npm - @leanspec/ui - Versions diffs - 0.2.5 → 0.2.6-dev.20251125010539 - Mend

@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (695) hide show

package/.next/standalone/packages/ui/dist/standalone/specs/059-programmatic-spec-management/COMMANDS.md DELETED Viewed

@@ -1,1002 +0,0 @@
-# CLI Commands
-**Mechanical transformation tools for AI agent orchestration**
-## Design Philosophy
-These commands are designed for **AI agent orchestration**:
-- AI agents read specs and detect issues
-- AI agents decide transformation strategies
-- AI agents call tools with explicit parameters
-- Tools execute transformations mechanically (no LLM calls)
-**Key Principles**:
-1. **Tools are executors, not deciders** - AI agents provide intelligence
-2. **Deterministic operations** - Same input = same output, always
-3. **Structured I/O** - JSON output for AI agent consumption
-4. **No semantic analysis** - Just parse, transform, validate
-5. **Fast and reliable** - Milliseconds, not minutes
-## Command Overview
-```bash
-# Analysis (returns structured data)
-lean-spec analyze <spec> [options]
-# Transformations (execute AI agent decisions)
-lean-spec split <spec> [options]
-lean-spec compact <spec> [options]
-lean-spec compress <spec> [options]
-lean-spec isolate <spec> [options]
-# Utilities
-lean-spec diff <spec> --before-after
-lean-spec preview <spec> --transformation=<type>
-lean-spec rollback <spec>
-```
-## `lean-spec analyze` - Analyze Spec Complexity
-### Purpose
-Parse spec structure and return metrics for AI agent decision-making. No semantic analysis, just structural facts.
-### Usage
-```bash
-lean-spec analyze <spec> [options]
-Options:
-  --json           Output as JSON (default for AI agents)
-  --concerns       Detect logical groupings by section structure
-  --verbose        Include detailed breakdown
-```
-### Output Format
-**JSON (primary format for AI agents)**:
-```json
-{
-  "spec": "045-unified-dashboard",
-  "path": "specs/045-unified-dashboard/README.md",
-  "metrics": {
-    "tokens": 4800,
-    "lines": 1166,
-    "characters": 19200,
-    "sections": {
-      "h1": 1,
-      "h2": 8,
-      "h3": 23,
-      "h4": 12,
-      "total": 44
-    },
-    "codeBlocks": 23,
-    "maxNesting": 4
-  },
-  "threshold": {
-    "status": "warning",
-    "limit": 3500,
-    "message": "Exceeds 3,500 token warning threshold"
-  },
-  "structure": [
-    {
-      "section": "Overview",
-      "level": 2,
-      "lineRange": [1, 150],
-      "tokens": 600,
-      "subsections": ["Background", "Decision"]
-    },
-    {
-      "section": "Design",
-      "level": 2,
-      "lineRange": [151, 528],
-      "tokens": 1512,
-      "subsections": ["Architecture", "Components", "Data Flow"]
-    }
-  ],
-  "recommendation": {
-    "action": "split",
-    "reason": "Exceeds 3,500 token threshold with multiple distinct concerns",
-    "confidence": "high"
-  }
-}
-```
-### Human-Readable Format
-**For human review** (optional `--verbose` flag):
-```bash
-$ lean-spec analyze 045 --verbose
-📊 Spec Analysis: 045-unified-dashboard
-Token Count: 4,800 tokens (⚠️  WARNING)
-  • Threshold: 3,500 tokens
-  • Status: Exceeds warning, approaching 5,000 error threshold
-Structure:
-  Lines: 1,166
-  Sections: 44 (H1:1, H2:8, H3:23, H4:12)
-  Code blocks: 23
-  Max nesting: 4 levels
-Top Sections by Size:
-  1. Design (1,512 tokens / 378 lines, 32%)
-  2. Testing (728 tokens / 182 lines, 15%)
-  3. Overview (600 tokens / 150 lines, 13%)
-Recommendation: Split into sub-specs
-  → Multiple distinct concerns detected
-  → Would reduce to 5 files under 2,000 tokens each
-```
-### AI Agent Usage Pattern
-```typescript
-// AI agent workflow
-const analysis = await exec('lean-spec analyze 045 --json');
-const data = JSON.parse(analysis);
-if (data.threshold.status === 'warning' && data.recommendation.action === 'split') {
-  // AI decides split strategy based on structure
-  const outputs = data.structure
-    .filter(s => s.level === 2)
-    .map(s => `${s.section}.md:${s.lineRange[0]}-${s.lineRange[1]}`);
-  // AI calls tool with explicit parameters
-  await exec(`lean-spec split 045 ${outputs.map(o => `--output=${o}`).join(' ')}`);
-}
-```
-## `lean-spec split` - Partition Spec into Files
-### Purpose
-Mechanically split spec into multiple files based on explicit line ranges. AI agent decides what goes where.
-### Usage
-```bash
-lean-spec split <spec> [options]
-Options:
-  --output=<file>:<lines>   Output file with line range (required, repeatable)
-  --update-refs            Update cross-references automatically
-  --dry-run                Show what would be created
-  --force                  Overwrite existing files
-```
-### Examples
-**AI agent orchestrated split**:
-```bash
-# AI agent analyzed spec and decided on split points
-$ lean-spec split 045 \
-  --output=README.md:1-150 \
-  --output=DESIGN.md:151-528 \
-  --output=TESTING.md:529-710 \
-  --update-refs
-✓ Created specs/045-unified-dashboard/README.md (812 tokens / 150 lines)
-✓ Created specs/045-unified-dashboard/DESIGN.md (1,512 tokens / 378 lines)
-✓ Created specs/045-unified-dashboard/TESTING.md (728 tokens / 182 lines)
-✓ Updated 47 cross-references
-✓ Validated all files
-Split complete: 3 files, 3,052 tokens total
-```
-**Dry run preview**:
-```bash
-$ lean-spec split 045 --output=README.md:1-150 --dry-run
-Would create:
-  specs/045-unified-dashboard/README.md
-    Lines: 1-150 (150 lines)
-    Estimated tokens: 812
-    Sections: Overview, Background, Decision
-No files modified (dry run)
-```
-**Conflict detection**:
-```bash
-**AI agent orchestrated split**:
-```bash
-# AI agent analyzed spec and decided on split points
-$ lean-spec split 045 \
-  --output=README.md:1-150 \
-  --output=DESIGN.md:151-528 \
-  --output=TESTING.md:529-710 \
-  --update-refs
-✓ Created specs/045-unified-dashboard/README.md (812 tokens / 150 lines)
-✓ Created specs/045-unified-dashboard/DESIGN.md (1,512 tokens / 378 lines)
-✓ Created specs/045-unified-dashboard/TESTING.md (728 tokens / 182 lines)
-✓ Updated 47 cross-references
-✓ Validated all files
-Split complete: 3 files, 3,052 tokens total
-```
-**Dry run preview**:
-```bash
-$ lean-spec split 045 --output=README.md:1-150 --dry-run
-Would create:
-  specs/045-unified-dashboard/README.md
-    Lines: 1-150 (150 lines)
-    Estimated tokens: 812
-    Sections: Overview, Background, Decision
-No files modified (dry run)
-```
-### Tool Behavior
-**What it does**:
-1. Parses spec structure (frontmatter, sections, line ranges)
-2. Extracts specified line ranges to new files
-3. Copies frontmatter to README.md only
-4. Updates internal cross-references if `--update-refs`
-5. Validates all created files
-**What it doesn't do**:
-- ❌ No semantic analysis of content
-- ❌ No decisions about what should go where
-- ❌ No content rewriting or summarization
-- ✅ Just mechanical extraction and file creation
-## `lean-spec compact` - Remove Specified Content
-### Purpose
-Mechanically remove specified line ranges. AI agent identifies redundancy, tool executes removal.
-### Usage
-```bash
-lean-spec compact <spec> [options]
-Options:
-  --remove=<lines>         Line range to remove (required, repeatable)
-  --dry-run               Show what would be removed
-  --force                 Skip confirmation
-```
-### Examples
-**AI agent orchestrated compaction**:
-```bash
-# AI agent detected redundancy at specific lines
-$ lean-spec compact 045 \
-  --remove=145-153 \
-  --remove=234-256 \
-  --remove=401-415
-✓ Removed lines 145-153 (9 lines, ~36 tokens)
-✓ Removed lines 234-256 (23 lines, ~92 tokens)
-✓ Removed lines 401-415 (15 lines, ~60 tokens)
-✓ Updated line references
-Compaction complete: Removed 47 lines, saved ~188 tokens
-```
-**Dry run**:
-```bash
-$ lean-spec compact 045 --remove=145-153 --dry-run
-Would remove:
-  Lines 145-153 (9 lines):
-    "Dashboard layout using CSS Grid..."
-    [duplicate of content at lines 289-297]
-  Estimated savings: ~36 tokens
-No files modified (dry run)
-```
-### Tool Behavior
-**What it does**:
-1. Removes specified line ranges
-2. Updates internal line number references
-3. Validates markdown structure after removal
-4. Reports token/line savings
-**What it doesn't do**:
-- ❌ No detection of redundancy
-- ❌ No semantic understanding of what's safe to remove
-- ✅ Just mechanical deletion of specified lines
-## `lean-spec compress` - Replace Content with Summary
-### Purpose
-Replace specified content with AI-provided summary. AI agent generates summary, tool executes replacement.
-### Usage
-```bash
-lean-spec compress <spec> [options]
-Options:
-  --replace=<lines>:<text>  Replace line range with text (required)
-  --dry-run                Show preview
-```
-### Examples
-**AI agent orchestrated compression**:
-```bash
-# AI agent read completed phase, generated summary
-$ lean-spec compress 043 \
-  --replace='142-284:## ✅ Phase 1: Foundation (Completed 2025-11-05)
-Established first principles through comprehensive analysis.
-See: specs/049-leanspec-first-principles/'
-✓ Replaced lines 142-284 (143 lines) with 4 lines
-✓ Saved ~572 tokens
-Compression complete: 143 → 4 lines
-```
-### Tool Behavior
-**What it does**:
-1. Replaces specified line range with provided text
-2. Validates markdown structure
-3. Reports compression ratio
-**What it doesn't do**:
-- ❌ No summarization of content
-- ❌ No decision about what to keep/remove
-- ✅ Just mechanical text replacement
-## `lean-spec isolate` - Move Content to New Spec
-### Purpose
-Move specified content to a new spec file. AI agent decides what to isolate, tool executes move.
-### Usage
-```bash
-lean-spec isolate <source-spec> [options]
-Options:
-  --lines=<range>          Lines to move (required)
-  --to=<new-spec>         New spec name (required)
-  --add-reference         Add cross-reference in source
-```
-### Examples
-**AI agent orchestrated isolation**:
-```bash
-# AI agent determined section is independent concern
-$ lean-spec isolate 045 \
-  --lines=401-542 \
-  --to=060-velocity-algorithm \
-  --add-reference
-✓ Created specs/060-velocity-algorithm/README.md (142 lines, ~568 tokens)
-✓ Removed lines 401-542 from spec 045
-✓ Added reference: "See [spec 060](../060-velocity-algorithm/)"
-✓ Updated frontmatter (related fields)
-Isolation complete: New spec 060 created
-```
-### Tool Behavior
-**What it does**:
-1. Creates new spec directory and README.md
-2. Moves specified lines to new spec
-3. Removes lines from source spec
-4. Updates cross-references if requested
-5. Initializes frontmatter for new spec
-**What it doesn't do**:
-- ❌ No decision about what constitutes a separate concern
-- ❌ No analysis of dependencies
-- ✅ Just mechanical file operations
-**auto (default)**: AI-suggested strategy based on analysis
-**concerns**: Split by logical concerns (design, testing, etc.)
-**phases**: Split by implementation phases
-**custom**: Interactive selection of sections
-### Examples
-**Auto split** (recommended):
-```bash
-$ lean-spec split 045
-🔍 Analyzing spec structure...
-✓ Detected 5 concerns
-✓ Generated split plan
-Split Preview:
-  045-unified-dashboard/
-  ├── README.md (812 tokens / 203 lines)
-  │   └── Overview, decision, quick reference
-  ├── DESIGN.md (1,512 tokens / 378 lines)
-  │   └── Architecture, components, data flow
-  ├── RATIONALE.md (584 tokens / 146 lines)
-  │   └── Trade-offs, alternatives, decisions
-  ├── IMPLEMENTATION.md (576 tokens / 144 lines)
-  │   └── Phased plan with milestones
-  └── TESTING.md (728 tokens / 182 lines)
-      └── Test strategy, cases, criteria
-Changes:
-  ✓ 5 files created (4,212 tokens total, ~588 tokens saved via compaction)
-  ✓ 47 cross-references updated
-  ✓ All files under 2,000 token optimal threshold
-  ✓ No content lost
-Apply this split? (Y/n) █
-```
-**Preview mode**:
-```bash
-$ lean-spec split 045 --preview
-Split Plan:
-README.md (812 tokens / 203 lines):
-  # Unified Dashboard
-  > **Status**: 📅 Planned · **Priority**: Critical
-  ## Overview
-  [600 tokens / 150 lines of overview content...]
-  ## Sub-Specs
-  - [DESIGN.md](./DESIGN.md) - Architecture details
-  - [RATIONALE.md](./RATIONALE.md) - Design decisions
-  - [IMPLEMENTATION.md](./IMPLEMENTATION.md) - Phased plan
-  - [TESTING.md](./TESTING.md) - Test strategy
-DESIGN.md (1,512 tokens / 378 lines):
-  # Design & Architecture
-  Detailed design for unified dashboard...
-  ## Component Structure
-  [architecture content...]
-[continue for other files...]
-Preview only - no files created.
-Run without --preview to apply.
-```
-**Split by phases**:
-```bash
-$ lean-spec split 043 --strategy=phases
-Phase-based split for multi-phase spec:
-043-official-launch-02/
-├── README.md (720 tokens / 180 lines)
-│   └── Overview, vision, success criteria
-├── PHASE-1-FOUNDATION.md (568 tokens / 142 lines)
-│   └── First principles, guidelines
-├── PHASE-2-OPERATIONALIZATION.md (632 tokens / 158 lines)
-│   └── Validation, tooling, dogfooding
-└── PHASE-3-LAUNCH.md (500 tokens / 125 lines)
-    └── Marketing, docs, announcement
-Apply? (Y/n)
-```
-**Custom/interactive split**:
-```bash
-$ lean-spec split 045 --strategy=custom
-Interactive Split Wizard:
-Current sections (select to group):
-  [x] 1. Overview
-  [x] 2. Background
-  [x] 3. Decision
-  [ ] 4. Design
-  [ ] 5. Architecture
-  [ ] 6. Components
-  ...
-Create file: README.md ✓
-Selected sections: 1, 2, 3
-Continue with next file? (Y/n) y
-Select sections for next file:
-  [ ] 4. Design
-  [ ] 5. Architecture
-  [ ] 6. Components
-  ...
-```
-### Post-Split Validation
-After splitting, automatically validates:
-- ✓ All files under 3,500 tokens
-- ✓ No broken cross-references
-- ✓ Valid markdown syntax
-- ✓ Valid frontmatter in README.md
-- ✓ Sub-spec links in README.md
-- ✓ Git-trackable (files committed together)
-## `lean-spec compact` - Remove Redundancy
-### Purpose
-Remove duplicate and redundant content while preserving decisions.
-### Usage
-```bash
-lean-spec compact <spec> [options]
-Options:
-  --preview              Show changes before applying
-  --aggressive           More aggressive compaction
-  --preserve=<sections>  Don't compact these sections
-  --threshold=<percent>  Similarity threshold (0-100, default: 85)
-```
-### Examples
-**Basic compaction**:
-```bash
-$ lean-spec compact 018
-🔍 Analyzing redundancy...
-✓ Found 3 duplicate sections
-✓ Found 5 consolidation opportunities
-Compaction Preview:
-Duplicates to remove:
-  1. "Validation rules" (lines 145-158)
-     → Consolidate with lines 278-291
-     Savings: 13 lines
-  2. "Config schema example" (lines 234-256)
-     → Already shown in lines 89-111
-     Savings: 22 lines
-Consolidations:
-  3. Repeated prop descriptions (4 instances)
-     → Convert to reference table
-     Savings: 38 lines
-Before: 591 lines
-After:  518 lines
-Savings: 73 lines (12%)
-Apply compaction? (Y/n)
-```
-**Aggressive mode**:
-```bash
-$ lean-spec compact 018 --aggressive
-🔍 Aggressive compaction analysis...
-Additional opportunities:
-  - Remove obvious inferences (e.g., "ESLint lints code")
-  - Shorten verbose explanations
-  - Convert examples to references
-  - Merge similar subsections
-Before: 591 lines
-After:  445 lines (conservative) or 389 lines (aggressive)
-Choose mode:
-  1. Conservative (keep more context)
-  2. Aggressive (maximum reduction)
-  3. Custom (you choose each)
-Selection: █
-```
-## `lean-spec compress` - Summarize Sections
-### Purpose
-Compress completed phases or verbose sections into summaries.
-### Usage
-```bash
-lean-spec compress <spec> [options]
-Options:
-  --section=<name>       Section to compress
-  --phases               Compress completed phases
-  --history              Compress historical sections
-  --ai                   Use AI for summarization
-  --preserve-decisions   Keep decision rationale (default: true)
-```
-### Examples
-**Compress completed phases**:
-```bash
-$ lean-spec compress 043 --phases
-🔍 Identifying completed phases...
-✓ Found 2 completed phases
-Compression Preview:
-Phase 1: Foundation (COMPLETE - 2025-11-05)
-  Before (142 lines):
-    ## Phase 1: Foundation
-    Establish first principles...
-    ### Task 1.1: Conduct Analysis
-    - Research context engineering
-    - Identify constraints
-    - [138 lines of detailed steps...]
-  After (8 lines):
-    ## ✅ Phase 1: Foundation (Completed 2025-11-05)
-    Established first principles through comprehensive analysis
-    of constraints, comparisons, and thought experiments.
-    Deliverables: specs/049-leanspec-first-principles/
-    Key decisions: [link to FIRST-PRINCIPLES.md]
-Phase 2: Operationalization (COMPLETE - 2025-11-06)
-  Before (158 lines):
-    ## Phase 2: Operationalization
-    [detailed implementation steps...]
-  After (10 lines):
-    ## ✅ Phase 2: Operationalization (Completed 2025-11-06)
-    Implemented validation tools and dogfooded on our own specs.
-    Split specs 018, 045, 048 using sub-spec pattern.
-    Result: All specs now under 400 lines or properly split.
-Total savings: 282 lines (69% reduction for completed phases)
-Apply compression? (Y/n)
-```
-**Compress specific section**:
-```bash
-$ lean-spec compress 045 --section="Research Notes"
-Section: Research Notes (85 lines)
-Status: Supporting information, not critical to decisions
-Compression options:
-  1. Summarize to 10-15 lines
-  2. Move to separate file (RESEARCH.md)
-  3. Link to external doc and remove
-  4. Keep as-is
-Selection: 1
-Preview:
-  Before (85 lines): [full research notes]
-  After (12 lines): Key findings and links to sources
-Apply? (Y/n)
-```
-**AI-powered compression**:
-```bash
-$ lean-spec compress 018 --history --ai
-🤖 Using AI to summarize historical sections...
-Found 3 historical sections:
-  1. "Initial Implementation Notes" (45 lines)
-  2. "Migration Path" (38 lines)
-  3. "Archived Approaches" (52 lines)
-AI Summary Preview:
-## Implementation History
-Initial implementation focused on...
-[AI-generated summary preserving key decisions]
-Total: 15 lines (from 135 lines, 89% reduction)
-Preserved:
-  ✓ Key decisions and rationale
-  ✓ Links to commits/PRs
-  ✓ Lessons learned
-Lost:
-  ✗ Step-by-step details (available in git history)
-  ✗ Intermediate explorations
-  ✗ Debugging notes
-Apply? (Y/n)
-```
-## `lean-spec isolate` - Extract to New Spec
-### Purpose
-Move unrelated concern to separate spec.
-### Usage
-```bash
-lean-spec isolate <spec> [options]
-Options:
-  --section=<name>       Section to isolate
-  --new-spec=<name>      Name for new spec
-  --interactive          Interactive section selection
-  --keep-reference       Add cross-reference in original
-```
-### Examples
-**Isolate section**:
-```bash
-$ lean-spec isolate 045 --section="Velocity Algorithm" --new-spec=velocity-algorithm
-🔍 Analyzing section "Velocity Algorithm"...
-✓ Can be isolated (minimal dependencies)
-Isolation Plan:
-Create new spec:
-  060-velocity-algorithm/README.md (142 lines)
-    - Extract "Velocity Algorithm" section
-    - Add context from parent spec
-    - Update frontmatter (tags, related)
-Update original spec:
-  045-unified-dashboard/README.md
-    - Remove "Velocity Algorithm" section (-142 lines)
-    - Add reference: "See [spec 060](../060-velocity-algorithm/)"
-    - Update line count: 1,166 → 1,024 lines
-Cross-references:
-  ✓ Update 3 internal links
-  ✓ Add bidirectional relationship (related field)
-Apply isolation? (Y/n)
-```
-**Interactive mode**:
-```bash
-$ lean-spec isolate 045 --interactive
-Select sections to isolate:
-  [ ] 1. Overview
-  [ ] 2. Background
-  [ ] 3. Design
-  [x] 4. Velocity Algorithm
-  [ ] 5. Health Scoring
-  [x] 6. Chart Library Evaluation
-  [ ] 7. Implementation
-  [ ] 8. Testing
-Selected: Velocity Algorithm, Chart Library Evaluation
-These sections can be isolated together (related concerns).
-Create new spec:
-  1. Single spec for both sections
-  2. Two separate specs
-Selection: 2 █
-New spec names:
-  1. 060-velocity-algorithm
-  2. 061-chart-library-eval
-Proceed? (Y/n)
-```
-## Utility Commands
-### `lean-spec diff` - Show Transformation Diff
-```bash
-$ lean-spec diff 045 --before-after
-Comparing before/after split:
-Before:
-  045-unified-dashboard/README.md (4,800 tokens / 1,166 lines)
-After:
-  045-unified-dashboard/
-  ├── README.md (812 tokens / 203 lines)
-  ├── DESIGN.md (1,512 tokens / 378 lines)
-  └── TESTING.md (728 tokens / 182 lines)
-Total: 3,052 tokens / 763 lines
-Savings: 1,748 tokens / 403 lines (via compaction)
-```
-### `lean-spec preview` - Preview Transformation
-```bash
-$ lean-spec preview 045 \
-  --split=README.md:1-150,DESIGN.md:151-528
-Preview:
-  Would create 2 files from spec 045
-  README.md: 812 tokens / 150 lines
-  DESIGN.md: 1,512 tokens / 378 lines
-Use --apply to execute transformation
-```
-### `lean-spec rollback` - Undo Transformation
-```bash
-$ lean-spec rollback 045
-Found git history:
-  1. Split into sub-specs (2 hours ago) - commit abc123
-  2. Compact README.md (5 hours ago) - commit def456
-Select rollback point: 1
-✓ Git reset to commit xyz789
-✓ Spec 045 restored to pre-split state
-```
-## AI Agent Usage Patterns
-### Pattern 1: Detect and Split Oversized Spec
-```typescript
-// AI agent detects large spec during review
-const analysis = await exec('lean-spec analyze 045 --json');
-const data = JSON.parse(analysis);
-if (data.metrics.tokens > 3500) {
-  // AI analyzes structure and decides split points
-  const h2Sections = data.structure.filter(s => s.level === 2);
-  // Group related sections
-  const groups = [
-    { file: 'README.md', sections: h2Sections.slice(0, 2) },
-    { file: 'DESIGN.md', sections: h2Sections.slice(2, 5) },
-    { file: 'TESTING.md', sections: h2Sections.slice(5) }
-  ];
-  // Build command
-  const outputs = groups.map(g => {
-    const start = g.sections[0].lineRange[0];
-    const end = g.sections[g.sections.length - 1].lineRange[1];
-    return `--output=${g.file}:${start}-${end}`;
-  });
-  // Execute split
-  await exec(`lean-spec split 045 ${outputs.join(' ')} --update-refs`);
-  // Verify
-  const newTokens = await exec('lean-spec tokens 045/*');
-  // Confirm all files under 2,000 tokens
-}
-```
-### Pattern 2: Detect and Remove Redundancy
-```typescript
-// AI agent reads spec and detects duplicate content
-const content = await readFile('specs/045-unified-dashboard/README.md');
-const lines = content.split('\n');
-// AI identifies duplicate sections by semantic similarity
-const duplicates = [
-  { original: [145, 153], duplicate: [289, 297] },
-  { original: [201, 215], duplicate: [423, 437] }
-];
-// Remove duplicates (keep original, remove duplicate)
-const removes = duplicates
-  .map(d => `--remove=${d.duplicate[0]}-${d.duplicate[1]}`)
-  .join(' ');
-await exec(`lean-spec compact 045 ${removes}`);
-```
-### Pattern 3: Compress Completed Phases
-```typescript
-// AI agent detects completed phase in implementation spec
-const content = await readFile('specs/043-official-launch-02/README.md');
-const analysis = await exec('lean-spec analyze 043 --json');
-// AI reads phase 1 section (lines 142-284)
-const phase1Content = lines.slice(141, 284).join('\n');
-// AI generates summary
-const summary = `## ✅ Phase 1: Foundation (Completed 2025-11-05)
-Established first principles through comprehensive analysis.
-Key deliverable: specs/049-leanspec-first-principles/`;
-// Execute compression
-await exec(`lean-spec compress 043 --replace='142-284:${summary}'`);
-```
-### Pattern 4: Isolate Independent Concern
-```typescript
-// AI agent identifies section that should be separate spec
-const analysis = await exec('lean-spec analyze 045 --json');
-// AI finds "Velocity Algorithm" section is self-contained
-const velocitySection = analysis.structure.find(
-  s => s.section === 'Velocity Algorithm'
-);
-// Check dependencies (AI reads content and determines it's independent)
-const hasExternalDeps = false; // AI determined this
-if (!hasExternalDeps) {
-  // Execute isolation
-  await exec(`lean-spec isolate 045 \
-    --lines=${velocitySection.lineRange.join('-')} \
-    --to=060-velocity-algorithm \
-    --add-reference`);
-}
-```
-### Pattern 5: Full Transformation Pipeline
-```typescript
-// AI agent performs complete spec optimization
-async function optimizeSpec(specId: string) {
-  // 1. Analyze
-  const analysis = JSON.parse(
-    await exec(`lean-spec analyze ${specId} --json`)
-  );
-  // 2. Decide strategy based on metrics
-  if (analysis.metrics.tokens > 5000) {
-    // Critical: Must split immediately
-    await splitSpec(specId, analysis);
-  } else if (analysis.metrics.tokens > 3500) {
-    // Try compaction first, then split if still too large
-    await compactSpec(specId, analysis);
-    const recheck = JSON.parse(
-      await exec(`lean-spec analyze ${specId} --json`)
-    );
-    if (recheck.metrics.tokens > 3500) {
-      await splitSpec(specId, recheck);
-    }
-  }
-  // 3. Verify all files are healthy
-  const finalCheck = await exec(`lean-spec validate ${specId}`);
-  return finalCheck;
-}
-```
-## Global Options
-Available for all commands:
-```bash
---json             JSON output (default for AI agents)
---dry-run          Simulate without making changes
---force            Skip confirmations (use with caution)
---verbose, -v      Show detailed output (for human review)
---quiet, -q        Minimal output
---help, -h         Show command help
-```
-## Exit Codes
-```
-0   Success
-1   General error
-2   Invalid arguments
-3   Validation failed
-4   File operation failed
-```
----
-**Key Takeaway**: These tools are building blocks for AI agents. The agent provides the intelligence (what to split, where to split, what to remove), tools provide reliable execution.