specweave 0.30.11 → 0.30.13

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

@@ -0,0 +1,158 @@
+---
+name: specweave-docs:build
+description: Build static documentation site for deployment. Supports both public and internal docs. Outputs production-ready HTML/CSS/JS.
+---
+
+# Documentation Build Command
+
+Build production-ready static documentation site for deployment to any static host.
+
+## Usage
+
+```bash
+# Build INTERNAL docs (SpecWeave living documentation) - DEFAULT
+/specweave-docs:build
+
+# Build PUBLIC docs (end-user documentation)
+/specweave-docs:build --public
+```
+
+## Two Build Targets
+
+| Site | Output Directory | NPM Script |
+|------|------------------|------------|
+| **Internal** | `docs-site/build-internal/` | `docs:internal:build` |
+| **Public** | `docs-site/build/` | `docs:build` |
+
+## 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 "Building PUBLIC documentation..."
+  echo "Output: docs-site/build/"
+  echo ""
+  npm run docs:build
+  echo ""
+  echo "Build complete! Output: docs-site/build/"
+else
+  echo "Building INTERNAL documentation..."
+  echo "Output: docs-site/build-internal/"
+  echo ""
+  npm run docs:internal:build
+  echo ""
+  echo "Build complete! Output: docs-site/build-internal/"
+fi
+```
+
+## Output Structure
+
+```
+docs-site/build-internal/
+├── index.html              <- Landing page
+├── strategy/
+├── specs/
+├── architecture/
+│   └── adr/
+├── delivery/
+├── operations/
+├── governance/
+├── assets/
+│   ├── css/styles.[hash].css
+│   └── js/runtime.[hash].js
+└── sitemap.xml
+```
+
+## Deployment Options
+
+### 1. Preview Locally
+
+```bash
+# Internal docs
+cd docs-site && npm run serve:internal
+
+# Public docs
+cd docs-site && npm run serve
+```
+
+### 2. Netlify
+
+```bash
+cd docs-site
+npx netlify deploy --dir=build-internal --prod
+```
+
+### 3. Vercel
+
+```bash
+cd docs-site
+npx vercel --prod
+```
+
+### 4. GitHub Pages
+
+```bash
+# Copy build to docs folder (GitHub Pages expects /docs)
+cp -r docs-site/build-internal/* docs/
+git add docs/
+git commit -m "docs: update documentation site"
+git push
+```
+
+### 5. Static Server
+
+```bash
+npx serve docs-site/build-internal/
+```
+
+## Build vs Preview
+
+| Aspect | Preview | Build |
+|--------|---------|-------|
+| **Purpose** | Development | Production |
+| **Speed** | Instant | 10-30 seconds |
+| **Output** | Dev server | Static files |
+| **Hot Reload** | Yes | No |
+| **Optimization** | No | Yes (minified) |
+| **Use Case** | Writing docs | Deployment |
+
+## First-Time Setup
+
+If dependencies not installed:
+
+```bash
+npm run docs:install
+```
+
+## Troubleshooting
+
+### Build fails with broken links
+```bash
+# Preview first to find errors
+npm run docs:internal
+# Fix broken links, then build
+npm run docs:internal:build
+```
+
+### Out of memory
+```bash
+# Increase Node memory
+NODE_OPTIONS="--max-old-space-size=4096" npm run docs:internal:build
+```
+
+### Cache issues
+```bash
+cd docs-site && npm run clear && npm run build:internal
+```
+
+## See Also
+
+- `/specweave-docs:preview` - Preview docs locally with hot reload
+- `/specweave-docs:organize` - Organize large folders with themed indexes
+- `/specweave-docs:health` - Documentation health report

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

@@ -1,11 +1,16 @@
-# Docs Generate - Generate Documentation from Code
+---
+name: specweave-docs:generate
+description: Generate documentation from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications.
+---
+
+# Generate Documentation from Code
 
 Generate documentation automatically from TypeScript/JavaScript code, OpenAPI specs, GraphQL schemas, and SpecWeave specifications. Creates comprehensive API docs, type references, and usage examples.
 
 ## Usage
 
 ```
-/specweave-docs:docs-generate <source-type> <path> [options]
+/specweave-docs:generate <source-type> <path> [options]
 ```
 
 ## Source Types

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

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