specweave 1.0.593 → 2.0.3

package/plugins/specweave/commands/diagrams-generate.md

@@ -1,172 +0,0 @@
----
-description: Generate Mermaid architecture diagrams following C4 Model conventions for system documentation.
----
-
-# sw-diagrams:diagrams-generate
-
-Generate Mermaid architecture diagrams following C4 Model conventions.
-
-You are an expert in creating clear, comprehensive architecture diagrams using Mermaid syntax and C4 Model principles.
-
-## Your Task
-
-Generate architecture diagrams based on the user's requirements using Mermaid.js syntax. Follow these guidelines:
-
-### 1. Diagram Types
-
-Support these diagram types:
-- **C4 Context Diagrams**: System context with external actors and systems
-- **C4 Container Diagrams**: High-level technology choices and container relationships
-- **C4 Component Diagrams**: Internal component structure
-- **Sequence Diagrams**: Interaction flows and timing
-- **ER Diagrams**: Database schema and relationships
-- **Deployment Diagrams**: Infrastructure and deployment architecture
-
-### 2. C4 Model Conventions
-
-**Context Level**:
-```mermaid
-C4Context
-    title System Context diagram for [System Name]
-
-    Person(user, "User", "End user of the system")
-    System(systemA, "System A", "Core system")
-    System_Ext(systemB, "External System", "Third-party service")
-
-    Rel(user, systemA, "Uses")
-    Rel(systemA, systemB, "Integrates with", "HTTPS")
-```
-
-**Container Level**:
-```mermaid
-C4Container
-    title Container diagram for [System Name]
-
-    Container(web, "Web Application", "React", "User interface")
-    Container(api, "API", "Node.js", "Business logic")
-    ContainerDb(db, "Database", "PostgreSQL", "Data storage")
-
-    Rel(web, api, "Calls", "HTTPS/JSON")
-    Rel(api, db, "Reads/Writes", "SQL")
-```
-
-**Component Level**:
-```mermaid
-C4Component
-    title Component diagram for [Container Name]
-
-    Component(controller, "Controller", "Express", "Handles HTTP requests")
-    Component(service, "Service", "TypeScript", "Business logic")
-    Component(repository, "Repository", "TypeORM", "Data access")
-
-    Rel(controller, service, "Uses")
-    Rel(service, repository, "Uses")
-```
-
-### 3. Sequence Diagrams
-
-```mermaid
-sequenceDiagram
-    actor User
-    participant Frontend
-    participant API
-    participant Database
-
-    User->>Frontend: Login request
-    Frontend->>API: POST /auth/login
-    API->>Database: Validate credentials
-    Database-->>API: User data
-    API-->>Frontend: JWT token
-    Frontend-->>User: Success
-```
-
-### 4. ER Diagrams
-
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ ORDER_ITEM : contains
-    PRODUCT ||--o{ ORDER_ITEM : "ordered in"
-
-    USER {
-        uuid id PK
-        string email
-        string name
-        timestamp created_at
-    }
-
-    ORDER {
-        uuid id PK
-        uuid user_id FK
-        decimal total
-        timestamp created_at
-    }
-```
-
-### 5. Best Practices
-
-1. **Clear Labels**: Use descriptive names for all elements
-2. **Consistent Direction**: Top-to-bottom or left-to-right flow
-3. **Technology Stack**: Include tech choices in container/component diagrams
-4. **Relationships**: Label all connections with protocol/method
-5. **Color Coding**: Use consistent colors for similar element types
-6. **Boundaries**: Show system boundaries clearly
-
-### 6. Output Format
-
-Always wrap diagrams in proper Mermaid code blocks:
-
-\`\`\`mermaid
-[diagram code]
-\`\`\`
-
-Include:
-- Diagram title
-- Legend if needed
-- Notes for complex interactions
-- Tech stack documentation
-
-### 7. Validation
-
-Ensure diagrams:
-- Use valid Mermaid syntax
-- Follow C4 conventions
-- Are readable at default zoom
-- Include all requested elements
-- Show data flow direction clearly
-
-## Example Usage
-
-**User**: "Create a C4 context diagram for an e-commerce system"
-
-**Response**:
-```mermaid
-C4Context
-    title E-Commerce System - Context Diagram
-
-    Person(customer, "Customer", "Shops for products online")
-    Person(admin, "Admin", "Manages products and orders")
-
-    System(ecommerce, "E-Commerce Platform", "Online shopping system")
-    System_Ext(payment, "Payment Gateway", "Processes payments")
-    System_Ext(shipping, "Shipping Provider", "Handles delivery")
-    System_Ext(email, "Email Service", "Sends notifications")
-
-    Rel(customer, ecommerce, "Browses products, places orders")
-    Rel(admin, ecommerce, "Manages catalog, views analytics")
-    Rel(ecommerce, payment, "Processes payments", "HTTPS/API")
-    Rel(ecommerce, shipping, "Creates shipments", "HTTPS/API")
-    Rel(ecommerce, email, "Sends notifications", "SMTP")
-```
-
-## When to Use
-
-This command is ideal for:
-- System architecture documentation
-- Technical design reviews
-- Database schema visualization
-- API interaction flows
-- Deployment architecture
-- Component relationships
-
-Generate diagrams that are clear, comprehensive, and follow industry best practices!

package/plugins/specweave/commands/discrepancies.md

@@ -1,142 +0,0 @@
----
-description: View and manage code-to-spec discrepancies. Detects API changes, function signature mismatches, and documentation gaps. Supports brownfield analysis and code-spec comparison.
----
-
-# Discrepancies Command
-
-View and manage documentation discrepancies. Supports two modes:
-1. **Code-to-Spec**: Real-time discrepancies between code and specs
-2. **Brownfield**: Documentation gaps detected by brownfield analysis
-
-## Usage
-
-```bash
-# Brownfield discrepancies (documentation gaps)
-sw:discrepancies                  # List pending brownfield discrepancies
-sw:discrepancies --module payment # Filter by module name
-sw:discrepancies --type missing-docs    # Filter by type
-sw:discrepancies --priority critical    # Filter by priority
-sw:discrepancies show DISC-0001   # View details
-sw:discrepancies ignore DISC-0001 "False positive"  # Ignore with reason
-
-# Code-to-spec discrepancies (legacy)
-sw:discrepancies --check          # Run code-spec check now
-sw:discrepancies --severity major # Filter by severity
-```
-
-## Arguments
-
-**Brownfield mode (default)**:
-- `--module <name>`: Filter by module name (e.g., "payment-service")
-- `--type <type>`: Filter by type: `missing-docs`, `stale-docs`, `knowledge-gap`, `orphan-doc`, `missing-adr`
-- `--priority <level>`: Filter by priority: `critical`, `high`, `medium`, `low`
-- `--status <status>`: Filter by status: `pending`, `in-progress`, `resolved`, `ignored`
-
-**Code-to-spec mode**:
-- `--check`: Run discrepancy detection now
-- `--severity <level>`: Filter by severity: `trivial`, `minor`, `major`, `breaking`
-
-**Common**:
-- `--json`: Output as JSON for scripting
-
-## Subcommands
-
-### list (default)
-
-Lists detected discrepancies with severity, type, and description.
-
-```
-DETECTED DISCREPANCIES (5)
-
-DISC-0001   BREAKING   api-route          POST /api/users removed
-DISC-0002   MAJOR      function-signature  getUserById params changed
-DISC-0003   MINOR      api-route          GET /api/orders path changed
-DISC-0004   TRIVIAL    type-definition    User type updated
-DISC-0005   MAJOR      api-route          New DELETE /api/users/:id
-
-Use 'sw:discrepancies show <id>' to view details
-Use 'sw:discrepancies accept <id>' to apply patch
-```
-
-### show <id>
-
-Shows full discrepancy details with recommended action and patch.
-
-```
-DISCREPANCY DETAILS
-
-ID:          DISC-0002
-Type:        function-signature
-Category:    modified
-Severity:    major
-Risk:        medium
-
-Spec Value:  getUserById(id: string): User
-Code Value:  getUserById(id: string, options?: Options): User | null
-
-Spec File:   docs/api.md:45
-Code File:   src/services/user.ts:123
-
-Description: Function signature has changed from documented version.
-             Code is the source of truth - specs should be updated.
-
-Recommended: review-required
-Patch Available: Yes
-
-Use 'sw:discrepancies accept DISC-0002' to apply patch
-Use 'sw:discrepancies dismiss DISC-0002' to mark intentional
-```
-
-### check
-
-Run discrepancy detection immediately.
-
-```
-Running discrepancy check...
-
-Analyzing:
-  TypeScript functions: 156 exported
-  Type definitions: 89 exported
-  API routes: 34 detected
-
-Comparing against specs:
-  Parsed 12 spec files
-
-Results:
-  Found 5 discrepancies
-  - Breaking: 1
-  - Major: 2
-  - Minor: 1
-  - Trivial: 1
-
-Use 'sw:discrepancies' to view list
-```
-
-### accept <id>
-
-Apply the recommended patch to update specs.
-
-```
-Applying patch for DISC-0002...
-
-File:    docs/api.md
-Line:    45
-Change:  getUserById(id: string): User
-      ->  getUserById(id: string, options?: Options): User | null
-
-Patch applied successfully
-Remaining: 4 discrepancies
-```
-
-### dismiss <id>
-
-Mark a discrepancy as intentional (won't be flagged again).
-
-```
-Dismissed DISC-0002 (marked as intentional)
-Remaining: 4 discrepancies
-```
-
-## Related
-
-- `sw:sync-monitor`: Dashboard showing discrepancy count

package/plugins/specweave/commands/discrepancy-to-increment.md

@@ -1,188 +0,0 @@
----
-description: Convert brownfield discrepancies into a new increment for systematic documentation improvement. Groups by module, generates spec with ACs, and tracks resolution.
----
-
-# Discrepancy to Increment Command
-
-Convert one or more brownfield discrepancies into a new increment for systematic documentation improvement.
-
-## Usage
-
-```bash
-sw:discrepancy-to-increment DISC-0001
-sw:discrepancy-to-increment DISC-0001 DISC-0002 DISC-0003
-sw:discrepancy-to-increment --module payment-service
-```
-
-## Arguments
-
-- `<discrepancy-ids>`: One or more discrepancy IDs to convert (e.g., DISC-0001 DISC-0002)
-- `--module <name>`: Convert all pending discrepancies for a specific module
-- `--type <type>`: Convert all discrepancies of a specific type
-- `--priority <level>`: Convert all discrepancies at or above a priority level
-- `--dry-run`: Preview what would be created without making changes
-
-## Process
-
-1. **Read Discrepancy Details**
-   - Load specified discrepancies from `.specweave/discrepancies/`
-   - Verify all discrepancies exist and are in `pending` status
-
-2. **Group by Module** (if multiple)
-   - If discrepancies span multiple modules, ask if user wants:
-     - Single increment covering all modules
-     - Separate increments per module
-
-3. **Generate Increment ID with Validation**
-   - Get next available increment number
-   - **Validate increment number** using increment-validator:
-     ```typescript
-     import { validateIncrementNumber, logValidationResult } from './src/core/increment-validator.js';
-
-     // Get all existing increments
-     const existingIncrements = [
-       ...fs.readdirSync('.specweave/increments/'),
-       ...fs.readdirSync('.specweave/increments/_archive/').map(f => `_archive/${f}`),
-     ].filter(f => /^\d{4}-/.test(f));
-
-     // Get next number
-     const nextNumber = getNextIncrementNumber();
-
-     // Validate (should always be sequential for discrepancy-to-increment)
-     const result = validateIncrementNumber(nextNumber, existingIncrements);
-     logValidationResult(result);
-
-     if (!result.isValid) {
-       throw new Error('Cannot generate increment ID. See validation errors above.');
-     }
-
-     // Use validated number
-     const incrementId = `${nextNumber}-${moduleName}-docs-improvement`;
-     ```
-   - Include discrepancy context in spec.md
-   - Generate user stories from discrepancies
-   - Link code/doc locations
-
-4. **Update Discrepancy Status**
-   - Change status from `pending` to `in-progress`
-   - Add `incrementId` reference
-
-5. **On Increment Completion**
-   - When increment closes via `sw:done`
-   - All linked discrepancies auto-marked `resolved`
-   - Archived to `resolved/YYYY-MM/`
-
-## Example Output
-
-```
-🔄 Converting discrepancies to increment...
-
-Selected discrepancies:
-  ├─ DISC-0001: missing-docs (payment-service)
-  ├─ DISC-0002: missing-docs (payment-service)
-  └─ DISC-0003: stale-docs (payment-service)
-
-Module: payment-service
-Total: 3 discrepancies
-
-Generated increment: 0087-payment-docs-improvement
-
-📝 spec.md created with:
-  • 1 user story: Document payment-service module
-  • 3 acceptance criteria (one per discrepancy)
-  • Links to affected code locations
-
-Updated discrepancy status:
-  ├─ DISC-0001: pending → in-progress
-  ├─ DISC-0002: pending → in-progress
-  └─ DISC-0003: pending → in-progress
-
-Next steps:
-  1. Review: .specweave/increments/0087-payment-docs-improvement/spec.md
-  2. Plan: sw:plan 0087
-  3. Execute: sw:do 0087
-```
-
-## Generated Spec Structure
-
-```markdown
----
-increment: 0087-payment-docs-improvement
-status: planning
-type: documentation
----
-
-# Documentation Improvement: payment-service
-
-## Context
-
-This increment addresses documentation gaps detected during brownfield analysis.
-
-### Source Discrepancies
-
-| ID | Type | Priority | Summary |
-|----|------|----------|---------|
-| DISC-0001 | missing-docs | high | 12 undocumented exports |
-| DISC-0002 | missing-docs | medium | processPayment function lacks docs |
-| DISC-0003 | stale-docs | high | Payment flow diagram outdated |
-
-## User Story
-
-### US-001: Document payment-service Module
-
-**As a** new developer joining the team,
-**I want** comprehensive documentation for the payment-service module,
-**So that** I can understand and contribute to the payment flow.
-
-#### Acceptance Criteria
-
-- [ ] **AC-US1-01**: Document all 12 undocumented exports (DISC-0001)
-- [ ] **AC-US1-02**: Add JSDoc to processPayment function (DISC-0002)
-- [ ] **AC-US1-03**: Update payment flow diagram to match current implementation (DISC-0003)
-
-## Technical Notes
-
-### Affected Files
-
-From DISC-0001:
-- `src/payment/processor.ts`
-- `src/payment/validator.ts`
-- `src/payment/types.ts`
-
-From DISC-0003:
-- `docs/modules/payment.md` (diagram needs update)
-```
-
-## Completion Hook
-
-When the increment is closed with `sw:done`:
-
-```typescript
-// Automatically triggered by increment completion
-async function onIncrementComplete(incrementId: string) {
-  const manager = new BrownfieldDiscrepancyManager(projectPath);
-
-  // Find all discrepancies linked to this increment
-  const discrepancies = await manager.listDiscrepancies({
-    incrementId,
-    status: 'in-progress'
-  });
-
-  // Resolve each discrepancy
-  for (const disc of discrepancies) {
-    await manager.resolveDiscrepancy(disc.id, {
-      type: 'doc-updated',
-      resolvedAt: new Date().toISOString(),
-      resolvedBy: 'increment-completion'
-    });
-  }
-
-  console.log(`✅ Resolved ${discrepancies.length} discrepancies`);
-}
-```
-
-## Related
-
-- `sw:discrepancies` - View pending discrepancies
-- `sw:increment` - Create new increment manually
-- `sw:done` - Complete increment (triggers resolution)

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

@@ -1,159 +0,0 @@
----
-description: Build static documentation site for deployment. Validates docs first, auto-fixes issues, auto-setup on first run. Outputs production-ready HTML/CSS/JS.
----
-
-# Documentation Build Command
-
-Build production-ready static documentation site for deployment to any static host.
-
-**CRITICAL**: Runs pre-flight validation to catch issues BEFORE building.
-
-## Your Task
-
-**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
-
-### Step 1: CRITICAL - Run Pre-Flight Validation
-
-**ALWAYS validate BEFORE building to prevent cryptic webpack errors!**
-
-```typescript
-import { DocsValidator } from '../../../src/utils/docs-validator.js';
-
-const validator = new DocsValidator({
-  docsPath: '.specweave/docs/internal',
-  autoFix: true,  // Auto-fix common issues
-});
-
-console.log('\n🔍 Running pre-build validation...\n');
-const result = await validator.validate();
-
-// Show summary
-console.log(DocsValidator.formatResult(result));
-
-// If errors remain after auto-fix, STOP and report
-if (!result.valid) {
-  console.log('\n❌ Documentation has errors that must be fixed before build.');
-  console.log('   Fix the issues above, then try again.\n');
-  process.exit(1);
-}
-
-console.log('\n✅ Validation passed! Proceeding with build...\n');
-```
-
-### Step 2: Ensure Docusaurus is Set Up
-
-```bash
-# Check if Docusaurus is set up
-if [ ! -d ".specweave/cache/docs-site/node_modules" ]; then
-  echo "Setting up Docusaurus first..."
-  # Run the same setup as view command (see view.md for full setup)
-  # After setup, continue to build
-fi
-```
-
-If not set up, follow the same setup steps as `/docs:view` (Step 3 in view.md).
-
-### Step 3: Run Build
-
-```bash
-cd .specweave/cache/docs-site && npm run build
-```
-
-### Step 3: Report Output
-
-```bash
-echo ""
-echo "📦 Build Complete!"
-echo ""
-echo "   Output: .specweave/cache/docs-site/build/"
-echo ""
-echo "   Deploy with:"
-echo "   • npx serve .specweave/cache/docs-site/build/"
-echo "   • Copy to your static host"
-echo ""
-```
-
-## Output Structure
-
-```
-.specweave/cache/docs-site/build/
-├── 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
-npx serve .specweave/cache/docs-site/build/
-```
-
-### 2. Copy to Custom Location
-
-```bash
-# Copy build to docs folder for GitHub Pages
-cp -r .specweave/cache/docs-site/build/* docs/
-git add docs/
-git commit -m "docs: update documentation site"
-```
-
-### 3. Netlify/Vercel
-
-```bash
-# Point your deployment to:
-.specweave/cache/docs-site/build/
-```
-
-## 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 |
-
-## Troubleshooting
-
-### Build fails with broken links
-```bash
-# View docs first to find errors
-/docs:view
-# Fix broken links, then build
-/docs:build
-```
-
-### Out of memory
-```bash
-NODE_OPTIONS="--max-old-space-size=4096" npm run build
-```
-
-### Cache issues
-```bash
-cd .specweave/cache/docs-site && npm run clear && npm run build
-```
-
-### Reinstall from scratch
-```bash
-rm -rf .specweave/cache/docs-site
-/docs:build
-```
-
-## See Also
-
-- `/docs:view` - View docs locally with hot reload
-- `/docs:organize` - Organize large folders with themed indexes
-- `/docs:health` - Documentation health report