@leanspec/ui 0.2.9-dev.20251205030455 → 0.2.10

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

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