specweave 0.30.19 → 0.32.2

package/plugins/specweave/commands/specweave-sync-specs.md

@@ -1,446 +1,340 @@
 ---
 name: specweave:sync-specs
-description: Sync increment specifications to living docs structure. Auto-generates feature IDs for greenfield increments (FS-XXX). Use after completing an increment to make it visible in living docs.
+description: Sync ALL increment specifications to living docs structure by default. Creates FS-XXX folders for each increment. Use with increment ID to sync single increment.
 ---
 
 # Sync Increment Specifications to Living Docs
 
-Syncs increment specs to living docs structure for stakeholder visibility. Auto-generates feature IDs for greenfield increments.
+**DEFAULT BEHAVIOR**: Syncs ALL increments to living docs (not just one!)
 
 ---
 
-## STEP 1: Parse Arguments
+## STEP 1: Parse Arguments & Determine Mode
 
 ```
-Arguments provided: [user's arguments]
+Arguments provided: $ARGUMENTS
 ```
 
-**Parse the input**:
-- Check for increment ID: `0001`, `0002`, etc.
-- If no increment ID: find the most recent increment
-- Check for options: `--force`, `--dry-run`
+**Parse the input to determine sync mode**:
 
-**Find increment**:
-```bash
-if [[ -z "$INCREMENT_ID" ]]; then
-  # Find most recent increment
-  INCREMENT_ID=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}-' | sort -r | head -1)
-fi
-
-# Verify increment exists
-INCREMENT_PATH=".specweave/increments/$INCREMENT_ID"
-if [[ ! -d "$INCREMENT_PATH" ]]; then
-  echo "❌ Error: Increment $INCREMENT_ID not found"
-  exit 1
-fi
-```
+| Input | Mode | Action |
+|-------|------|--------|
+| `/specweave:sync-specs` | **ALL** (default) | Sync ALL increments |
+| `/specweave:sync-specs --all` | **ALL** (explicit) | Sync ALL increments |
+| `/specweave:sync-specs 0106` | **SINGLE** | Sync only increment 0106 |
+| `/specweave:sync-specs 0106 --dry-run` | **SINGLE + DRY** | Preview sync for 0106 |
+| `/specweave:sync-specs --dry-run` | **ALL + DRY** | Preview sync for ALL |
 
-**Output**:
-```
-🎯 Target increment: {increment_id}
-📁 Increment path: .specweave/increments/{increment_id}
-🔄 Mode: Specs-only sync (Universal Hierarchy)
-
-Processing...
-```
+**CRITICAL**: No increment ID = sync ALL increments (this is the DEFAULT!)
 
 ---
 
-## STEP 2: Check Prerequisites
-
-### 2.1 Verify Spec File Exists
+## STEP 2: Execute Sync Based on Mode
 
-```bash
-SPEC_FILE="$INCREMENT_PATH/spec.md"
-if [[ ! -f "$SPEC_FILE" ]]; then
-  echo "❌ Error: No spec.md found in increment $INCREMENT_ID"
-  echo "   Cannot sync specs without a spec file"
-  exit 1
-fi
-```
+### MODE A: Sync ALL Increments (Default)
 
-### 2.2 Check Tasks File (for bidirectional linking)
+**This is the DEFAULT when no increment ID is provided!**
 
 ```bash
-TASKS_FILE="$INCREMENT_PATH/tasks.md"
-HAS_TASKS=false
-if [[ -f "$TASKS_FILE" ]]; then
-  HAS_TASKS=true
-  echo "✅ Found tasks.md - will create bidirectional links"
-else
-  echo "⚠️  No tasks.md - spec will sync without task links"
-fi
+# List ALL syncable increments (with spec.md)
+ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sort
 ```
 
-### 2.3 Read Metadata for External Links
+**Execute sync for EACH increment**:
 
-```bash
-METADATA_FILE="$INCREMENT_PATH/metadata.json"
-if [[ -f "$METADATA_FILE" ]]; then
-  echo "✅ Found metadata.json - will include external links"
-else
-  echo "⚠️  No metadata.json - no external tool links available"
-fi
 ```
+🔄 Syncing ALL increments to living docs...
 
----
-
-## STEP 3: Execute Spec Sync
-
-### 3.1 Run Sync Command
+Found {N} increments with spec.md files.
+```
 
-**Execute the sync using the CLI command**:
+**For each increment**, call the sync logic:
 
 ```typescript
-import { syncSpecs } from './dist/src/cli/commands/sync-specs.js';
-
-// Parse arguments
-const args = process.argv.slice(2); // e.g., ['0040', '--dry-run']
-
-// Execute sync
-await syncSpecs(args);
+import { LivingDocsSync } from './src/core/living-docs/living-docs-sync.js';
+
+const sync = new LivingDocsSync(projectRoot);
+
+// Get all increment folders
+const incrementsDir = '.specweave/increments';
+const entries = fs.readdirSync(incrementsDir);
+const increments = entries.filter(e => /^\d{4}E?-/.test(e));
+
+let successCount = 0;
+let failCount = 0;
+const results = [];
+
+for (const incrementId of increments.sort()) {
+  // Check if spec.md exists
+  const specPath = path.join(incrementsDir, incrementId, 'spec.md');
+  if (!fs.existsSync(specPath)) {
+    console.log(`   ⚠️  Skipping ${incrementId} (no spec.md)`);
+    continue;
+  }
+
+  try {
+    const result = await sync.syncIncrement(incrementId, { dryRun, force });
+    if (result.success) {
+      successCount++;
+      results.push({ id: incrementId, featureId: result.featureId, status: '✅' });
+    } else {
+      failCount++;
+      results.push({ id: incrementId, featureId: '', status: '❌', error: result.errors[0] });
+    }
+  } catch (error) {
+    failCount++;
+    results.push({ id: incrementId, featureId: '', status: '❌', error: error.message });
+  }
+}
 ```
 
-**This will**:
-1. **Derive feature ID from increment number** (e.g., 0040 → FS-040, 0002 → FS-002)
-2. **Read project/board from spec.md YAML frontmatter** (v0.31.0+ REQUIRED):
-   - For 1-level: `project:` field REQUIRED
-   - For 2-level: `project:` AND `board:` fields REQUIRED
-   - See [ADR-0190](/internal/architecture/adr/0190-spec-project-board-requirement.md)
-3. **Smart project matching fallback** (only if YAML fields missing - deprecated):
-   - `**Project**:` field in spec.md body (legacy)
-   - `multiProject.activeProject` in config.json
-   - ADO area path / JIRA board mapping
-   - Git remote (repo name)
-   - **ASK USER if unsure** (multi-project mode)
-4. Parse spec.md for user stories and acceptance criteria
-5. Create living docs structure:
-   - 1-level: `.specweave/docs/internal/specs/{project}/FS-XXX/`
-   - 2-level: `.specweave/docs/internal/specs/{project}/{board}/FS-XXX/`
-
-**CRITICAL**: Feature ID is DERIVED from increment number (ADR-0187)
-- Increment 0002-user-authentication → FS-002
-- Increment 0040-some-feature → FS-040
-- NO date-based patterns like FS-YY-MM-DD-name
-
-### 3.2 Project/Board Validation (v0.31.0+)
-
-**Structure Level Detection** (from `src/utils/structure-level-detector.ts`):
-- Detects 1-level vs 2-level from config (ADO, JIRA, umbrella, multiProject, folders)
-- Validates spec.md has required fields based on structure level
-- For 2-level: **ERROR if project OR board missing** (cannot sync)
-- For 1-level: **WARNING if project missing** (uses fallback, deprecated)
-
-**Expected spec.md frontmatter**:
-
-```yaml
-# 1-level structure
----
-increment: 0001-feature-name
-project: my-project          # REQUIRED for 1-level
----
-
-# 2-level structure
----
-increment: 0001-feature-name
-project: acme-corp           # REQUIRED for 2-level
-board: clinical-insights     # REQUIRED for 2-level
----
-```
-
-**Migration**: See [Migration Guide](/public/guides/migration-v031-project-fields.md)
-
----
-
-## STEP 4: Report Distribution Results
-
-### 4.1 Show What Was Created
+**Output summary table**:
 
 ```
 ═══════════════════════════════════════════════════════
-✅ SPECS-ONLY SYNC COMPLETE
+✅ BULK SYNC COMPLETE
 ═══════════════════════════════════════════════════════
 
-Increment: {increment_id}
-Title: {title from spec.md}
+| Increment | Feature ID | Status |
+|-----------|------------|--------|
+| 0093-ado-permission-profile-fixes | FS-093 | ✅ |
+| 0094-unit-test-alignment | FS-094 | ✅ |
+| 0095-per-project-epic-hierarchy | FS-095 | ✅ |
+| ... | ... | ... |
 
 ───────────────────────────────────────────────────────
-📊 UNIVERSAL HIERARCHY CREATED
+📊 SUMMARY
 ───────────────────────────────────────────────────────
 
-📁 Epic (Optional):
-   {if created}
-   Path: .specweave/docs/internal/specs/_epics/{EPIC-ID}/EPIC.md
-   Status: Created/Updated
-
-📁 Feature (Required):
-   Path: .specweave/docs/internal/specs/_features/{FS-ID}/FEATURE.md
-   Status: Created/Updated
-   Projects: {list of projects}
-
-📁 Project Contexts:
-   {for each project}
-   • {project}: .specweave/docs/internal/specs/{project}/{FS-ID}/README.md
-
-📝 User Stories:
-   {for each project}
-   {project}:
-   {for each story}
-   • {story-id}: {story-title}
-     Path: .specweave/docs/internal/specs/{project}/{FS-ID}/{us-id}.md
+Total increments: {N}
+✅ Succeeded: {successCount}
+❌ Failed: {failCount}
+⏭️  Skipped: {skippedCount} (no spec.md)
 
-───────────────────────────────────────────────────────
-🔗 BIDIRECTIONAL LINKING
-───────────────────────────────────────────────────────
+═══════════════════════════════════════════════════════
+```
 
-{if tasks.md exists}
-✅ Task → User Story Links:
-   Updated tasks.md with user story references
-   Each task now links to its parent user story
+### MODE B: Sync SINGLE Increment
 
-✅ User Story → Task Links:
-   Each user story shows implementing tasks
-   Tasks linked back to increment #{increment_id}
-{else}
-⚠️  No tasks.md found - stories created without task links
-{/if}
+**Only when a specific increment ID is provided**:
 
-───────────────────────────────────────────────────────
-📂 FILE STRUCTURE (v5.0.0+)
-───────────────────────────────────────────────────────
+```
+🎯 Target increment: {increment_id}
+📁 Increment path: .specweave/increments/{increment_id}
+🔄 Mode: Single increment sync
+```
 
-**NO _features folder** - Features live directly in project folders!
-
-**Project folder detection** (priority order):
-1. `**Project**:` field in spec.md (explicit)
-2. `multiProject.activeProject` in config.json
-3. ADO area path mapping / JIRA board mapping
-4. Git remote (repo name)
-5. **ASK USER if multi-project mode and unsure**
-
-.specweave/docs/internal/specs/
-├── {project}/                  ← Features + stories together
-│   └── FS-XXX/                 ← Feature ID derived from increment (0002 → FS-002)
-│       ├── FEATURE.md          ← Feature overview
-│       ├── us-001-{title}.md   ← User story 1
-│       ├── us-002-{title}.md   ← User story 2
-│       └── ...
-├── _epics/                     ← Optional (SAFe/large orgs only)
-│   └── EP-XXX/
-│       └── EPIC.md
-└── _archive/                   ← Archived features
-    └── {project}/FS-XXX/
+**Execute single sync**:
 
-───────────────────────────────────────────────────────
-🎯 WHAT THIS SYNC DID
-───────────────────────────────────────────────────────
+```typescript
+const result = await sync.syncIncrement(incrementId, { dryRun, force });
+```
 
-✅ Parsed increment spec.md
-✅ Derived Feature ID from increment number (e.g., 0002 → FS-002)
-✅ Detected project folder (or asked user if unsure)
-✅ Generated hierarchical structure in {project}/FS-XXX/
-✅ Created bidirectional links (if tasks.md exists)
-✅ Preserved external tool links (GitHub/Jira/ADO)
+**Output**:
+```
+═══════════════════════════════════════════════════════
+✅ SINGLE INCREMENT SYNC COMPLETE
+═══════════════════════════════════════════════════════
 
-❌ DID NOT UPDATE:
-   • Architecture decisions (ADRs)
-   • Operations docs (runbooks, deployment)
-   • Delivery docs (CI/CD, testing)
-   • Governance docs (security, compliance)
-   • Strategy docs (PRDs, roadmaps)
+Increment: {increment_id}
+Feature ID: FS-{XXX} (derived from increment number)
+Project: {project}
 
-This command ONLY syncs specs folder content!
+Files created:
+  • {project}/FS-{XXX}/FEATURE.md
+  • {project}/FS-{XXX}/us-001-*.md
+  • {project}/FS-{XXX}/us-002-*.md
+  ...
 
 ═══════════════════════════════════════════════════════
 ```
 
 ---
 
-## STEP 5: Next Steps Guidance
+## STEP 3: Identify Missing/New Specs
 
-```
-🎯 NEXT STEPS
-───────────────────────────────────────────────────────
-
-1. Review generated specs:
-   cd .specweave/docs/internal/specs/
-   ls -la {project}/{FS-ID}/
-
-2. Verify bidirectional links (if applicable):
-   • Check tasks.md has "User Story:" links
-   • Check user stories have "Implementation:" sections
-
-3. Sync to external tools (if configured):
-   {if GitHub configured}
-   • GitHub: /specweave-github:sync-spec
-   {/if}
-   {if Jira configured}
-   • Jira: /specweave-jira:sync-spec
-   {/if}
-   {if ADO configured}
-   • Azure DevOps: /specweave-ado:sync-spec
-   {/if}
-
-4. Update other docs (if needed):
-   • Full sync: /specweave:sync-docs
-   • Architecture only: Update ADRs manually
-   • Operations only: Update runbooks manually
-
-5. Commit changes:
-   git add .specweave/docs/internal/specs/
-   git commit -m "docs: sync specs from increment {increment_id}"
-```
+After sync, compare increments vs specs:
 
----
+```bash
+# Get all increment numbers
+INCREMENT_NUMS=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}E?-' | sed 's/^\([0-9]*E\?\).*/\1/')
 
-## ERROR HANDLING
+# Get all FS-XXX folders in specs
+SPEC_NUMS=$(ls -1 .specweave/docs/internal/specs/*/FS-* 2>/dev/null | grep -oE 'FS-[0-9]+E?' | sed 's/FS-//')
 
-### Error: Increment Not Found
+# Find missing (increments without corresponding FS-XXX)
+echo "Checking for gaps..."
 ```
-❌ Error: Increment '{increment_id}' not found
 
-Available increments:
-  {list .specweave/increments/*/}
-
-Usage: /specweave:sync-specs [increment_id] [--dry-run]
-```
+**Report gaps** (increments without corresponding specs):
 
-### Error: No Spec File
 ```
-❌ Error: No spec.md in increment '{increment_id}'
+📊 GAP ANALYSIS
+───────────────────────────────────────────────────────
 
-The increment must have a spec.md file to sync specs.
-Check: .specweave/increments/{increment_id}/spec.md
+{if gaps found}
+⚠️  Found {N} increments without corresponding specs:
+   • 0106-ci-health-improvements → FS-106 missing
+   • 0113-enhanced-living-docs-architecture → FS-113 missing
 
-Cannot proceed with specs sync.
+These were synced in this run.
+{else}
+✅ All increments have corresponding spec folders!
+{/if}
 ```
 
-### Error: Distribution Failed
-```
-❌ Error: Failed to distribute specs
+---
 
-Reason: {error message}
+## STEP 4: Feature ID Derivation Rules
 
-Common causes:
-  • Invalid spec.md format
-  • Missing user stories
-  • Corrupted YAML frontmatter
+**CRITICAL**: Feature ID is ALWAYS derived from increment number:
 
-Try: /specweave:validate {increment_id}
-```
+| Increment ID | Feature ID |
+|--------------|------------|
+| 0002-user-authentication | FS-002 |
+| 0040-some-feature | FS-040 |
+| 0106-ci-health | FS-106 |
+| 0111E-dora-metrics-fix | FS-111E |
+
+**Rules**:
+- Increment `XXXX-name` → Feature `FS-XXX` (3-digit minimum)
+- Increment `XXXXE-name` (external) → Feature `FS-XXXE`
+- NO date-based patterns (FS-YY-MM-DD-name is WRONG)
+- See ADR-0187 for rationale
 
 ---
 
 ## OPTIONS
 
 ### --dry-run
-Show what would be synced without making changes:
+Preview what would be synced without making changes:
 
 ```bash
-/specweave:sync-specs 0031 --dry-run
-```
-
-Output:
-```
-🔍 DRY RUN MODE - No files will be modified
-
-Would create/update:
-  • Feature: specweave/FS-031/FEATURE.md
-  • User story: specweave/FS-031/us-001-api-sync.md
-  • User story: specweave/FS-031/us-002-status-mapping.md
-  • Tasks.md: Would add 5 user story links
-
-Total: 4 files would be affected
-
-Note: Feature ID FS-031 derived from increment number 0031
+/specweave:sync-specs --dry-run        # Preview ALL
+/specweave:sync-specs 0106 --dry-run   # Preview single
 ```
 
 ### --force
 Overwrite existing files without prompting:
 
 ```bash
-/specweave:sync-specs 0031 --force
+/specweave:sync-specs --force          # Force ALL
+/specweave:sync-specs 0106 --force     # Force single
 ```
 
 ---
 
 ## EXAMPLES
 
-### Example 1: Sync Current Increment
+### Example 1: Sync ALL (Default - Most Common)
 ```
 User: /specweave:sync-specs
 
 Output:
-🎯 Target increment: 0031-external-tool-status-sync
-📁 Increment path: .specweave/increments/0031-external-tool-status-sync
-🔄 Mode: Specs-only sync
-
-Processing...
-✅ Distribution successful!
-   📊 Total stories: 7
-   📁 Total files created: 10
-   🎯 Feature ID: FS-031 (derived from increment 0031)
-   📁 Project folder: specweave/FS-031/
+🔄 Syncing ALL increments to living docs...
+
+Found 25 increments with spec.md files.
+
+| Increment | Feature ID | Status |
+|-----------|------------|--------|
+| 0093-ado-permission-profile-fixes | FS-093 | ✅ |
+| 0094-unit-test-alignment | FS-094 | ✅ |
+| 0095-per-project-epic-hierarchy | FS-095 | ✅ |
+| 0096-ado-import-fixes | FS-096 | ✅ |
+| 0097-umbrella-module-detection | FS-097 | ✅ |
+| ... | ... | ... |
+| 0116-livingspec-universal-standard | FS-116 | ✅ |
+
+📊 SUMMARY: 25 succeeded, 0 failed
 ```
 
-### Example 2: Sync Specific Increment
+### Example 2: Sync Single Increment
 ```
-User: /specweave:sync-specs 0025
+User: /specweave:sync-specs 0106
 
 Output:
-🎯 Target increment: 0025-per-project-resource-config
-📁 Increment path: .specweave/increments/0025-per-project-resource-config
-🔄 Mode: Specs-only sync (Universal Hierarchy)
-
-Processing...
-✅ Distribution successful!
-   📊 Total stories: 3
-   📁 Total files created: 5
+🎯 Target increment: 0106-ci-health-improvements
+📁 Increment path: .specweave/increments/0106-ci-health-improvements
+🔄 Mode: Single increment sync
+
+✅ Synced 0106-ci-health-improvements → FS-106
+   Created: specweave/FS-106/FEATURE.md
+   Created: specweave/FS-106/us-001-*.md
 ```
 
-### Example 3: Dry Run
+### Example 3: Dry Run ALL
 ```
-User: /specweave:sync-specs 0031 --dry-run
+User: /specweave:sync-specs --dry-run
 
 Output:
 🔍 DRY RUN MODE - No files will be modified
 
-Would sync increment: 0031-external-tool-status-sync
-Would create feature: FS-031 (derived from increment 0031)
-Would use project folder: specweave/FS-031/
-Would create 7 user stories
-Would update tasks.md with bidirectional links
+Would sync 25 increments:
+  • 0093 → FS-093 (exists, would update)
+  • 0094 → FS-094 (exists, would update)
+  • 0106 → FS-106 (NEW - would create)
+  • 0113 → FS-113 (NEW - would create)
+  ...
 
 No changes made (dry run mode)
 ```
 
 ---
 
+## ERROR HANDLING
+
+### Error: No Increments Found
+```
+❌ Error: No increments found in .specweave/increments/
+
+Create an increment first:
+  /specweave:increment "feature name"
+```
+
+### Error: Specific Increment Not Found
+```
+❌ Error: Increment '0999' not found
+
+Available increments:
+  0093-ado-permission-profile-fixes
+  0094-unit-test-alignment
+  ...
+
+Usage: /specweave:sync-specs [increment_id]
+```
+
+### Error: Missing spec.md
+```
+⚠️  Skipping 0107-incomplete-feature (no spec.md)
+
+Increment must have a spec.md file to sync.
+```
+
+---
+
 ## IMPORTANT NOTES
 
-1. **Specs-only**: This command ONLY updates `.specweave/docs/internal/specs/` folder
-2. **Universal Hierarchy**: Uses Epic → Feature → User Story → Task structure
-3. **Bidirectional Links**: Automatically creates if tasks.md exists
-4. **Project-aware**: Distributes stories to correct project folders
-5. **Non-destructive**: Creates backups before overwriting (unless --force)
-6. **External Links**: Preserves GitHub/Jira/ADO links from metadata.json
+1. **DEFAULT = ALL**: Running without arguments syncs ALL increments
+2. **Idempotent**: Safe to run multiple times (updates existing, creates missing)
+3. **Feature ID derivation**: Always from increment number (not stored in metadata)
+4. **Project detection**: Reads `project:` from spec.md YAML frontmatter
+5. **External sync**: Triggers GitHub/JIRA/ADO sync if configured
 
 ---
 
 ## WHEN TO USE THIS COMMAND
 
-✅ **Use `/specweave:sync-specs` when**:
-- You only want to update user stories and features
-- You've made changes to spec.md and want them in living docs
-- You want to preserve existing architecture/operations docs
-- You need quick spec sync without full documentation update
+✅ **Use `/specweave:sync-specs` (no args) when**:
+- You want to ensure ALL increments are in living docs
+- After creating multiple increments
+- To fix gaps in specs folder
+- Regular maintenance sync
 
-❌ **Use `/specweave:sync-docs` instead when**:
-- You want to update ALL documentation areas
-- You have new architecture decisions (ADRs)
-- You updated operations/deployment docs
-- You need comprehensive documentation sync
+✅ **Use `/specweave:sync-specs <id>` when**:
+- You only want to sync one specific increment
+- After updating a single spec.md
+- Debugging sync issues for one increment
 
 ---
 
-**You are now ready to execute this specs-only sync command. Follow the steps above precisely.**
+**Execute this command now. Default = sync ALL increments.**