@leanspec/ui 0.2.6-dev.20251125010539 → 0.2.6

package/.next/standalone/packages/ui/dist/standalone/specs/018-spec-validation/CLI-DESIGN.md

@@ -0,0 +1,380 @@
+# CLI Design
+
+Command-line interface for the `lean-spec validate` command.
+
+**Note:** This spec originally proposed expanding `lean-spec check`, but the implementation created a separate `lean-spec validate` command for comprehensive quality validation, while keeping `lean-spec check` focused on sequence conflicts.
+
+## Basic Usage
+
+### Current Implementation (v0.2.0)
+
+```bash
+# Validate all specs (runs: line count + frontmatter)
+lean-spec validate
+
+# Validate specific specs
+lean-spec validate 018
+lean-spec validate 043 048 018          # Multiple specs
+
+# Custom line limit
+lean-spec validate --max-lines 500
+lean-spec validate 018 --max-lines 300
+
+# For sequence conflicts (separate command)
+lean-spec check
+```
+
+### Planned Enhancements (v0.3.0+)
+
+```bash
+# Validate specific aspects
+lean-spec validate --frontmatter        # Only frontmatter validation
+lean-spec validate --structure          # Only structure validation
+lean-spec validate --content            # Only content validation
+lean-spec validate --corruption         # Only corruption detection
+lean-spec validate --staleness          # Only staleness detection
+lean-spec validate --sub-specs          # Only sub-spec validation
+
+# Combine validations
+lean-spec validate --frontmatter --structure
+lean-spec validate --sub-specs --structure  # Check sub-specs and main structure
+
+# Skip certain checks
+lean-spec validate --no-staleness       # Skip staleness warnings
+
+# Filter which specs to validate
+lean-spec validate --status=in-progress
+lean-spec validate --tag=api
+```
+
+## Output Options
+
+```bash
+# Output formatting
+lean-spec validate --format=json        # JSON output for CI
+lean-spec validate --quiet              # Brief output (errors only)
+lean-spec validate --verbose            # Detailed output with explanations
+
+# Behavior options
+lean-spec validate --strict             # Fail on warnings (not just errors)
+lean-spec validate --fix                # Auto-fix issues where possible
+```
+
+## Command Evolution
+
+### Current Implementation (v0.2.0+)
+
+Two separate commands with distinct purposes:
+
+```bash
+lean-spec check               # Fast sequence conflict detection
+lean-spec validate            # Comprehensive quality validation
+lean-spec validate [specs...] # Validate specific specs
+```
+
+### Planned Enhancements (v0.3.0+)
+
+Expand `lean-spec validate` with additional validation rules:
+
+```bash
+lean-spec validate --all           # All validation rules
+lean-spec validate --frontmatter   # Frontmatter validation
+lean-spec validate --structure     # Structure validation
+lean-spec validate --corruption    # Corruption detection
+```
+
+## Console Output Format
+
+### Current Output (v0.2.0)
+
+**Actual output format:**
+```
+Validating specs...
+
+Line Count:
+  ✓ 018-spec-validation (255 lines)
+  ⚠ 051-docs-system-prompt-principles (340 lines - approaching limit)
+     → Consider simplification or splitting
+  ✗ 048-spec-complexity-analysis (601 lines - exceeds limit!)
+     → Spec exceeds 400 lines (601 lines)
+     → Consider splitting into sub-specs using spec 012 pattern
+
+Frontmatter:
+  ✓ All 25 spec(s) passed
+
+Results: 25 specs validated, 3 error(s), 6 warning(s)
+```
+
+**Features:**
+- Groups results by validator type (Line Count, Frontmatter, etc.)
+- Clear pass/warn/error indicators (✓ ⚠ ✗)
+- Actionable suggestions for each issue
+- Summary with counts
+
+### Planned Output (v0.3.0+)
+
+```
+📋 Validating specs...
+
+Line Count:
+  ✓ 10 specs within limits
+  ⚠ 1 spec approaching limit (300-400 lines)
+  ✗ 1 spec exceeds limit (>400 lines)
+
+Frontmatter:
+  ✗ 1 spec has errors:
+    - specs/044-spec-relationships-clarity/
+      • Missing required field: created
+      • Invalid status: "wip"
+
+Structure:
+  ✗ 1 spec has errors:
+    - specs/044-spec-relationships-clarity/
+      • Missing required section: ## Testing
+
+Sub-Specs:
+  ⚠ 2 warnings:
+    - specs/018-spec-validation/
+      ⚠ Sub-spec TESTING.md (421 lines) exceeds 400 line limit
+      ⚠ Orphaned sub-spec: DEPRECATED.md (not linked from README.md)
+  ✓ All other specs with sub-specs are valid
+
+Corruption:
+  ✗ 1 spec corrupted:
+    - specs/018-spec-validation/
+      • Duplicate section: "Auto-Fix Capability" (lines 245, 320)
+      • Malformed code block (line 67)
+      • Incomplete JSON (line 156)
+
+Content:
+  ⚠ 1 warning:
+    - specs/043-official-launch-02/
+      ⚠ In progress for 45 days
+
+Results: 8/12 passed, 2 warnings, 4 errors
+
+Note: For sequence conflicts, run `lean-spec check`
+```
+
+### Quiet Output
+
+```
+✗ 2 specs with errors
+```
+
+### Verbose Output
+
+```
+📋 Validating specs...
+
+Line Count:
+  ✓ 10 specs within limits
+  
+  Checked 12 specs total
+  - 10 specs under 300 lines (ideal)
+  - 1 spec 300-400 lines (warning zone)
+  - 1 spec over 400 lines (should split)
+
+Frontmatter:
+  ✗ 1 spec has errors:
+  
+    specs/044-spec-relationships-clarity/
+      • Missing required field: created
+        → Fix: Add 'created: YYYY-MM-DD' to frontmatter
+      
+      • Invalid status: "wip"
+        → Valid values: planned, in-progress, complete, archived
+        → Fix: Change status to one of the valid values
+
+... (more detailed explanations)
+```
+
+## JSON Output Format
+
+For CI/CD integration:
+
+```json
+{
+  "summary": {
+    "total": 12,
+    "passed": 10,
+    "failed": 2,
+    "warnings": 1,
+    "checks": {
+      "sequences": {"passed": true, "conflicts": 0},
+      "frontmatter": {"passed": false, "errors": 2},
+      "structure": {"passed": false, "errors": 1},
+      "corruption": {"passed": false, "errors": 3},
+      "content": {"passed": true, "warnings": 1}
+    }
+  },
+  "results": [
+    {
+      "path": "specs/018-spec-validation/",
+      "valid": false,
+      "checks": {
+        "sequences": {"passed": true},
+        "frontmatter": {"passed": true},
+        "structure": {"passed": true},
+        "corruption": {
+          "passed": false,
+          "errors": [
+            {
+              "type": "duplicate-section",
+              "message": "Duplicate section: 'Auto-Fix Capability'",
+              "locations": [245, 320],
+              "severity": "error",
+              "fixable": true
+            },
+            {
+              "type": "malformed-code-block",
+              "message": "Code block not properly closed",
+              "line": 67,
+              "severity": "error",
+              "fixable": false
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+## Exit Codes
+
+- `0` - All checks passed
+- `1` - Errors found (any check failed)
+- `2` - Warnings found (only in --strict mode)
+- `3` - Command error (invalid arguments, etc.)
+
+**Note:** `lean-spec check` (sequence conflicts) uses same exit code pattern.
+
+## Auto-Fix Mode
+
+```bash
+lean-spec validate --fix
+```
+
+**What Gets Fixed:**
+- Missing frontmatter fields (adds with defaults)
+- Date formatting (converts to ISO 8601)
+- Duplicate sections (removes duplicates, keeps first)
+- Unclosed code blocks (closes them)
+- Visual badges (updates from frontmatter)
+- Missing sub-spec references in README.md (adds links)
+
+**What Doesn't Get Fixed:**
+- Invalid status values (requires decision)
+- Empty sections (requires content)
+- Broken links (requires investigation)
+- Complex corruption (requires judgment)
+- Sub-specs exceeding line limits (requires manual splitting)
+- Orphaned sub-specs (requires decision to keep or remove)
+
+**Output:**
+```
+📋 Checking and fixing specs...
+
+Fixed 3 issues:
+  ✓ specs/044-spec-relationships-clarity/
+    • Added missing field: created = 2025-11-04
+    • Formatted date: 2025/11/04 → 2025-11-04
+  
+  ✓ specs/018-spec-validation/
+    • Removed duplicate section: "Auto-Fix Capability"
+
+Could not auto-fix 2 issues:
+  ✗ specs/044-spec-relationships-clarity/
+    • Invalid status: "wip" - Please use: planned, in-progress, complete, archived
+
+Results: Auto-fixed 3/5 issues
+```
+
+## Filtering Specs
+
+```bash
+# By status
+lean-spec validate --status=in-progress
+lean-spec validate --status=planned,in-progress
+
+# By tag
+lean-spec validate --tag=api
+lean-spec validate --tag=quality,validation
+
+# By priority
+lean-spec validate --priority=high,critical
+
+# By path pattern
+lean-spec validate specs/2025*
+lean-spec validate specs/archived/
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+- name: Check spec quality
+  run: |
+    lean-spec validate --format=json --strict > validate-results.json
+  continue-on-error: true
+
+- name: Comment PR with results
+  uses: actions/github-script@v6
+  with:
+    script: |
+      const results = require('./validate-results.json');
+      // Post comment with results
+```
+
+### Pre-Commit Hook
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+# Run comprehensive validation
+lean-spec validate --format=json > /dev/null 2>&1
+
+if [ $? -ne 0 ]; then
+  echo "❌ Spec quality checks failed!"
+  echo "Run 'lean-spec validate' to see details"
+  echo "Run 'lean-spec validate --fix' to auto-fix issues"
+  exit 1
+fi
+
+echo "✓ All spec quality checks passed"
+```
+
+## Design Decisions
+
+### Why Separate `validate` Command (Implementation Choice)
+
+The original spec proposed expanding `lean-spec check`, but the implementation created a separate `lean-spec validate` command:
+
+**Rationale:**
+1. **Separation of concerns**: Sequence checking is fast/targeted; validation is comprehensive
+2. **Performance**: Users can run quick sequence checks without validation overhead
+3. **Backwards compatible**: Existing `lean-spec check` behavior unchanged
+4. **Incremental adoption**: Can add validation rules without affecting check command
+5. **Clearer intent**: `validate` explicitly signals quality checking vs. `check` for conflicts
+
+**Trade-offs:**
+- Two commands to remember (but both are intuitive)
+- More CLI surface area
+- Better performance and flexibility
+
+### Flag Design Philosophy
+
+- **Positive flags**: Enable specific validations (`--frontmatter`, `--structure`)
+- **Negative flags**: Disable validations (`--no-staleness`)
+- **Default**: All available validations when no flags specified
+- **Specificity**: Can validate individual specs or filter by status/tags
+
+### Performance Considerations
+
+- Fast by default (< 1s for 100 specs)
+- Parallel spec loading
+- Incremental checking (only changed specs in auto-check)
+- Caching of check results

package/.next/standalone/packages/ui/dist/standalone/specs/018-spec-validation/CONFIGURATION-EXAMPLES.md

@@ -0,0 +1,230 @@
+# Configuration Examples
+
+> Part of spec: [018-spec-validation](README.md)
+
+Configuration examples for different use cases of `lean-spec validate`.
+
+## Strict Mode (CI/CD)
+
+Use for production/CI environments where you want maximum validation:
+
+```json
+{
+  "validate": {
+    "mode": "comprehensive",
+    "autoValidate": false,
+    "rules": {
+      "frontmatter": {
+        "required": ["status", "created", "priority"],
+        "allowedStatus": ["planned", "in-progress", "complete", "archived"],
+        "allowedPriority": ["low", "medium", "high", "critical"]
+      },
+      "structure": {
+        "requireReadme": true,
+        "requiredSections": ["Overview", "Design", "Plan", "Test"],
+        "forbidEmptySections": true
+      },
+      "content": {
+        "minLength": 200,
+        "forbidTodoInComplete": true,
+        "validateLinks": true
+      },
+      "corruption": {
+        "detectDuplicateSections": true,
+        "validateCodeBlocks": true,
+        "validateJsonYaml": true,
+        "detectFragments": true
+      },
+      "staleness": {
+        "inProgressMaxDays": 30,
+        "noUpdateMaxDays": 90,
+        "plannedMaxDays": 60
+      }
+    }
+  },
+  "ignorePaths": [
+    "archived/**",
+    "drafts/**"
+  ]
+}
+```
+
+## Relaxed Mode (Early Development)
+
+Use for early-stage projects or rapid prototyping:
+
+```json
+{
+  "validate": {
+    "mode": "quick",
+    "autoValidate": false,
+    "rules": {
+      "frontmatter": {
+        "required": ["status"],
+        "allowedStatus": ["planned", "in-progress", "complete", "archived"]
+      },
+      "structure": {
+        "requireReadme": true,
+        "requiredSections": [],
+        "forbidEmptySections": false
+      },
+      "content": {
+        "minLength": 50,
+        "forbidTodoInComplete": false,
+        "validateLinks": false
+      },
+      "corruption": {
+        "detectDuplicateSections": true,
+        "validateCodeBlocks": false,
+        "validateJsonYaml": false,
+        "detectFragments": false
+      },
+      "staleness": {
+        "inProgressMaxDays": 90,
+        "noUpdateMaxDays": 180,
+        "plannedMaxDays": 120
+      }
+    }
+  }
+}
+```
+
+## Custom Workflow (Sprint-Based)
+
+Example for teams using sprint-based workflow:
+
+```json
+{
+  "validate": {
+    "mode": "comprehensive",
+    "rules": {
+      "frontmatter": {
+        "required": ["status", "created", "team", "sprint"],
+        "allowedStatus": ["backlog", "sprint", "review", "done"],
+        "allowedPriority": ["p0", "p1", "p2", "p3"]
+      },
+      "structure": {
+        "requiredSections": ["Problem", "Solution", "Acceptance Criteria"],
+        "forbidEmptySections": true
+      },
+      "content": {
+        "minLength": 150,
+        "forbidTodoInComplete": true,
+        "validateLinks": true
+      }
+    }
+  },
+  "ignorePaths": [
+    "archived/**",
+    "experiments/**"
+  ]
+}
+```
+
+## Minimal Configuration
+
+Bare minimum for validation (uses most defaults):
+
+```json
+{
+  "validate": {
+    "mode": "quick"
+  }
+}
+```
+
+## Feature-Specific Examples
+
+### Enforce Custom Fields
+
+```json
+{
+  "validate": {
+    "rules": {
+      "frontmatter": {
+        "required": ["status", "created", "owner", "cost_estimate"],
+        "customFields": {
+          "owner": { "type": "string", "pattern": "^[a-z]+$" },
+          "cost_estimate": { "type": "number", "min": 0 }
+        }
+      }
+    }
+  }
+}
+```
+
+### Template-Specific Validation
+
+```json
+{
+  "validate": {
+    "templateRules": {
+      "feature": {
+        "requiredSections": ["Use Cases", "Technical Design", "Rollout Plan"]
+      },
+      "bug": {
+        "requiredSections": ["Root Cause", "Fix", "Prevention"]
+      },
+      "spike": {
+        "requiredSections": ["Questions", "Findings", "Recommendation"]
+      }
+    }
+  }
+}
+```
+
+### Ignore Patterns
+
+```json
+{
+  "validate": {
+    "mode": "comprehensive"
+  },
+  "ignorePaths": [
+    "archived/**",
+    "drafts/**",
+    "experiments/**",
+    "**/*.backup.md",
+    "temp-*/**"
+  ]
+}
+```
+
+## Usage with Examples
+
+### Apply Strict Mode
+
+```bash
+# Add to .lean-spec/config.json, then run:
+lean-spec validate
+
+# Or override via CLI:
+lean-spec validate --mode comprehensive
+```
+
+### Apply Relaxed Mode
+
+```bash
+# Use during early development:
+lean-spec validate --mode quick
+
+# Or with specific rules disabled:
+lean-spec validate --no-links --no-staleness
+```
+
+### Custom Workflow
+
+```bash
+# Configure custom status values:
+# .lean-spec/config.json with custom allowedStatus
+# Then validate normally:
+lean-spec validate
+```
+
+## Tips
+
+1. **Start relaxed, tighten gradually** - Begin with `quick` mode, add rules as project matures
+2. **Use strict mode in CI** - Catch issues before merge
+3. **Customize for your workflow** - Adapt `allowedStatus` and `requiredSections` to match your process
+4. **Use ignore paths wisely** - Don't validate archived or experimental specs
+5. **Test configuration** - Run `lean-spec validate --dry-run` to preview changes