specweave 0.30.12 → 0.30.14

package/plugins/specweave-docs/commands/health.md

@@ -0,0 +1,268 @@
+---
+name: specweave-docs:health
+description: Documentation health report - analyzes docs for freshness, coverage, naming violations, duplicates, and provides recommendations.
+---
+
+# Documentation Health Report
+
+Analyze your documentation for health issues including freshness, coverage, naming violations, duplicates, and spec-code mismatches.
+
+## Usage
+
+```bash
+# Full health report
+/specweave-docs:health
+
+# Include archived documents
+/specweave-docs:health --include-archived
+
+# Output as JSON
+/specweave-docs:health --format json
+
+# Save report to file
+/specweave-docs:health --output health-report.md
+```
+
+## Your Task
+
+Execute the enterprise documentation analyzer:
+
+```typescript
+import { EnterpriseDocAnalyzer, generateEnterpriseReport } from '../../src/living-docs/enterprise-analyzer.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const projectPath = process.cwd();
+
+// Create analyzer
+const analyzer = new EnterpriseDocAnalyzer({
+  projectPath,
+  includeArchived: false, // Set true to include archived docs
+});
+
+// Run analysis
+console.log('\nAnalyzing Documentation Health...\n');
+const report = await analyzer.analyze();
+
+// Generate markdown report
+const markdownReport = generateEnterpriseReport(report);
+
+// Display summary
+console.log(`
+DOCUMENTATION HEALTH REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall Score: ${report.healthScore.overall}% (Grade: ${report.healthScore.grade})
+
+Metrics:
+  Freshness: ${report.healthScore.freshness}%
+  Coverage:  ${report.healthScore.coverage}%
+  Accuracy:  ${report.healthScore.accuracy}%
+
+Categories: ${report.categories.length}
+Total Documents: ${report.totalDocuments}
+
+Issues Found:
+  Spec-Code Mismatches: ${report.mismatches.length}
+  Naming Violations: ${report.namingViolations.length}
+  Duplicates: ${report.duplicates.length}
+  Discrepancies: ${report.discrepancies.length}
+
+Recommendations: ${report.recommendations.length}
+`);
+
+// Show recommendations
+if (report.recommendations.length > 0) {
+  console.log('RECOMMENDATIONS');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  for (const rec of report.recommendations) {
+    console.log(`• ${rec}`);
+  }
+}
+
+// Optionally save full report
+const outputPath = path.join(projectPath, '.specweave/docs/ENTERPRISE-HEALTH.md');
+fs.writeFileSync(outputPath, markdownReport);
+console.log(`\nFull report saved to: ${outputPath}`);
+```
+
+## Health Metrics
+
+### Overall Score (0-100%)
+
+Weighted combination of:
+- **Freshness** (20%): Documents updated in last 30 days
+- **Coverage** (30%): Documents with acceptance criteria
+- **Accuracy** (50%): ACs without spec-code mismatches + naming compliance
+
+### Grade Scale
+
+| Grade | Score Range | Meaning |
+|-------|-------------|---------|
+| A | 90-100% | Excellent documentation health |
+| B | 80-89% | Good, minor improvements needed |
+| C | 70-79% | Acceptable, several issues |
+| D | 60-69% | Below standard, action required |
+| F | <60% | Critical issues, immediate attention |
+
+## Issue Types
+
+### Spec-Code Mismatches
+
+| Type | Description |
+|------|-------------|
+| `ghost_completion` | AC marked complete but no code evidence found |
+| `partial_implementation` | Very little code evidence (<10 lines) |
+| `undocumented_code` | Code exists without corresponding spec |
+| `spec_drift` | Spec and code have diverged |
+
+### Naming Violations
+
+| Type | Severity | Example |
+|------|----------|---------|
+| `all_caps` | Warning | `CIRCUIT-BREAKER.md` |
+| `mixed_case` | Warning | `CircuitBreaker.md` |
+| `date_suffix` | Info | `feature-2025-11-24.md` |
+| `no_extension` | Error | `readme` (missing .md) |
+
+### Duplicates
+
+| Type | Description |
+|------|-------------|
+| `exact` | Identical content |
+| `near_duplicate` | Very similar content (>90%) |
+| `same_title` | Same normalized title |
+
+### Discrepancies
+
+| Type | Description |
+|------|-------------|
+| `broken_link` | Link to non-existent file |
+| `orphaned_reference` | Reference to deleted increment |
+| `outdated_version` | Old version numbers (v0.x) |
+| `conflicting_info` | Contradictory information |
+
+## Report Sections
+
+### 1. Health Score Summary
+
+```
+| Metric | Score | Grade |
+|--------|-------|-------|
+| Overall | 85% | B |
+| Freshness | 72% | - |
+| Coverage | 65% | - |
+| Accuracy | 92% | - |
+```
+
+### 2. Documentation Categories
+
+```
+| Category | Documents | Last Updated |
+|----------|-----------|--------------|
+| Feature Specs | 45 | 12/3/2025 |
+| Architecture | 148 | 12/3/2025 |
+| ADRs | 147 | 12/3/2025 |
+```
+
+### 3. Spec-Code Mismatches
+
+```
+| AC ID | Type | Confidence | File |
+|-------|------|------------|------|
+| AC-US1-01 | ghost_completion | 70% | spec-0045.md |
+```
+
+### 4. Naming Violations
+
+```
+| File | Type | Severity | Expected |
+|------|------|----------|----------|
+| CIRCUIT-BREAKER.md | all_caps | Warning | lowercase-kebab.md |
+```
+
+### 5. Recommendations
+
+Actionable suggestions based on analysis:
+- Update stale documentation
+- Add acceptance criteria
+- Fix naming conventions
+- Consolidate duplicates
+- Run `/specweave-docs:organize` for large folders
+
+## Output Example
+
+```
+DOCUMENTATION HEALTH REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overall Score: 78% (Grade: C)
+
+Metrics:
+  Freshness: 65%
+  Coverage:  42%
+  Accuracy:  89%
+
+Categories: 6
+Total Documents: 708
+
+Issues Found:
+  Spec-Code Mismatches: 12
+  Naming Violations: 8
+  Duplicates: 3
+  Discrepancies: 15
+
+Recommendations: 5
+
+RECOMMENDATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+• Documentation freshness is low. Consider reviewing docs over 30 days old.
+• Documentation coverage is limited. Add acceptance criteria to more documents.
+• 8 files use ALL CAPS naming. Rename to lowercase-kebab-case.
+• 3 sets of duplicate documents detected. Consider consolidating.
+• "ADRs" has 147 files. Run /specweave-docs:organize to generate themed indexes.
+
+Full report saved to: .specweave/docs/ENTERPRISE-HEALTH.md
+```
+
+## Integrations
+
+### CI/CD Health Check
+
+```yaml
+# .github/workflows/docs-health.yml
+name: Documentation Health
+
+on:
+  push:
+    paths:
+      - '.specweave/docs/**'
+
+jobs:
+  health-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Check Documentation Health
+        run: |
+          npx specweave docs:health --format json > health.json
+          SCORE=$(jq '.healthScore.overall' health.json)
+          if [ $SCORE -lt 70 ]; then
+            echo "Documentation health below threshold: $SCORE%"
+            exit 1
+          fi
+```
+
+### Scheduled Reports
+
+```bash
+# Run weekly health check
+0 9 * * 1 cd /project && npx specweave docs:health --output weekly-health.md
+```
+
+## See Also
+
+- `/specweave-docs:organize` - Organize large folders with themed indexes
+- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:generate` - Generate docs from code

package/plugins/specweave-docs/commands/{docs-init.md → init.md}

@@ -1,11 +1,16 @@
-# Docs Init - Initialize Documentation Site
+---
+name: specweave-docs:init
+description: Initialize Docusaurus documentation site with spec-driven structure, living docs integration, and SpecWeave-optimized configuration.
+---
+
+# Initialize Documentation Site
 
 Initialize a Docusaurus documentation site with spec-driven documentation structure, living docs integration, and SpecWeave-optimized configuration.
 
 ## Usage
 
 ```
-/specweave-docs:docs-init [options]
+/specweave-docs:init [options]
 ```
 
 ## What I Do
@@ -298,14 +303,14 @@ themeConfig: {
 
 ### Custom Output Directory
 ```bash
-/specweave-docs:docs-init --output ./documentation
+/specweave-docs:init --output ./documentation
 ```
 
 ## Related Commands
 
-- `/specweave-docs:docs-generate` - Generate docs from code/specs
-- `/specweave-docs-preview:preview` - Launch documentation preview server
-- `/specweave-docs-preview:build` - Build static documentation site
+- `/specweave-docs:generate` - Generate docs from code/specs
+- `/specweave-docs:preview` - Launch documentation preview server
+- `/specweave-docs:build` - Build static documentation site
 
 ## Requirements
 

package/plugins/specweave-docs/commands/organize.md

@@ -0,0 +1,184 @@
+---
+name: specweave-docs:organize
+description: Smart documentation organization - generates themed navigation indexes for large folders. Works seamlessly with Docusaurus preview.
+---
+
+# Smart Documentation Organizer
+
+Automatically organize large documentation folders by detecting themes and generating navigable category indexes.
+
+## Why Organize?
+
+When folders grow beyond 30+ files, navigation becomes painful:
+- ADRs (147 files) - hard to find sync vs hooks vs testing decisions
+- Specs - many features across different domains
+- Guides - mixed topics without clear structure
+
+**Solution**: Generate themed category indexes WITHOUT moving files (preserves URLs).
+
+## Usage
+
+```bash
+# Analyze and organize all internal docs
+/specweave-docs:organize
+
+# Analyze specific folder only
+/specweave-docs:organize --folder architecture/adr
+
+# Preview without generating files
+/specweave-docs:organize --dry-run
+
+# Force regeneration even if under threshold
+/specweave-docs:organize --force
+
+# Set custom threshold (default: 30)
+/specweave-docs:organize --threshold 20
+```
+
+## Your Task
+
+Execute the smart documentation organizer:
+
+```typescript
+import { SmartDocOrganizer, organizeDocumentation } from '../../src/living-docs/smart-doc-organizer.js';
+import * as path from 'path';
+
+const projectPath = process.cwd();
+
+// Option 1: Quick organize all internal docs
+const result = await organizeDocumentation(projectPath, {
+  dryRun: false,  // Set true to preview
+  thresholdForOrganization: 30,
+});
+
+console.log(result.summary);
+
+// Option 2: Analyze specific folder
+const organizer = new SmartDocOrganizer({
+  projectPath,
+  thresholdForOrganization: 30,
+  generateIndexes: true,
+  dryRun: false,
+});
+
+const adrPath = path.join(projectPath, '.specweave/docs/internal/architecture/adr');
+const plan = await organizer.analyzeFolder(adrPath);
+
+console.log(`
+DOCUMENTATION ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Folder: ${plan.folder}
+Total Files: ${plan.totalFiles}
+Needs Organization: ${plan.needsOrganization ? 'Yes' : 'No'}
+
+Theme Categories:
+${plan.themeCategories
+  .filter(c => c.count >= 3)
+  .map(c => `  ${c.theme.icon} ${c.theme.name}: ${c.count} files`)
+  .join('\n')}
+
+Uncategorized: ${plan.uncategorized.length} files
+`);
+
+// Generate indexes if needed
+if (plan.needsOrganization) {
+  const generatedFiles = await organizer.generateCategoryIndexes(plan);
+  console.log(`\nGenerated ${generatedFiles.length} index files`);
+}
+```
+
+## What Gets Generated
+
+### 1. Category Index (`_categories.md`)
+
+Main navigation hub with:
+- Links to all theme categories
+- Quick stats (total docs, categorized count)
+- Recently updated documents
+
+### 2. Theme Indexes (`_index-{theme}.md`)
+
+Per-theme navigation with:
+- All files in that category
+- Sub-grouping for large themes (15+ files)
+- Sorted alphabetically
+
+## Theme Detection
+
+The organizer automatically detects these themes:
+
+| Icon | Theme | Keywords |
+|------|-------|----------|
+| 🔄 | Synchronization | sync, integration, bidirectional |
+| 🐙 | GitHub | github, issue, actions |
+| 🪝 | Hooks | hook, event, trigger |
+| 🔌 | External Tools | jira, ado, area-path |
+| 🧪 | Testing | test, fixture, coverage |
+| 🏗️ | Brownfield | brownfield, migration, legacy |
+| ⚡ | Performance | cache, pagination, batch |
+| 🔒 | Security | permission, auth, token |
+| 📦 | Increments | increment, status, lifecycle |
+| ⚙️ | Configuration | config, env, setup |
+| 📚 | Documentation | doc, spec, naming |
+
+## Output Example
+
+```
+DOCUMENTATION ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Folder: architecture/adr
+Total Files: 147
+Needs Organization: Yes
+
+Theme Categories:
+  🔄 Synchronization & Integration: 23 files
+  🐙 GitHub Integration: 18 files
+  🪝 Hooks & Events: 15 files
+  🧪 Testing & Quality: 12 files
+  🔌 External Tools (ADO, JIRA): 11 files
+  📦 Increment Lifecycle: 10 files
+  ⚡ Performance & Optimization: 9 files
+  ⚙️ Configuration & Setup: 8 files
+
+Uncategorized: 14 files
+
+Generated 9 index files:
+  - _categories.md
+  - _index-sync.md
+  - _index-github.md
+  - _index-hooks.md
+  - _index-testing.md
+  - _index-external-tools.md
+  - _index-increments.md
+  - _index-performance.md
+  - _index-config.md
+```
+
+## Docusaurus Integration
+
+After running this command, use:
+
+```bash
+/specweave-docs:preview
+```
+
+The generated indexes will appear in the sidebar:
+- **Browse by Category** - main hub
+- **Synchronization & Integration** - themed section
+- **GitHub Integration** - themed section
+- etc.
+
+## Best Practices
+
+1. **Run periodically** - As docs grow, re-run to update indexes
+2. **Review uncategorized** - Files without themes may need better naming
+3. **Check Docusaurus** - Preview after organizing to verify navigation
+4. **Don't move files** - Indexes are virtual, original URLs preserved
+
+## See Also
+
+- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:build` - Build static documentation site
+- `/specweave-docs:health` - Documentation health report

package/plugins/specweave-docs/commands/preview.md

@@ -0,0 +1,138 @@
+---
+name: specweave-docs:preview
+description: Launch Docusaurus documentation server. Supports both public (port 3016) and internal (port 3015) documentation sites.
+---
+
+# Documentation Preview Command
+
+Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
+
+## Usage
+
+```bash
+# Preview INTERNAL docs (SpecWeave living documentation) - DEFAULT
+/specweave-docs:preview
+
+# Preview PUBLIC docs (end-user documentation)
+/specweave-docs:preview --public
+```
+
+## Two Documentation Sites
+
+| Site | Port | Content | NPM Script |
+|------|------|---------|------------|
+| **Internal** | 3015 | `.specweave/docs/internal/` | `docs:internal` |
+| **Public** | 3016 | `docs-site/docs/` | `docs:dev` |
+
+## Your Task
+
+Execute the appropriate npm script based on user flags:
+
+```bash
+# Check if user wants public docs
+PUBLIC_FLAG="${1:-}"
+
+cd /path/to/project
+
+if [ "$PUBLIC_FLAG" = "--public" ]; then
+  echo "Launching PUBLIC documentation on port 3016..."
+  echo "Content: docs-site/docs/"
+  echo ""
+  npm run docs:dev
+else
+  echo "Launching INTERNAL documentation on port 3015..."
+  echo "Content: .specweave/docs/internal/"
+  echo ""
+  npm run docs:internal
+fi
+```
+
+### Alternative: Run directly with npx
+
+If in a fresh project without the docs-site setup:
+
+```bash
+# For internal docs
+cd docs-site && npm run start:internal
+
+# For public docs
+cd docs-site && npm run start
+```
+
+## What You Get
+
+- **Hot reload** - Edit markdown, see changes instantly
+- **Auto sidebar** - Generated from folder structure
+- **Mermaid diagrams** - Architecture diagrams render beautifully
+- **Dark/light mode** - Toggle in navbar
+- **Local search** - Instant search across all docs
+- **Mobile responsive** - Works on any device
+
+## First-Time Setup
+
+If `docs-site/node_modules` doesn't exist:
+
+```bash
+npm run docs:install
+```
+
+This installs Docusaurus dependencies (~200MB, ~30 seconds).
+
+## Ports
+
+| Script | Port | URL |
+|--------|------|-----|
+| `docs:dev` | 3016 | http://localhost:3016 |
+| `docs:internal` | 3015 | http://localhost:3015 |
+
+## Internal Docs Structure
+
+```
+.specweave/docs/internal/
+├── strategy/        → Product strategy
+├── specs/           → Feature specifications (708 files!)
+│   └── specweave/
+│       ├── FS-001/  → Feature folders
+│       ├── FS-002/
+│       └── ...
+├── architecture/    → ADRs, HLDs, diagrams
+├── delivery/        → Release plans, guides
+├── operations/      → Runbooks, NFRs
+└── governance/      → Standards, conventions
+```
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `docusaurus.config.ts` | Public docs config |
+| `docusaurus.config.internal.ts` | Internal docs config |
+| `sidebars.ts` | Public docs sidebar |
+| `sidebars.internal.ts` | Internal docs sidebar |
+
+## Troubleshooting
+
+### Port already in use
+```bash
+# Find process using port
+lsof -i :3015
+
+# Kill it
+kill -9 <PID>
+```
+
+### Missing dependencies
+```bash
+npm run docs:install
+```
+
+### Build errors
+```bash
+cd docs-site && npm run clear && npm run start:internal
+```
+
+## See Also
+
+- `/specweave-docs:build` - Build static site for deployment
+- `/specweave-docs:organize` - Generate themed indexes for large folders
+- `/specweave-docs:health` - Documentation health report