@leanspec/ui 0.2.6-dev.20251125010539 → 0.2.6

package/.next/standalone/packages/ui/dist/standalone/specs/018-spec-validation/VALIDATION-RULES.md

@@ -0,0 +1,327 @@
+# Validation Rules
+
+This document details what gets validated by `lean-spec validate` and the specific rules for each validation type.
+
+**Note:** This spec originally proposed expanding `lean-spec check`, but the implementation created `lean-spec validate` as a separate command.
+
+## Implementation Status
+
+- ✅ **Line Count Validation** - Phase 1a Complete
+- ✅ **Frontmatter Validation** - Phase 1b Complete
+- ⏳ **Structure Validation** - Phase 2 (Planned)
+- ⏳ **Corruption Detection** - Phase 3 (High Priority)
+- ⏳ **Sub-Spec Validation** - Phase 3.5 (High Priority)
+- ⏳ **Content Validation** - Phase 4 (Optional)
+- ⏳ **Staleness Detection** - Phase 5 (Optional)
+
+---
+
+## Line Count Validation ✅
+
+**Status:** Implemented in Phase 1a
+
+**Thresholds:**
+- **Warning**: 300-400 lines (approaching limit)
+- **Error**: >400 lines (exceeds limit)
+- **Configurable**: `--max-lines` flag to customize limit
+
+**Rationale:**
+Enforces **Context Economy** principle - specs must fit in working memory (human and AI). Files >400 lines become difficult to read, edit, and maintain.
+
+**Suggestions:**
+- Warns: "Consider simplification or splitting"
+- Errors: "Consider splitting into sub-specs using spec 012 pattern"
+
+---
+
+## Frontmatter Validation ✅
+
+**Status:** Implemented in Phase 1b (27 tests passing)
+
+**Required Fields:**
+- `status` - Must be present
+- `created` - Must be present
+
+**Status Values:**
+- Valid: `planned`, `in-progress`, `complete`, `archived`
+- Invalid: Any other value (e.g., `wip`, `draft`, `done`)
+
+**Priority Values:**
+- Valid: `low`, `medium`, `high`, `critical`
+- Optional field, but if present must be valid
+
+**Date Formats:**
+- ISO 8601 format (YYYY-MM-DD or full ISO timestamp)
+- `created` field must be valid date
+- Other date fields (if present) must be valid
+
+**Tags:**
+- Must be array of strings
+- Example: `["quality", "validation", "cli"]`
+
+**Custom Fields:**
+- If config schema defined, custom fields must match
+- Type validation based on config
+
+## Structure Validation
+
+**File Requirements:**
+- `README.md` must exist in spec directory
+- Frontmatter must be valid YAML
+- Must have title (H1 heading: `# Title`)
+
+**Section Requirements:**
+- Required sections based on template
+- Typically: Overview, Design, Plan, Test
+- No empty required sections (content beyond just comment)
+- No duplicate section headers at same level
+
+## Sub-Spec Validation
+
+**File Naming Conventions (from spec 012):**
+- Sub-spec files should follow recommended naming patterns
+- Standard names: `DESIGN.md`, `IMPLEMENTATION.md`, `TESTING.md`, `API.md`, `ARCHITECTURE.md`, `MIGRATION.md`, `CONFIGURATION.md`, etc.
+- Custom names allowed but should be descriptive (e.g., `PHASE1.md`, `RESEARCH.md`)
+- Assets should be in `assets/` subdirectory
+
+**README.md Integration:**
+- Main `README.md` should reference all sub-spec files
+- Links can be in any section (Overview, Design, etc.)
+- Missing links to sub-specs generate warnings
+- Example: `[Testing Strategy](TESTING.md)` or `See [DESIGN.md](DESIGN.md)`
+
+**Line Count Per Sub-Spec (Context Economy):**
+- Each sub-spec file should be < 400 lines (error threshold)
+- Warning at 300 lines (same as main spec)
+- Rationale: Context Economy applies to each file independently
+- Sub-specs exist to split complexity - they shouldn't become bloated
+
+**Orphan Detection:**
+- Detect sub-spec markdown files not referenced from README.md
+- Warn about orphaned sub-specs (may be deprecated)
+- Exception: README.md itself is never orphaned
+- Assets (.png, .svg, etc.) are checked separately
+
+**Cross-Document Validation:**
+- Validate internal links between sub-specs work correctly
+- Check relative paths are correct
+- Detect circular references (if spec A links to B, B to C, C to A)
+
+**Sub-Spec Structure:**
+- Each sub-spec should have clear heading structure
+- Should include backlink to main spec (recommended)
+- Example: `> Part of spec: [018-spec-validation](README.md)`
+
+## Content Validation
+
+**Minimum Requirements:**
+- Spec must have minimum content length (avoid stub specs)
+- Default: 100 characters (configurable)
+
+**Quality Checks:**
+- No TODO/FIXME in complete specs
+- Internal links should be valid (no broken references)
+- No placeholder text in complete specs
+
+## Corruption Detection
+
+**Duplicate Content:**
+- No duplicate section headers at same level
+- Detect sections appearing multiple times
+- Example: "## Plan" appearing twice in same spec
+
+**Code Block Validation:**
+- All code blocks properly closed (unclosed blocks break syntax highlighting)
+- Matching number of opening ``` and closing ```
+- This is the #1 indicator of corruption humans notice visually
+
+**Formatting Validation:**
+- Unclosed bold formatting (**) in actual content
+- Unclosed italic formatting (*) in actual content
+- Excludes code blocks, inline code, and list markers from checks
+- Only validates markdown content outside code fences
+
+**Duplicate Content Detection:**
+- Detects duplicated content blocks (5+ consecutive lines, 100+ chars)
+- Excludes code blocks to prevent false positives from code examples
+- Tuned to reduce noise: was 3 lines/50 chars (too sensitive)
+- Helps find merge artifacts and failed edits
+- Warnings only (not errors) as some duplication is intentional
+
+**Intentionally Excluded:**
+- ❌ JSON/YAML validation in code blocks (examples often show invalid syntax)
+- ❌ Table and list structure validation (too noisy, not actual corruption)
+
+**Sub-Spec Duplication:**
+- Detect if same content appears in multiple sub-specs
+- Warn about significant content overlap between files
+- Helps identify when content should be consolidated
+
+### Corruption Detection Philosophy
+
+**Focus on visually apparent corruption:**
+- What breaks rendering (unclosed code blocks, unclosed formatting)
+- What humans actually notice when reading specs
+- Not semantic issues or style preferences
+
+**Why we exclude certain checks:**
+- JSON/YAML in code blocks: Examples intentionally show invalid syntax
+- Duplicate content detection: Many false positives from boilerplate/templates
+- Table/list validation: Too noisy, rarely indicates actual corruption
+
+**Tuning for signal-to-noise:**
+- Originally: 3 lines, 50 chars → 13 duplicate warnings across all specs
+- Improved: 5 lines, 100 chars, exclude code blocks → More targeted detection
+- Goal: Only flag genuine corruption, not common patterns
+
+## Staleness Detection
+
+**In-Progress Specs:**
+- Warn if status is `in-progress` for > 30 days
+- Suggests spec might be stalled
+
+**No Updates:**
+- Warn if no updates in > 90 days
+- Based on git history or file mtime
+- Suggests spec might be abandoned
+
+**Planned Specs:**
+- Warn if status is `planned` for > 60 days
+- Suggests planning without execution
+
+**Archived Specs:**
+- No staleness warnings for archived specs
+- Archived specs are expected to be static
+
+## Auto-Fix Capabilities
+
+### Fixable Issues
+
+**Frontmatter:**
+- Add missing required fields (use defaults)
+- Format dates to ISO 8601 standard
+- Sort frontmatter fields alphabetically
+- Update visual badges to match frontmatter
+
+**Structure:**
+- Add missing required sections (as comments)
+- Remove duplicate sections (keep first occurrence)
+- Close unclosed code blocks (where unambiguous)
+
+**Sub-Specs:**
+- Add missing links to sub-specs in README.md
+- Generate suggested backlinks for sub-specs
+- Create "Documentation Structure" section if missing (when sub-specs exist)
+
+### Non-Fixable Issues
+
+These require manual intervention:
+- Invalid status/priority values (requires decision)
+- Empty required sections (requires content)
+- Broken links (requires investigation)
+- Stale specs (requires status update or work)
+- Complex corruption (requires human judgment)
+
+## Error Severity Levels
+
+**Error (blocks passing):**
+- Missing required fields
+- Invalid status/priority values
+- Duplicate sections
+- Corrupted code blocks
+- Invalid JSON/YAML syntax
+- Malformed markdown structure
+
+**Warning (passes with warning):**
+- Stale specs
+- Suggested improvements
+- Minor formatting issues
+- Empty optional sections
+
+**Info (informational):**
+- Best practice suggestions
+- Style recommendations
+- Optimization hints
+
+## Validation Rules Configuration
+
+Rules can be customized in `.lean-spec/config.json`:
+
+```json
+{
+  "check": {
+    "rules": {
+      "frontmatter": {
+        "required": ["status", "created"],
+        "allowedStatus": ["planned", "in-progress", "complete", "archived"],
+        "allowedPriority": ["low", "medium", "high", "critical"]
+      },
+      "structure": {
+        "requireReadme": true,
+        "requiredSections": ["Overview", "Design", "Plan"],
+        "forbidEmptySections": true
+      },
+      "content": {
+        "minLength": 100,
+        "forbidTodoInComplete": true,
+        "validateLinks": true
+      },
+      "corruption": {
+        "detectDuplicateSections": true,
+        "validateCodeBlocks": true,
+        "validateJsonYaml": true,
+        "detectFragments": true
+      },
+      "staleness": {
+        "inProgressMaxDays": 30,
+        "noUpdateMaxDays": 90,
+        "plannedMaxDays": 60
+      },
+      "subSpecs": {
+        "validateNaming": true,
+        "requireReferences": true,
+        "detectOrphans": true,
+        "maxLinesPerFile": 400,
+        "warnLinesPerFile": 300,
+        "validateCrossReferences": true,
+        "standardNames": [
+          "DESIGN.md",
+          "IMPLEMENTATION.md",
+          "TESTING.md",
+          "API.md",
+          "ARCHITECTURE.md",
+          "MIGRATION.md",
+          "CONFIGURATION.md"
+        ]
+      }
+    }
+  }
+}
+```
+
+## Why These Rules?
+
+**Frontmatter:**
+- Ensures specs are trackable and categorizable
+- Required fields enable automation and reporting
+- Valid values prevent typos and inconsistencies
+
+**Structure:**
+- Maintains consistency across team
+- Makes specs easier to navigate
+- Enables automated processing
+
+**Content:**
+- Prevents stub specs from cluttering project
+- Ensures specs are complete before marking done
+- Maintains quality standards
+
+**Corruption:**
+- Catches errors from failed AI edits
+- Prevents shipping broken specs
+- Early detection saves debugging time
+
+**Staleness:**
+- Identifies abandoned work
+- Prompts status updates
+- Keeps project health visible

package/.next/standalone/packages/ui/dist/standalone/specs/024-pattern-aware-list-grouping/README.md

@@ -0,0 +1,117 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - ux
+  - polish
+  - v0.2.0
+priority: high
+related:
+  - 043-official-launch-02
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:43:43.501Z'
+completed_at: '2025-11-05T05:43:43.501Z'
+completed: '2025-11-05'
+transitions:
+  - status: complete
+    at: '2025-11-05T05:43:43.501Z'
+---
+
+# Pattern-Aware List Grouping
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: ux, polish, v0.2.0
+
+
+> Make `lean-spec list` adapt to flat vs date-grouped folder patterns
+
+## Overview
+
+Currently `list.ts` has hardcoded date grouping logic that assumes the `{YYYYMMDD}/{NNN}-{name}/` pattern. When users configure flat patterns like `{NNN}-{name}/` or custom patterns, the list command still tries to group by date, which doesn't make sense.
+
+**Issue:** List command doesn't adapt to configured folder pattern.
+
+**Solution:** Detect pattern type and adjust grouping accordingly.
+
+## Design
+
+Make `lean-spec list` respect the configured folder pattern:
+
+1. **For date-grouped patterns** (contains `{YYYYMMDD}/`):
+   - Group by date as it does now
+   - Show date headers
+
+2. **For flat patterns**:
+   - Show flat list, no date grouping
+   - Or group by prefix if present
+
+3. **For custom patterns**:
+   - Adapt based on pattern structure
+   - Default to flat list if unclear
+
+**Implementation:**
+- Read `folderPattern` from config
+- Detect if pattern includes date component
+- Adjust grouping logic in `list.ts` accordingly
+
+## Plan
+
+**Status (2025-11-05):** ✅ Complete - Implemented pattern detection utility and updated list command
+
+- [x] Extract grouping logic from `list.ts`
+- [x] Add pattern detection utility
+- [x] Implement adaptive grouping
+- [x] Add tests for flat/date/custom patterns
+- [x] Update documentation
+
+**Implementation Notes:**
+- Makes list command respect configured folder patterns
+- Fixes hardcoded date grouping assumption
+- Improves UX for users with flat or custom patterns
+- Part of spec 043 launch preparation
+- Estimated: 2-3 hours implementation
+- Works with spec 026 (pattern selection during init)
+
+**Technical Approach:**
+1. Read `folderPattern` from `.lean-spec/config.json`
+2. Detect if pattern contains `{YYYYMMDD}/` for date grouping
+3. Apply appropriate grouping strategy in list output
+4. Maintain backward compatibility
+
+## Implementation (2025-11-05)
+
+**Created new utility module:** `src/utils/pattern-detection.ts`
+- Exports `detectPatternType()` function that returns explicit pattern type
+- Pattern types: `flat`, `date-grouped`, or `custom-grouped`
+- Helper functions: `isDateGroupedPattern()`, `shouldGroupSpecs()`
+- Makes the logic testable and reusable
+
+**Updated list command:** `src/commands/list.ts`
+- Replaced inline pattern detection with utility function
+- Clearer intent: detect pattern type, then decide rendering strategy
+- Maintains full backward compatibility
+
+**Test coverage:**
+- 14 unit tests for pattern-detection utility
+- 4 integration tests for list command:
+  - Flat pattern → flat list
+  - Date-grouped pattern → grouped by date
+  - Custom-grouped pattern → grouped by custom field (e.g., milestone)
+  - Flat with date prefix → flat list (prefix in name, not folder)
+- All 261 tests pass
+
+**Files changed:**
+- `src/utils/pattern-detection.ts` (new)
+- `src/utils/pattern-detection.test.ts` (new)
+- `src/list-integration.test.ts` (new)
+- `src/commands/list.ts` (updated)
+
+## Test
+
+- [x] List command adapts to configured pattern
+- [x] Date grouping works for date-grouped patterns
+- [x] Flat list works for flat patterns
+- [x] No breaking changes to existing behavior
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.

package/.next/standalone/packages/ui/dist/standalone/specs/025-template-config-updates/README.md

@@ -0,0 +1,73 @@
+---
+status: planned
+created: 2025-11-03
+tags: [templates, polish]
+priority: low
+---
+
+# Template Config Updates
+
+> Update all template configs to use new format consistently
+
+## Overview
+
+The built-in templates (minimal, standard, enterprise) in `templates/` still use the legacy config format. They work fine but are inconsistent with the new flexible folder structure config format introduced in spec 20251103/001.
+
+**Issue:** Templates use old config format.
+
+**Solution:** Update all template `config.json` files to new format with `folderPattern`.
+
+## Design
+
+Update templates to use new config format:
+
+**Current format (legacy):**
+```json
+{
+  "specDir": "specs"
+}
+```
+
+**New format:**
+```json
+{
+  "specDir": "specs",
+  "folderPattern": "{YYYYMMDD}/{NNN}-{name}/",
+  "prefix": "",
+  "frontmatter": {
+    "required": ["status", "created"],
+    "custom": {}
+  }
+}
+```
+
+**Templates to update:**
+- `templates/minimal/config.json`
+- `templates/standard/config.json`
+- `templates/enterprise/config.json`
+
+Each template should have a sensible default `folderPattern`:
+- **Minimal**: Flat pattern `{NNN}-{name}/` (simplest)
+- **Standard**: Date-grouped `{YYYYMMDD}/{NNN}-{name}/` (prevents conflicts)
+- **Enterprise**: Date-grouped `{YYYYMMDD}/{NNN}-{name}/` (team workflows)
+
+## Plan
+
+- [ ] Update `templates/minimal/config.json`
+- [ ] Update `templates/standard/config.json`
+- [ ] Update `templates/enterprise/config.json`
+- [ ] Test template creation with new configs
+- [ ] Update template README files if needed
+
+## Test
+
+- [ ] All templates use new config format
+- [ ] `lean-spec init` works with each template
+- [ ] Config merging works correctly
+- [ ] Backward compatibility maintained
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.
+
+Low priority since legacy format still works, but good for consistency.

package/.next/standalone/packages/ui/dist/standalone/specs/026-init-pattern-selection/README.md

@@ -0,0 +1,109 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - ux
+  - init
+  - v0.2.0
+priority: high
+related:
+  - 043-official-launch-02
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:44:40.533Z'
+completed_at: '2025-11-05T05:44:40.533Z'
+completed: '2025-11-05'
+transitions:
+  - status: complete
+    at: '2025-11-05T05:44:40.533Z'
+---
+
+# Init Pattern Selection
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: ux, init, v0.2.0
+
+
+> Let users choose folder pattern during `lean-spec init`
+
+## Overview
+
+Currently when running `lean-spec init`, users can only choose a template (minimal/standard/enterprise). The folder pattern is set by the template and users must manually edit `.lean-spec/config.json` to change it.
+
+**Issue:** No way to choose folder pattern during initialization.
+
+**Solution:** Add pattern selection step to init wizard.
+
+## Design
+
+Enhance the `lean-spec init` wizard to offer pattern choices:
+
+**Current flow:**
+1. Choose template (minimal/standard/enterprise)
+2. Confirm → Done
+
+**New flow:**
+1. Choose template (minimal/standard/enterprise)
+2. Choose folder pattern:
+   - `{YYYYMMDD}/{NNN}-{name}/` (Date-grouped - recommended for teams)
+   - `{YYYYMMDD}-{NNN}-{name}/` (Flat with date prefix)
+   - `{NNN}-{name}/` (Simple sequential)
+   - Custom (enter your own)
+3. Confirm → Done
+
+**UI mockup:**
+```bash
+$ lean-spec init
+
+? Select a template:
+  ❯ standard
+    minimal
+    enterprise
+
+? Select folder pattern:
+  ❯ Date-grouped: 20251103/001-my-spec/ (recommended for teams)
+    Flat with date: 20251103-001-my-spec/
+    Simple: 001-my-spec/
+    Custom pattern
+```
+
+**Implementation:**
+- Add pattern selection prompt to `init.ts`
+- Override template's `folderPattern` in generated config
+- Provide sensible descriptions for each pattern
+- Default to date-grouped (current best practice)
+
+## Plan
+
+**Status (2025-11-04):** Ready to implement - part of Phase 2 UX improvements for v0.2.0
+
+- [ ] Add pattern selection to init wizard
+- [ ] Update init command to handle pattern choice
+- [ ] Add pattern override logic
+- [ ] Update documentation
+- [ ] Add tests for pattern selection
+
+**Implementation Notes:**
+- Straightforward UX enhancement to init flow
+- Improves onboarding by eliminating manual config edits
+- Part of spec 043 launch preparation
+- Estimated: 3-4 hours implementation
+- No blocking dependencies
+
+**Testing Priority:**
+- Pattern selection UI is intuitive
+- Selected pattern correctly overrides template default
+- Custom pattern validation works
+- Backward compatibility maintained
+
+## Test
+
+- [ ] Init wizard offers pattern choices
+- [ ] Selected pattern overrides template default
+- [ ] Custom pattern option works
+- [ ] Default pattern is date-grouped
+- [ ] Backward compatibility (skip pattern selection if not needed)
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.
+
+This improves onboarding by letting users choose the right pattern upfront instead of requiring manual config edits.