@leanspec/ui 0.2.8 → 0.2.9-dev.20251205030455

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

@@ -1,358 +0,0 @@
-# Implementation Plan
-
-8-phase implementation plan for the `lean-spec validate` command.
-
-**Note:** This spec originally proposed expanding `lean-spec check`, but the implementation created `lean-spec validate` as a separate command to keep sequence checking and quality validation as separate concerns.
-
-## Status
-
-**Overall Status:** ✅ COMPLETE for v0.2.0 - Core validation (Phases 1-3.5) shipped
-
-**Priority:** CRITICAL - Quality gates and spec corruption prevention
-
-**v0.2.0 Delivered:** Core validation working, finding real issues, 370+ tests passing.
-
-## Phase 1a: Basic Validation Framework (✅ COMPLETE)
-
-**Goal:** Create modular framework for validation rules
-
-**Completed Tasks:**
-- [x] Created validation framework architecture
-- [x] Implemented `ValidationRule` interface
-- [x] Created `LineCountValidator` with warning/error thresholds
-- [x] Implemented `lean-spec validate` command with `--max-lines` flag
-- [x] Added integration tests
-- [x] Documented in README
-
-**Notes:** 
-- Built as separate `validate` command (not expansion of `check`)
-- Framework allows easy addition of new validators
-- Already in production use
-
-**Phase Completed:** November 2025
-
-## Phase 1b: Frontmatter Validation (✅ COMPLETE)
-
-**Goal:** Validate spec frontmatter for required fields and valid values
-
-**Completed Tasks:**
-- [x] Create frontmatter validator module (`src/validators/frontmatter.ts`)
-- [x] Validate required fields present (status, created)
-- [x] Validate status values (planned, in-progress, complete, archived)
-- [x] Validate priority values (low, medium, high, critical)
-- [x] Validate date formats (ISO 8601: YYYY-MM-DD or full timestamp)
-- [x] Validate tags format (must be array)
-- [x] Add comprehensive unit tests (27 tests passing)
-- [x] Integrate with `lean-spec validate` command
-- [ ] Validate custom fields (if defined in config) - deferred to future phase
-- [ ] Add `--frontmatter` flag for selective validation - deferred to future phase
-
-**Notes:** 
-- Most critical for catching common mistakes ✓
-- Enables comprehensive pre-commit hooks ✓
-- Prevents invalid specs from being created ✓
-- Pragmatic approach: coerces types where reasonable
-- Clear error messages with actionable suggestions
-- Tested against real repository specs: all passing
-
-**Phase Completed:** November 2025
-
-**Actual Effort:** 1 day (ahead of 2-day estimate)
-
-## Phase 2: Structure Validation (✅ COMPLETE)
-
-**Goal:** Ensure specs follow structural conventions
-
-**Completed Tasks:**
-- [x] Create structure validator module (`src/validators/structure.ts`)
-- [x] Validate YAML frontmatter syntax
-- [x] Check for title (H1 heading)
-- [x] Validate required sections present (Overview, Design)
-- [x] Check for empty sections (with proper subsection handling)
-- [x] Detect duplicate section headers
-- [x] Add comprehensive unit tests (17 tests passing)
-- [x] Integrate with `lean-spec validate` command
-- [x] Test against real repository specs
-
-**Notes:** 
-- Ensures spec consistency across team ✓
-- Template-specific validation rules (configurable)
-- Properly handles sections with subsections (doesn't flag as empty)
-- Found 2 real issues in repository (duplicate headers in specs 048, 049)
-
-**Phase Completed:** November 2025
-
-**Actual Effort:** 0.5 days (ahead of 2-day estimate)
-
-## Phase 3: Corruption Detection (✅ COMPLETE)
-
-**Goal:** Detect file corruption from failed edits
-
-**Completed Tasks:**
-- [x] Create corruption detector module (`src/validators/corruption.ts`)
-- [x] Detect duplicate sections at same level (delegated to structure validator)
-- [x] Validate code blocks are properly closed
-- [x] Check JSON/YAML blocks are complete and parseable
-- [x] Detect content fragments (partial duplicates / merge artifacts)
-- [x] Validate markdown structure (unclosed formatting)
-- [x] Add comprehensive unit tests (19 tests passing)
-- [x] Integrate with `lean-spec validate` command
-- [x] Test against real repository specs
-
-**Notes:** 
-- Addresses real pain point we've experienced ✓
-- Runs by default to catch AI edit failures ✓
-- Critical for maintaining spec quality ✓
-- Found 6 real corruption issues in repository:
-  - Invalid YAML blocks (specs 044, 045)
-  - Unclosed formatting (specs 036, 037, 038, 045, 046)
-
-**Phase Completed:** November 2025
-
-**Actual Effort:** 1 day (ahead of 3-day estimate)
-
-## Phase 3.5: Sub-Spec Validation (✅ COMPLETE)
-
-**Goal:** Validate sub-spec files per spec 012 conventions
-
-**Completed Tasks:**
-- [x] Create sub-spec validator module (`src/validators/sub-spec.ts`)
-- [x] Check sub-spec naming conventions (uppercase .md files)
-- [x] Validate README.md references all sub-specs
-- [x] Check line counts per sub-spec file (<400 lines)
-- [x] Detect orphaned sub-spec files (not linked from README)
-- [x] Validate cross-document references
-- [x] Add comprehensive unit tests (16 tests passing)
-- [x] Integrate with `lean-spec validate` command
-- [ ] Check for content duplication across sub-specs (deferred - complex analysis)
-
-**Notes:** 
-- Complements spec 012 (sub-spec files management) ✓
-- Important as teams adopt multi-file specs ✓
-- Enforces Context Economy principle per file ✓
-- Leverages existing `loadSubFiles()` infrastructure ✓
-- Found real issues in repository:
-  - spec 049: ANALYSIS.md (428 lines), OPERATIONALIZATION.md (415 lines)
-  - spec 018: CONFIGURATION.md (443 lines)
-
-**Phase Completed:** November 2025
-
-**Actual Effort:** 0.5 days (ahead of 2-day estimate)
-
-## Phase 4: Content Validation (OPTIONAL for v0.3.0)
-
-**Goal:** Validate spec content quality
-
-**Tasks:**
-- [ ] Minimum content length check
-- [ ] Detect TODO/FIXME in complete specs
-- [ ] Validate internal links
-- [ ] Check for placeholder text
-- [ ] Integrate with `lean-spec validate --content` flag
-
-**Notes:** 
-- Nice to have, can defer to v0.3.0 if time-constrained
-- Lower priority than corruption detection
-- Useful for quality gates
-
-**Estimated Effort:** 1-2 days
-
-## Phase 5: Staleness Detection (OPTIONAL for v0.3.0)
-
-**Goal:** Identify stale or abandoned specs
-
-**Tasks:**
-- [ ] Calculate spec age (created date)
-- [ ] Calculate last update (git or file mtime)
-- [ ] Warn on in-progress specs > 30 days
-- [ ] Warn on no updates > 90 days
-- [ ] Warn on planned specs > 60 days
-- [ ] Integrate with `lean-spec validate --staleness` flag
-
-**Notes:** 
-- Useful for maintenance
-- Lower priority for launch
-- Git integration adds complexity
-
-**Estimated Effort:** 2 days
-
-## Phase 6: Auto-Fix (OPTIONAL for v0.3.0)
-
-**Goal:** Automatically fix common issues
-
-**Tasks:**
-- [ ] Implement --fix flag for `lean-spec validate`
-- [ ] Add missing frontmatter fields
-- [ ] Format dates to ISO 8601
-- [ ] Sort frontmatter fields
-- [ ] Update visual badges
-- [ ] Remove duplicate sections
-- [ ] Close unclosed code blocks
-- [ ] Report what was fixed
-
-**Notes:** 
-- Great UX feature
-- Can defer to post-launch iteration
-- Should be conservative (only fix obvious issues)
-
-**Estimated Effort:** 3 days
-
-## Phase 8: Integration & Polish
-
-**Goal:** Complete feature with docs and tests
-
-**Tasks:**
-- [ ] Add tests for all check types
-- [ ] Update README with expanded check command
-- [ ] Update AGENTS.md to mention comprehensive checking
-- [ ] Create pre-commit hook example
-- [ ] Document migration guide for backwards compatibility
-- [ ] Update MCP server to expose new check capabilities
-- [ ] Performance optimization (parallel checking)
-- [ ] Caching for repeated checks
-
-**Notes:** 
-- Essential for launch
-- Documentation is critical for adoption
-- Performance matters for large projects
-
-**Estimated Effort:** 2-3 days
-
-## Launch Strategy (2025-11-04)
-
-### v0.2.0 Scope
-- **MUST HAVE:** Phases 1-3 (refactored framework + frontmatter + structure validation)
-- **HIGHLY RECOMMENDED:** Phase 3.5 (sub-spec validation - enforces spec 012)
-- **HIGHLY RECOMMENDED:** Phase 4 (corruption detection - addresses real pain point)
-- **SHOULD HAVE:** Phase 7 (auto-fix, at least for corruption issues)
-- **NICE TO HAVE:** Phases 5-6 (content, staleness)
-
-### v0.3.0 Scope
-- Complete all remaining phases
-- Roll out comprehensive checking with backwards compatibility
-- Enable by default with config override
-
-### Post-v0.3.0
-- Add advanced features based on user feedback
-- Custom validation rules
-- Performance optimizations
-- Additional check types
-
-## Total Estimated Effort
-
-**Minimum (Phases 1-3.5):** 11-12 days
-**Complete (All phases):** 17-20 days
-
-## Dependencies
-
-- Existing `check` command (sequence conflicts)
-- Frontmatter parsing infrastructure
-- Spec loading system (with `loadSubFiles()` support)
-- Config system
-- Spec 012 conventions (sub-spec file organization)
-
-## Risks & Mitigation
-
-**Risk:** Breaking backwards compatibility
-- **Mitigation:** Comprehensive testing, config options, gradual rollout
-
-**Risk:** Performance degradation with many checks
-- **Mitigation:** Parallel checking, caching, incremental mode
-
-**Risk:** False positives in corruption detection
-- **Mitigation:** Conservative rules, allow configuration
-
-**Risk:** Scope creep (too many check types)
-- **Mitigation:** Focus on Phases 1-4 for launch, defer others
-
-## Success Metrics
-
-- Zero spec corruption incidents after deployment
-- >90% of specs pass validation checks
-- <1s check time for 100 specs
-- Positive user feedback on validation quality
-- Reduced time debugging spec issues
-
-## Testing Strategy
-
-Each phase includes:
-- Unit tests for validator modules
-- Integration tests with real specs
-- Edge case testing
-- Performance benchmarks
-- Backwards compatibility tests
-
-See [TESTING.md](./TESTING.md) for detailed test plan.
-
-## Migration Path
-
-### For Existing Projects
-
-1. **Run initial validation:**
-   ```bash
-   lean-spec validate --max-lines 400
-   ```
-
-2. **Review and fix issues:**
-   ```bash
-   lean-spec validate --fix  # When auto-fix is available
-   lean-spec validate        # Verify fixes
-   ```
-
-3. **Enable in CI:**
-   ```yaml
-   - run: lean-spec validate --strict --format=json
-   ```
-
-4. **Add pre-commit hook:**
-   ```bash
-   lean-spec check           # Sequence conflicts
-   lean-spec validate        # Quality validation
-   ```
-
-### For New Projects
-
-- Comprehensive checking enabled by default
-- Use templates with validation hints
-- Pre-commit hooks included
-
-## Alternative Approaches Considered
-
-### Separate `lean-spec validate` Command
-
-**Pros:** 
-- Clear separation of concerns
-- No backwards compatibility issues
-
-**Cons:**
-- Two commands for quality checking
-- User confusion (when to use which?)
-- More maintenance burden
-
-**Decision:** Expand `check` with flags for better UX
-
-### Always-On Comprehensive Checking
-
-**Pros:**
-- Maximum quality enforcement
-- Simple model
-
-**Cons:**
-- Breaking change
-- Performance impact for large projects
-- User pushback
-
-**Decision:** Make it opt-in with config, default in v0.3.0
-
-### External Plugin System
-
-**Pros:**
-- Extensibility
-- Community contributions
-
-**Cons:**
-- Over-engineering for current needs
-- Added complexity
-- Maintenance burden
-
-**Decision:** Defer to future version if needed

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

@@ -1,303 +0,0 @@
----
-status: complete
-created: '2025-11-02'
-tags:
-  - quality
-  - validation
-  - cli
-  - first-principles
-  - v0.2.0
-priority: critical
-related:
-  - 043-official-launch-02
-  - 012-sub-spec-files
-created_at: '2025-11-02T00:00:00Z'
-updated_at: '2025-11-06T07:08:45.538Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-05T13:35:26.669Z'
-  - status: complete
-    at: '2025-11-06T07:00:00.000Z'
-completed: '2025-11-06'
----
-
-# Comprehensive Spec Validation
-
-> **Status**: ✅ Complete · **Priority**: Critical · **Created**: 2025-11-02 · **Tags**: quality, validation, cli, first-principles, v0.2.0
-
-## Overview
-
-Provide comprehensive validation tooling that checks specs for quality issues including structure, frontmatter, content, sequence conflicts, and **file corruption**.
-
-**Current State:**
-- ✅ `lean-spec check` exists - checks sequence conflicts only
-- ✅ `lean-spec validate` exists - comprehensive validation framework
-- ✅ **Line count validation** - warns at 300 lines, errors at 400+ lines
-- ✅ **Frontmatter validation** - enforces required fields and valid values
-- ✅ **Structure validation** - duplicate headers, required sections
-- ✅ **Corruption detection** - unclosed code blocks, formatting issues, duplicates
-- ❌ No way to detect stale specs (optional, future phase)
-- ❌ No auto-fix capability (optional, future phase)
-
-**Implementation Approach:**
-Both `lean-spec check` and `lean-spec validate` exist as separate commands:
-
-```bash
-# Current commands
-lean-spec check                    # Check for sequence conflicts
-lean-spec validate [specs...]      # Validate specs for quality issues
-lean-spec validate --max-lines 500 # Custom line limit
-
-# Planned enhancements
-lean-spec validate --frontmatter   # Frontmatter validation
-lean-spec validate --structure     # Structure validation
-lean-spec validate --corruption    # File corruption detection
-lean-spec validate --sub-specs     # Sub-spec validation (spec 012)
-lean-spec validate --all           # All validation rules
-```
-
-**Use Cases:**
-1. CI/CD validation (block PRs with invalid specs)
-2. Pre-commit hooks (comprehensive quality checks)
-3. Local validation before creating PR
-4. Detecting stale/abandoned specs
-5. Enforcing team conventions (required fields, valid values)
-6. Quality gates for spec completion
-7. **Detecting corrupted specs from failed edits**
-8. **Validating sub-spec organization per spec 012**
-
-**What Success Looks Like:**
-```bash
-$ lean-spec validate --all
-Validating specs...
-
-Line Count:
-  ✓ 043-official-launch-02 (387 lines)
-  ⚠ 048-spec-complexity-analysis (356 lines - approaching limit)
-  ✗ 018-spec-validation (455 lines - exceeds limit!)
-     → Consider splitting into sub-specs (see spec 012)
-
-Frontmatter:
-  ✗ 1 spec has invalid frontmatter:
-    - specs/043-official-launch-02/README.md
-      • Invalid status: "wip" (expected: planned, in-progress, complete, archived)
-
-Structure:
-  ✓ All specs have valid structure
-
-Sub-Specs:
-  ⚠ 1 spec has warnings:
-    - specs/018-spec-validation/README.md
-      ⚠ Sub-spec TESTING.md (421 lines) exceeds 400 line limit
-      ⚠ Orphaned sub-spec: DEPRECATED.md (not linked from README.md)
-
-Corruption:
-  ✓ All 25 spec(s) passed
-
-Results: 25 specs validated, 5 error(s), 6 warning(s)
-```
-
-**Recent Improvements (2025-11-05):**
-- ✅ Fixed duplicate detection bug: sliding window was reporting adjacent lines as duplicates
-- ✅ Improved thresholds: 8 lines / 200 chars (was 5/100) for better signal-to-noise
-- ✅ Code blocks now included in duplicate detection (catches actual copy-paste errors)
-- ✅ Removed JSON/YAML validation (code examples show invalid syntax)
-- ✅ Smarter formatting checks: exclude inline code and list markers
-- 📉 Result: Zero false positives, catches only real corruption
-
-## Design
-
-This spec has been split into focused sub-documents for clarity and maintainability.
-
-### Core Documents
-
-📋 **[VALIDATION-RULES.md](./VALIDATION-RULES.md)** - What gets validated
-- Frontmatter validation rules
-- Structure validation rules
-- Content validation rules
-- Corruption detection rules
-- Staleness detection rules
-- Auto-fix capabilities
-
-🔧 **[CLI-DESIGN.md](./CLI-DESIGN.md)** - Command interface
-- Command syntax and flags
-- Output formats (console, JSON)
-- Backwards compatibility strategy
-- Exit codes
-- CI/CD integration examples
-
-⚙️ **[CONFIGURATION.md](./CONFIGURATION.md)** - Configuration schema
-- Complete config options
-- Rule customization
-- Template-specific rules
-- Default configuration
-- Configuration examples
-
-📝 **[CONFIGURATION-EXAMPLES.md](./CONFIGURATION-EXAMPLES.md)** - Real-world configuration examples and use cases
-
-🗺️ **[IMPLEMENTATION.md](./IMPLEMENTATION.md)** - Implementation plan
-- 8-phase implementation plan
-- Priority and scope decisions
-- Launch strategy (v0.2.0 vs v0.3.0)
-- Dependencies and risks
-- Migration path
-
-✅ **[TESTING.md](./TESTING.md)** - Test strategy
-- Test categories and coverage
-- Integration tests
-- Performance tests
-- Manual testing checklist
-
-## Design Decision
-
-**Implementation Note:** The original design proposed expanding `lean-spec check` into a unified validation command. However, the implementation created a separate `lean-spec validate` command instead, keeping both commands focused:
-
-- **`lean-spec check`** - Fast sequence conflict detection
-- **`lean-spec validate`** - Comprehensive quality validation
-
-**Rationale for Separate Commands:**
-
-1. **Clear separation of concerns:** Sequence checking is fast and targeted; validation is comprehensive
-2. **Performance:** Users can run quick checks without full 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
-
-**Trade-offs:**
-- Two commands to remember (but both are intuitive)
-- More CLI surface area
-- Better performance and flexibility
-
-## Evolution
-
-| Version | Commands Available |
-|---------|--------------------|
-| v0.1.0 | `lean-spec check` (sequence conflicts only) |
-| v0.2.0+ | `lean-spec check` (sequences) + `lean-spec validate` (line counts) |
-| v0.3.0+ | Both commands with comprehensive validation rules |
-
-## Launch Strategy
-
-**v0.2.0 Scope (Current):**
-- ✅ `lean-spec check` for sequence conflicts
-- ✅ `lean-spec validate` with basic framework and line count validation
-- ⏳ Expand validation rules in upcoming phases
-
-**v0.3.0 Scope:**
-- **MUST HAVE:** Framework + frontmatter + structure validation
-- **HIGHLY RECOMMENDED:** Corruption detection (addresses real pain point)
-- **SHOULD HAVE:** Auto-fix capability
-- **NICE TO HAVE:** Content and staleness validation
-
-**Post-v0.3.0:**
-- Advanced features based on user feedback
-- Custom validation rules
-- Performance optimizations
-
-## Implementation Status
-
-See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for detailed plan.
-
-**Status:** ✅ COMPLETE for v0.2.0 launch
-
-**✅ Completed (Phases 1a, 1b, 2, 3, 3.5):**
-- ✅ Validation framework architecture
-- ✅ **Phase 1a:** `LineCountValidator` with warning/error thresholds (300 line warning, 400 line error)
-- ✅ **Phase 1a:** `lean-spec validate` command with `--max-lines` flag
-- ✅ **Phase 1b:** `FrontmatterValidator` for comprehensive frontmatter validation
-  - Required fields (status, created)
-  - Valid status/priority values  
-  - Date format validation (ISO 8601)
-  - Tags format validation
-- ✅ **Phase 2:** `StructureValidator` for spec structure validation
-  - H1 title presence
-  - Required sections (Overview, Design)
-  - Empty section detection (with subsection handling)
-  - Duplicate section header detection
-- ✅ **Phase 3:** `CorruptionValidator` for file corruption detection
-  - Unclosed code block detection (visible syntax highlighting issues)
-  - Unclosed markdown formatting (bold, italic) in actual content
-  - Duplicate content block detection with improved tuning (8 lines, 200 chars)
-  - **Code blocks included** in duplicate detection (catches real copy-paste errors)
-  - **Bug fix:** Fixed sliding window algorithm reporting adjacent lines
-  - **Removed JSON/YAML validation** (examples show invalid syntax intentionally)
-  - Code block exclusion for all formatting checks
-  - Inline code and list marker exclusion
-  - Duplicate detection tuning: 3/50 → 5/100 (reduced false positives)
-  - Removed noisy checks (JSON/YAML, table/list validation)
-  - **Bug fix:** Fixed sliding window algorithm causing adjacent line false positives
-  - **Threshold increase:** 5/100 → 8/200 (block size/min chars) for less sensitivity
-  - **Reverted code block filtering:** Now includes code blocks in duplicate detection
-- ✅ **Phase 3.5:** `SubSpecValidator` for sub-spec file validation
-  - Sub-spec naming conventions (uppercase .md files)
-  - README.md references all sub-specs (orphan detection)
-  - Line count validation per sub-spec file (<400 lines)
-  - Cross-document reference validation
-  - Found real issues: 3 sub-specs exceeding limits in 2 specs
-- ✅ **370 total tests passing** (16 sub-spec + 354 existing)
-- ✅ Documentation and CLI integration
-- ✅ Tested with real repository specs
-
-**📊 Current Validation Results (2025-11-05):**
-```bash
-$ lean-spec validate
-Results: 25 specs validated, 5 error(s), 6 warning(s)
-
-Errors found:
-- Line count: 3 specs exceed 400 lines (048, 046, 045)
-- Sub-specs: 3 sub-spec files exceed 400 lines (049: 2 files, 018: 1 file)
-- Corruption: ✅ 0 errors (bug fixed, thresholds tuned!)
-
-Warnings:
-- Line count: 6 specs between 300-400 lines (approaching limit)
-- Corruption: ✅ 0 warnings (improved from 31 false positives!)
-
-All specs: ✅ Frontmatter passed, ✅ Structure passed, ✅ Sub-spec validation working
-```
-
-**✨ v0.2.0 Scope Complete:**
-Core validation is complete and working! Phases 1-3.5 deliver the essential quality checks including sub-spec validation. Additional phases (content validation, staleness detection, auto-fix) deferred to v0.3.0 based on user feedback.
-
-## Quick Links
-
-- **Validation Details:** [VALIDATION-RULES.md](./VALIDATION-RULES.md)
-- **CLI Reference:** [CLI-DESIGN.md](./CLI-DESIGN.md)
-- **Configuration:** [CONFIGURATION.md](./CONFIGURATION.md)
-- **Implementation:** [IMPLEMENTATION.md](./IMPLEMENTATION.md)
-- **Testing:** [TESTING.md](./TESTING.md)
-
-## Notes
-
-**Why This Matters:**
-
-This addresses real pain points we've experienced:
-- Spec corruption from failed AI edits
-- Invalid frontmatter causing issues
-- No way to enforce quality standards
-- Manual validation is time-consuming
-
-**Performance Goals:**
-- < 1s for 100 specs
-- Parallel checking
-- Incremental mode for auto-check
-- Caching for repeated checks
-
-**Integration:**
-```bash
-# CI/CD - Quick sequence check
-lean-spec check
-
-# CI/CD - Comprehensive validation
-lean-spec validate --all --format=json
-
-# Pre-commit hook - Fast validation
-lean-spec validate --max-lines 400
-
-# Manual comprehensive check
-lean-spec validate --all --fix
-```
-
-**References:**
-- Markdownlint: Markdown linting tool (inspiration)
-- JSON Schema: Validation schema standard
-- YAML Lint: YAML validation patterns