@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/archived/022-flexible-folder-structure/README.md

@@ -1,794 +0,0 @@
----
-status: complete
-created: 2025-11-03
-completed: 2025-11-03
-tags: [core, ux]
-priority: high
----
-
-# Flexible Folder Structure System
-
-> Make spec organization configurable - support flat sequential (default), date-based, and custom patterns
-
-## Problem
-
-**Current state**: LeanSpec hard-codes `<date>/<NNN-short-name>/` structure
-- ✅ Good for chronological grouping
-- ❌ Too complex for small teams/solo devs
-- ❌ No flexibility for different workflows
-- ❌ Two-level nesting adds navigation overhead
-
-**Pain points:**
-- Solo devs don't need date-based grouping (frontmatter `created` is enough)
-- Teams want different patterns (sprint-based, milestone-based, flat)
-- Current structure feels over-engineered for simple use cases
-- References are verbose: `20251103/001-feature` vs `001-feature`
-
-## Proposal
-
-**Make folder structure configurable** with sensible defaults that align with LeanSpec's "lean" philosophy.
-
-### When Does Folder Structure Actually Matter?
-
-**The honest answer: It depends on your file browser usage patterns.**
-
-**If you reference specs primarily through:**
-- ✅ `lean-spec` commands → Structure doesn't matter (search/filter handles it)
-- ✅ IDE search/grep → Structure doesn't matter (tools find it)
-- ✅ GitHub PR links → Structure doesn't matter (direct links)
-
-**If you reference specs by:**
-- 📁 Browsing `specs/` in file explorer → Structure matters a lot
-- 👀 Visually scanning folders → Structure affects discoverability
-- 🗂️ Manual navigation → Structure impacts cognitive load
-
-### Supported Patterns
-
-#### 1. **Flat Sequential** (Default - Recommended)
-```
-specs/
-├── 001-typescript-cli-migration/
-├── 002-template-system-redesign/
-├── 011-docusaurus-vercel-migration/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "flat",
-    "sequenceDigits": 3
-  }
-}
-```
-
-**Optional: Add prefix to spec folders (still flat, just with naming)**
-```json
-{
-  "structure": {
-    "pattern": "flat",
-    "sequenceDigits": 3,
-    "prefix": "{YYYYMMDD}-"  // Optional prefix pattern
-  }
-}
-```
-
-**Examples with prefixes:**
-- `"prefix": "{YYYYMMDD}-"` → `20251103-001-feature/`
-- `"prefix": "{YYYY-MM}-"` → `2025-11-001-feature/`
-- `"prefix": "spec-"` → `spec-001-feature/`
-- No prefix (default) → `001-feature/`
-
-**Result with date prefix:**
-```
-specs/
-├── 20251031-001-typescript-cli-migration/
-├── 20251031-002-template-system-redesign/
-├── 20251103-003-flexible-folder-structure/
-└── archived/
-```
-
-**Pros:**
-- ✅ Simplest mental model (one flat list)
-- ✅ Minimal navigation (no nested folders)
-- ✅ Easy references: `lean-spec update 11` or just `011-docusaurus-vercel`
-- ✅ File explorer shows all specs at once
-- ✅ Works like GitHub issues (familiar pattern)
-- ✅ No cognitive overhead deciding "which folder?"
-- ✅ Optional prefix gives chronological sorting without nesting
-
-**Cons:**
-- ❌ Long list in file explorer if 100+ specs (mitigated by date prefix sorting)
-- ❌ Can't easily see "what was worked on in October?" (unless using date prefix)
-- ❌ Requires frontmatter `created` for timeline views (or use date prefix)
-
-**Best for:**
-- Solo developers
-- Small teams (< 50 specs)
-- Projects using `lean-spec` commands primarily
-- Teams who filter/search rather than browse
-- Anyone who wants chronological sorting without folder nesting
-
----
-
-#### 2. **Custom Pattern** (Flexible - Automatic Grouping)
-
-Any nested grouping structure extracted from frontmatter or date functions.
-
-##### Example A: Date-Based (Current LeanSpec behavior)
-```
-specs/
-├── 20251031/
-│   ├── 001-typescript-cli-migration/
-│   └── 002-template-system-redesign/
-├── 20251103/
-│   └── 003-flexible-folder-structure/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "custom",
-    "groupExtractor": "{YYYYMMDD}",
-    "sequenceDigits": 3
-  }
-}
-```
-
-**Built-in date functions:**
-- `{YYYYMMDD}` → `20251103`
-- `{YYYY-MM-DD}` → `2025-11-03`
-- `{YYYY-MM}` → `2025-11`
-- `{YYYY}` → `2025`
-
----
-
-##### Example B: Month-Based
-```
-specs/
-├── 2025-11/
-│   ├── 001-typescript-cli-migration/
-│   └── 011-docusaurus-vercel/
-├── 2025-12/
-│   └── 012-new-feature/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "custom",
-    "groupExtractor": "{YYYY-MM}",
-    "sequenceDigits": 3
-  }
-}
-```
-
----
-
-##### Example C: Milestone-Based
-```
-specs/
-├── milestone-1/
-│   ├── 001-feature-a/
-│   └── 002-feature-b/
-├── milestone-2/
-│   └── 003-feature-c/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "custom",
-    "groupExtractor": "milestone-{milestone}",
-    "groupFallback": "backlog",
-    "sequenceDigits": 3
-  }
-}
-```
-
----
-
-##### Example D: Sprint-Based
-```
-specs/
-├── sprint-14/
-├── sprint-15/
-│   ├── 023-checkout-flow/
-│   └── 024-payment-integration/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "custom",
-    "groupExtractor": "sprint-{sprint}",
-    "groupFallback": "backlog",
-    "sequenceDigits": 3
-  }
-}
-```
-
----
-
-##### Example E: Release-Based
-```
-specs/
-├── v1.0/
-├── v2.0/
-│   ├── 042-new-api/
-│   └── 043-breaking-changes/
-├── v3.0/
-└── archived/
-```
-
-**Config:**
-```json
-{
-  "structure": {
-    "pattern": "custom",
-    "groupExtractor": "v{version}",
-    "groupFallback": "upcoming",
-    "sequenceDigits": 3
-  }
-}
-```
-
----
-
-### Custom Pattern: How It Works
-
-**Automatic group extraction:**
-
-```yaml
-# User creates spec with custom field
----
-status: planned
-created: 2025-11-03
-milestone: 1  # ← This determines folder
----
-```
-
-```bash
-# LeanSpec automatically creates milestone-1/ folder
-lean-spec create feature-a --field milestone=1
-# → specs/milestone-1/001-feature-a/
-
-lean-spec create feature-b --field milestone=1
-# → specs/milestone-1/002-feature-b/
-
-lean-spec create feature-c --field milestone=2
-# → specs/milestone-2/003-feature-c/  # Auto-creates milestone-2/
-
-# Missing field uses fallback
-lean-spec create docs
-# → specs/backlog/004-docs/  # Uses groupFallback
-```
-
-**Built-in extractors:**
-- Date functions: `{YYYYMMDD}`, `{YYYY-MM-DD}`, `{YYYY-MM}`, `{YYYY}`, `{MM}`, `{DD}`
-- Frontmatter fields: `{fieldname}` → reads from `frontmatter.fieldname`
-- Combined: `{YYYY}/Q{quarter}` → `2025/Q4`
-
-**Pros:**
-- ✅ No manual folder management (auto-created)
-- ✅ Infinitely flexible (any grouping you want)
-- ✅ Semantic grouping (feature-related specs together)
-- ✅ Works with existing frontmatter fields
-- ✅ Date-based is just a special case
-
-**Cons:**
-- ❌ Two-level nesting
-- ❌ Need custom frontmatter fields for non-date grouping
-- ❌ Specs without field go to fallback folder
-- ❌ More complex config
-
-**Best for:**
-- Milestone/epic/sprint-based planning
-- Release-driven development
-- Time-boxed workflows (date/month grouping)
-- Large teams (100+ specs)
-- Teams with structured planning
-
----
-
-## Comparison Matrix
-
-| Pattern | Navigation | Discovery | Maintenance | Cognitive Load | Best Team Size |
-|---------|-----------|-----------|-------------|----------------|----------------|
-| **Flat** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | Solo - Small |
-| **Custom (Date)** | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | Medium - Large |
-| **Custom (Month)** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Small - Medium |
-| **Custom (Fields)** | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | Medium - Large |
-
-**Navigation**: How easy to browse to a spec  
-**Discovery**: How easy to find related specs  
-**Maintenance**: How much manual organization needed (auto-creation = better)  
-**Cognitive Load**: Mental effort to use the system
-
----
-
-## Design
-
-### Config Schema
-
-```typescript
-export interface LeanSpecConfig {
-  // ... other fields
-  structure: {
-    pattern: 'flat' | 'custom';
-    sequenceDigits: number;
-    defaultFile: string;
-    prefix?: string;         // For flat pattern: "{YYYYMMDD}-" or "spec-" (optional)
-    groupExtractor?: string; // For custom pattern: "{YYYYMMDD}" or "milestone-{milestone}"
-    groupFallback?: string;  // Fallback folder if field missing (only for non-date extractors)
-  };
-}
-```
-
-**Pattern behavior:**
-- `pattern: 'flat'` → Single level, optionally with `prefix` on folder names
-- `pattern: 'custom'` → Two levels with `groupExtractor` determining parent folder
-
-### Pattern Resolution Logic
-
-```typescript
-function resolveSpecPath(name: string, config: LeanSpecConfig, options?: CreateOptions): string {
-  const seq = await getGlobalNextSequence(config);
-  
-  if (config.structure.pattern === 'flat') {
-    // Flat pattern: optional prefix on folder name
-    const prefix = config.structure.prefix 
-      ? resolvePrefix(config.structure.prefix, options?.customFields)
-      : '';
-    return `${prefix}${seq}-${name}`;
-  }
-  
-  // Custom pattern - extract group from extractor string
-  const group = extractGroup(
-    config.structure.groupExtractor,
-    options?.customFields,
-    config.structure.groupFallback
-  );
-  
-  return `${group}/${seq}-${name}`;
-}
-
-function resolvePrefix(
-  prefix: string,  // e.g., "{YYYYMMDD}-" or "spec-"
-  fields?: Record<string, unknown>
-): string {
-  // Replace date functions
-  const dateReplacements = {
-    '{YYYYMMDD}': () => getToday('YYYYMMDD'),
-    '{YYYY-MM-DD}': () => getToday('YYYY-MM-DD'),
-    '{YYYY-MM}': () => getToday('YYYY-MM'),
-    '{YYYY}': () => new Date().getFullYear().toString(),
-    '{MM}': () => String(new Date().getMonth() + 1).padStart(2, '0'),
-    '{DD}': () => String(new Date().getDate()).padStart(2, '0'),
-  };
-  
-  let result = prefix;
-  
-  for (const [pattern, fn] of Object.entries(dateReplacements)) {
-    result = result.replace(pattern, fn());
-  }
-  
-  // Could also support frontmatter fields in prefix if needed
-  // For now, keep it simple with date functions only
-  
-  return result;
-}
-
-function extractGroup(
-  extractor: string,     // e.g., "{YYYYMMDD}" or "milestone-{milestone}"
-  fields?: Record<string, unknown>,
-  fallback?: string
-): string {
-  // Replace date functions
-  const dateReplacements = {
-    '{YYYYMMDD}': () => getToday('YYYYMMDD'),
-    '{YYYY-MM-DD}': () => getToday('YYYY-MM-DD'),
-    '{YYYY-MM}': () => getToday('YYYY-MM'),
-    '{YYYY}': () => new Date().getFullYear().toString(),
-    '{MM}': () => String(new Date().getMonth() + 1).padStart(2, '0'),
-    '{DD}': () => String(new Date().getDate()).padStart(2, '0'),
-  };
-  
-  let result = extractor;
-  
-  // Replace date functions first
-  for (const [pattern, fn] of Object.entries(dateReplacements)) {
-    result = result.replace(pattern, fn());
-  }
-  
-  // Replace frontmatter fields: {fieldname}
-  const fieldMatches = result.match(/\{([^}]+)\}/g);
-  if (fieldMatches) {
-    for (const match of fieldMatches) {
-      const fieldName = match.slice(1, -1); // Remove { }
-      const fieldValue = fields?.[fieldName];
-      
-      if (fieldValue === undefined) {
-        if (!fallback) {
-          throw new Error(`Custom field '${fieldName}' required but not provided`);
-        }
-        return fallback;
-      }
-      
-      result = result.replace(match, String(fieldValue));
-    }
-  }
-  
-  return result;
-}
-```
-
-**Examples:**
-```typescript
-// Flat with no prefix (default)
-resolveSpecPath("my-feature", { pattern: 'flat', sequenceDigits: 3 })
-// → "001-my-feature"
-
-// Flat with date prefix
-resolveSpecPath("my-feature", { 
-  pattern: 'flat', 
-  sequenceDigits: 3,
-  prefix: "{YYYYMMDD}-"
-})
-// → "20251103-001-my-feature"
-
-// Flat with custom prefix
-resolveSpecPath("my-feature", { 
-  pattern: 'flat', 
-  sequenceDigits: 3,
-  prefix: "spec-"
-})
-// → "spec-001-my-feature"
-
-// Custom with date grouping
-extractGroup("{YYYYMMDD}", {})
-// → "20251103"
-// Full path: "20251103/001-my-feature"
-
-// Custom with frontmatter grouping
-extractGroup("milestone-{milestone}", { milestone: 1 }, "backlog")
-// → "milestone-1"
-// Full path: "milestone-1/001-my-feature"
-```
-
-### Sequential Number Calculation
-
-**All patterns use global unique sequence numbers:**
-
-```typescript
-// Sequence always spans entire specs/ directory
-// This ensures unique IDs regardless of folder structure
-const seq = await getGlobalNextSeq(specsDir, config.structure.sequenceDigits);
-
-// Example:
-// specs/001-feature-a/
-// specs/002-feature-b/
-// specs/20251103/003-feature-c/  ← Still uses global sequence
-// specs/2025-11/004-feature-d/   ← Continues global sequence
-```
-
-**Why global sequences:**
-- ✅ Unique references: `lean-spec update 5` is unambiguous
-- ✅ Simple mental model: Numbers never repeat
-- ✅ Works like GitHub issues/PRs
-- ✅ No confusion when switching patterns
-- ✅ Archives don't break references
-
-**Implementation:**
-```typescript
-async function getGlobalNextSeq(specsDir: string, digits: number): Promise<string> {
-  // Scan ALL subdirectories recursively for NNN- pattern
-  const allSpecs = await loadAllSpecs();
-  const seqNumbers = allSpecs
-    .map(spec => parseInt(spec.name.match(/^(\d+)-/)?.[1] || '0', 10))
-    .filter(n => !isNaN(n) && n > 0);
-  
-  const maxSeq = seqNumbers.length > 0 ? Math.max(...seqNumbers) : 0;
-  return String(maxSeq + 1).padStart(digits, '0');
-}
-```
-
-### Migration Strategy
-
-**Default for new projects:** `flat`
-
-**Existing projects:** Keep current structure unless explicitly changed
-
-**Config migration:**
-```typescript
-// On lean-spec init, detect existing structure
-const hasDateDirs = await detectDateDirectories(specsDir);
-
-if (hasDateDirs) {
-  config.structure.pattern = 'date'; // Preserve existing
-} else {
-  config.structure.pattern = 'flat'; // Use new default
-}
-```
-
-### Spec References
-
-Commands should support multiple reference formats:
-
-```bash
-# By number (works for all patterns)
-lean-spec update 11 --status complete
-
-# By name (searches across all groups)
-lean-spec update flexible-folder-structure --status complete
-
-# By full path (explicit)
-lean-spec update 20251103/001-flexible-folder-structure --status complete
-```
-
-Existing `resolveSpecPath()` handles this already!
-
-## Implementation Plan
-
-### Phase 1: Config Schema ✅
-- [x] Update `LeanSpecConfig` interface with `pattern` field
-- [x] Add pattern validation
-- [x] Set default to `flat` for new projects
-- [x] Detect existing structure on init
-
-### Phase 2: Path Resolution ✅
-- [x] Refactor `create.ts` to use pattern-based paths
-- [x] Update `getNextSeq()` to handle flat vs grouped
-- [x] Test all patterns with sequential numbering
-
-### Phase 3: Command Updates ⚠️
-- [x] Update `create` command
-- [x] Update `list` command (group display logic) - **Minor issue: still hardcoded to date grouping**
-- [x] Update `board` command
-- [x] Update `search` command
-- [x] Update `archive` command
-
-### Phase 4: Migration Tools ✅
-- [x] Add `normalizeLegacyPattern()` to convert patterns automatically
-- [x] Detect current structure automatically
-- [x] Warn about breaking changes
-
-### Phase 5: Documentation ⚠️
-- [ ] Update README with pattern examples
-- [ ] Add pattern selection to `lean-spec init` wizard
-- [ ] Document migration guide
-- [x] Update template configs - **Issue: Templates still use legacy format**
-
-### Phase 6: Testing ✅
-- [x] Integration tests for all patterns
-- [x] Test sequential number consistency
-- [x] Test spec resolution across patterns
-- [x] Test migration between patterns
-
-## Files to Modify
-
-### Core
-- `src/config.ts` - Add pattern field, update schema
-- `src/commands/create.ts` - Pattern-based path resolution
-- `src/utils/path-helpers.ts` - Update `getNextSeq()`, `resolveSpecPath()`
-- `src/spec-loader.ts` - Handle different directory structures
-
-### Commands
-- `src/commands/list.ts` - Group display by pattern
-- `src/commands/board.ts` - Pattern-aware grouping
-- `src/commands/search.ts` - Search across patterns
-- `src/commands/archive.ts` - Archive to pattern-agnostic location
-- `src/commands/init.ts` - Pattern selection wizard
-
-### New Commands
-- `src/commands/migrate.ts` - Convert between patterns
-
-### Tests
-- `src/integration.test.ts` - Add pattern scenarios
-- `src/commands.test.ts` - Test all patterns
-
-### Templates
-- `templates/*/config.json` - Add pattern field with defaults
-
-### Documentation
-- `README.md` - Show pattern examples
-- `docs-site/docs/guide/getting-started.md` - Pattern selection
-- `docs-site/docs/reference/config.md` - Pattern reference
-
-## Success Criteria
-
-- [x] New projects default to flat pattern
-- [x] Existing projects preserve date-based structure
-- [x] All 4 patterns (flat, date, month, custom) work correctly
-- [x] Sequential numbering consistent within each pattern
-- [x] Spec references work across all patterns
-- [x] Migration between patterns doesn't break links
-- [ ] `lean-spec init` offers pattern selection
-- [ ] Documentation covers all patterns
-- [x] Zero breaking changes for existing users
-
-## Implementation Status
-
-**Status: ✅ COMPLETE** (2025-11-03)
-
-### ✅ What's Working
-
-1. **Core Implementation**
-   - Config schema with `pattern`, `prefix`, `groupExtractor`, `groupFallback` fields
-   - `resolvePrefix()` and `extractGroup()` functions for path resolution
-   - `getGlobalNextSeq()` for global unique sequence numbers
-   - `normalizeLegacyPattern()` for backward compatibility
-
-2. **Pattern Support**
-   - ✅ Flat pattern (default)
-   - ✅ Flat with date prefix (`{YYYYMMDD}-`)
-   - ✅ Flat with custom prefix (`spec-`)
-   - ✅ Custom pattern with date grouping (`{YYYYMMDD}`, `{YYYY-MM}`, etc.)
-   - ✅ Custom pattern with field grouping (`milestone-{milestone}`)
-
-3. **Commands**
-   - ✅ `create` - Fully pattern-aware
-   - ✅ `archive` - Archives to flat `specs/archived/`
-   - ✅ `update` - Resolves specs across patterns
-   - ✅ `board` - Pattern-agnostic
-   - ✅ `search` - Pattern-agnostic
-
-4. **Testing**
-   - ✅ 10 tests covering all patterns
-   - ✅ All 98 tests passing
-   - ✅ Flat pattern tests (3)
-   - ✅ Custom date grouping tests (3)
-   - ✅ Custom field grouping tests (3)
-   - ✅ Legacy compatibility test (1)
-
-### ⚠️ Minor Issues
-
-1. **`list.ts` hardcoded date grouping**
-   - Lines 64-65: `const dateMatch = spec.path.match(/^(\d{8})\//)`
-   - Currently assumes date-based structure for grouping
-   - **Impact**: Display grouping doesn't adapt to pattern
-   - **Fix needed**: Make grouping pattern-aware or add `--no-grouping` flag
-
-2. **Template configs use legacy format**
-   - All templates (`minimal`, `standard`, `enterprise`) use: `"pattern": "{date}/{seq}-{name}/"`
-   - Works via `normalizeLegacyPattern()` but inconsistent
-   - **Fix needed**: Update to `"pattern": "flat"` or `"pattern": "custom", "groupExtractor": "{YYYYMMDD}"`
-
-### 📋 Remaining Work (Optional Polish)
-
-1. **Pattern selection wizard in `lean-spec init`**
-   - Currently line 72-74 shows TODO for custom setup flow
-   - Would improve UX to let users choose pattern during init
-
-2. **Documentation updates**
-   - Add pattern examples to README
-   - Document all supported patterns
-   - Migration guide for switching patterns
-
-3. **Enhanced `list` command**
-   - Smart grouping based on active pattern
-   - `--flat` flag for ungrouped list view
-
-### 🎯 Verification Results
-
-**Test Run**: All tests passing (98/98)
-- Flexible Folder Structure: 10/10 ✅
-- Integration tests: 5/5 ✅
-- Command tests: 30/30 ✅
-- Other tests: 53/53 ✅
-
-**Files Modified**:
-- ✅ `src/config.ts` - Schema + helper functions
-- ✅ `src/commands/create.ts` - Pattern-based creation
-- ✅ `src/commands/archive.ts` - Flat archive structure
-- ✅ `src/utils/path-helpers.ts` - Global sequence + resolution
-- ✅ `src/commands.test.ts` - Comprehensive test coverage
-
-**Backward Compatibility**: ✅ Zero breaking changes
-- Legacy patterns auto-converted
-- Existing date-based projects continue working
-- Archive behavior consistent
-
-## Open Questions
-
-1. **~~Should flat pattern use global sequence or allow resets?~~**
-   - ✅ **Resolved**: Global unique sequence for all patterns
-   - Ensures unique references and simple mental model
-
-2. **~~Custom pattern syntax:~~**
-   - ✅ **Resolved**: Extract from frontmatter fields automatically
-   - Pattern: `"milestone-{milestone}"` reads `frontmatter.milestone`
-   - Supports any custom field defined in config
-
-3. **~~What should happen if custom field is missing?~~**
-   - ✅ **Resolved**: Use fallback folder configured in `groupFallback`
-   - Example: `"groupFallback": "backlog"` → specs go to `specs/backlog/`
-   - Keeps workflow smooth without errors
-
-4. **~~Archive behavior across patterns:~~**
-   - ✅ **Resolved**: All patterns archive to `specs/archived/` (flat structure)
-   - **Why flat in archived**: Archived specs don't need organizational structure
-   - Simplifies discovery: all archived specs in one place
-   - Example: `specs/archived/001-old-feature/`, `specs/archived/042-deprecated/`
-
-5. **~~What happens when switching patterns?~~**
-   - ✅ **Resolved**: Legacy patterns auto-converted via `normalizeLegacyPattern()`
-   - Old structure remains, new specs use new pattern
-   - No manual migration required
-   - Backward compatible
-
-6. **Display in `lean-spec list` for flat pattern:**
-   - ⚠️ **Partially Resolved**: Currently hardcoded to date grouping
-   - **Options considered**:
-     - Group by month from frontmatter `created` ✓ (best for chronological view)
-     - Flat list with `--no-grouping` flag ✓ (best for simplicity)
-     - Both: smart default + flag override
-   - **Recommendation**: Add `--flat` flag, default to month grouping from frontmatter
-
-## Why This Matters
-
-**Aligns with LeanSpec philosophy:**
-- ✅ Simple default (flat) for 80% of users
-- ✅ Flexible enough for complex workflows
-- ✅ Progressive complexity (start simple, add structure when needed)
-- ✅ No forced overhead
-
-**Competitive advantage:**
-- Other SDD tools force their structure
-- LeanSpec adapts to YOUR workflow
-
-**User experience:**
-- Easier references: `lean-spec update 5` vs `lean-spec update 20251103/001-feature`
-- Less navigation overhead
-- Familiar pattern (like GitHub issues)
-- Still supports chronological grouping when needed
-
----
-
-## Implementation Notes
-
-### Key Design Decisions
-
-1. **Global Sequence Numbers**
-   - All patterns share a single sequence counter
-   - Prevents ID conflicts when switching patterns
-   - Familiar mental model (like GitHub issues)
-   - Implementation: `getGlobalNextSeq()` scans recursively
-
-2. **Backward Compatibility**
-   - `normalizeLegacyPattern()` converts old format automatically
-   - Legacy: `"{date}/{seq}-{name}/"` → New: `pattern: "custom", groupExtractor: "{YYYYMMDD}"`
-   - Zero breaking changes for existing users
-
-3. **Archive Strategy**
-   - All patterns archive to flat `specs/archived/`
-   - Simplifies discovery and reduces complexity
-   - Archived specs don't need organizational structure
-
-4. **Pattern-Agnostic Resolution**
-   - `resolveSpecPath()` finds specs by number, name, or path
-   - Works across all patterns seamlessly
-   - Supports multiple reference formats: `5`, `001-feature`, `milestone-1/001-feature`
-
-### Performance Considerations
-
-- `getGlobalNextSeq()` scans entire specs directory
-- Performance impact minimal for < 1000 specs
-- Could cache sequence number if needed (future optimization)
-
-### Testing Strategy
-
-- Comprehensive integration tests for each pattern
-- Test global sequence consistency across patterns
-- Test legacy pattern conversion
-- Test archive behavior
-- Test spec resolution across patterns