specweave 1.0.49 → 1.0.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.49",
+  "version": "1.0.50",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

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

@@ -47,18 +47,36 @@ if [ -z "$INCREMENT_ID" ]; then
 fi
 ```
 
-**Validate increment exists**:
+**Validate increment exists** (check active AND archive directories):
 
 ```bash
 INCREMENT_DIR=".specweave/increments/$INCREMENT_ID"
+INCREMENT_STATUS="active"
+
 if [ ! -d "$INCREMENT_DIR" ]; then
-  echo "❌ Increment $INCREMENT_ID not found at $INCREMENT_DIR"
-  exit 1
+  # Check archive directory for completed increments
+  ARCHIVE_DIR=".specweave/increments/_archive/$INCREMENT_ID"
+  if [ -d "$ARCHIVE_DIR" ]; then
+    INCREMENT_DIR="$ARCHIVE_DIR"
+    INCREMENT_STATUS="completed"
+    echo "📦 Found ARCHIVED increment: $INCREMENT_ID (status: completed)"
+  else
+    echo "❌ Increment $INCREMENT_ID not found in active or archive"
+    exit 1
+  fi
+else
+  echo "✅ Found increment: $INCREMENT_ID"
 fi
-
-echo "✅ Found increment: $INCREMENT_ID"
 ```
 
+### ⚠️ IMPORTANT: DO NOT SKIP SYNC FOR COMPLETED/ARCHIVED INCREMENTS
+
+**Even if INCREMENT_STATUS="completed", you MUST proceed with ALL sync steps:**
+- ✅ Still create missing GitHub issues (critical for historical tracking)
+- ✅ Still sync to living docs
+- ✅ Still close issues if they were just created
+- ❌ DO NOT print "no sync needed" for completed increments
+
 **Output**:
 ```
 🔍 Auto-detected active increment: 0053-safe-feature-deletion
@@ -67,6 +85,12 @@ echo "✅ Found increment: $INCREMENT_ID"
 📊 Starting comprehensive progress sync...
 ```
 
+**OR for archived/completed**:
+```
+📦 Found ARCHIVED increment: 0001-content-repurposer-mvp (status: completed)
+📊 Syncing COMPLETED increment (will create/close GitHub issues)...
+```
+
 ---
 
 ## STEP 2: Sync Tasks → Living Docs (ACs and User Stories)
@@ -96,29 +120,42 @@ fi
 - Updates spec.md to mark ACs as complete: `- [ ]` → `- [x]`
 - Updates metadata.json with AC completion count
 
-### 2.2: Sync to Living Docs (User Stories)
+### 2.2: Sync to Living Docs (User Stories) - MANDATORY BEFORE EXTERNAL SYNC
+
+### ⚠️ CRITICAL: THIS STEP IS MANDATORY AND MUST COMPLETE BEFORE ANY EXTERNAL TOOL OPERATIONS
+
+**Why?** External tools (GitHub, JIRA, ADO) sync FROM living docs. If you skip this step:
+- External issues will have stale/outdated content
+- User stories won't reflect completed status
+- AC checkboxes in GitHub issues won't be checked
 
-Call the existing `/sw:sync-specs` command:
+**You MUST invoke the `/sw:sync-specs` command:**
 
 ```bash
 echo "📚 Step 2/5: Syncing increment to living docs..."
+echo "   ⚠️  THIS MUST COMPLETE BEFORE EXTERNAL TOOL SYNC"
 
-# Sync increment specs to living docs structure
+# MANDATORY: Sync increment specs to living docs structure
+# This populates .specweave/docs/internal/specs/{project}/FS-XXX/
 npx specweave sync-specs "$INCREMENT_ID"
 
 if [ $? -eq 0 ]; then
   echo "   ✅ Living docs sync complete"
+  echo "   📁 Updated: .specweave/docs/internal/specs/{project}/FS-XXX/"
 else
-  echo "   ❌ Living docs sync failed"
+  echo "   ❌ Living docs sync failed - BLOCKING external sync"
   exit 1
 fi
 ```
 
 **What this does**:
-- Syncs spec.md → living docs user stories
+- Syncs spec.md → living docs user stories in `.specweave/docs/internal/specs/`
 - Updates user story completion status
 - Generates/updates feature ID if needed
 - Updates README.md in feature folder
+- **Creates the content that external tools will sync FROM**
+
+### ⛔ DO NOT PROCEED TO STEP 3 UNTIL THIS COMPLETES SUCCESSFULLY
 
 ---
 
@@ -194,6 +231,15 @@ fi
 
 **Philosophy**: `/sw:sync-progress` is the "single button" - it should JUST WORK. If GitHub is configured and no issue exists, CREATE IT.
 
+### ⚠️ CRITICAL RULE: DO NOT SKIP FOR COMPLETED INCREMENTS
+
+**You MUST create GitHub issues even for COMPLETED increments!**
+
+- ❌ WRONG: "Increment already completed - no sync needed" → SKIP creation
+- ✅ CORRECT: Create issues regardless of status, then sync/close them
+
+**Why?** Users need GitHub issues for historical tracking, team visibility, and compliance. A completed increment without a GitHub issue is an incomplete record.
+
 **Check and auto-create**:
 
 ```bash
@@ -389,6 +435,13 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " github " ]] && [ "$NO_GITHUB" != "true" ]; t
       else
         echo "      ⚠️  GitHub sync had warnings (check logs)"
       fi
+
+      # SPECIAL CASE: For completed/archived increments, also CLOSE the issue
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      🔒 Closing GitHub issue (increment is completed)..."
+        /sw-github:close "$INCREMENT_ID"
+        echo "      ✅ GitHub issue closed"
+      fi
     fi
   fi
 fi
@@ -401,6 +454,11 @@ fi
 - Updates labels based on status
 - Pulls external changes (comments, status changes from team)
 
+**SPECIAL CASE: Completed/Archived Increments**:
+- If `INCREMENT_STATUS="completed"` and issue was just created → ALSO close the issue
+- Use `/sw-github:close $INCREMENT_ID` to close with completion comment
+- This provides complete historical tracking
+
 ### 5.2: Sync to JIRA (if configured)
 
 ```bash
@@ -540,7 +598,7 @@ echo "   • Run /sw:done $INCREMENT_ID when ready to close"
 echo ""
 ```
 
-**Example Output**:
+**Example Output (Active Increment)**:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -565,6 +623,34 @@ Next steps:
    • Run /sw:done 0053 when ready to close
 ```
 
+**Example Output (COMPLETED/Archived Increment)**:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅ PROGRESS SYNC COMPLETE (ARCHIVED INCREMENT)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Increment: 0001-content-repurposer-mvp
+📊 Status: completed (archived)
+
+✅ Synced:
+   • Tasks → ACs (spec.md)          54/54 ACs ✓
+   • Spec → Living docs             10/10 user stories ✓
+   • Status line cache              100% complete ✓
+
+🔗 External Tools:
+   • GitHub issue AUTO-CREATED: #123
+   • GitHub issue CLOSED: #123 (increment complete)
+
+📊 Completion:
+   • Tasks: 35/35 (100%)
+   • ACs: 54/54 (100%)
+   • User Stories: 10/10 (100%)
+
+ℹ️  Archived increment synced successfully!
+   GitHub issues created and closed for historical tracking.
+```
+
 ---
 
 ## STEP 7: Dry-Run Mode (If --dry-run flag)

package/plugins/specweave/skills/progress-sync/SKILL.md

@@ -24,6 +24,13 @@ tasks.md → spec.md ACs → living docs → AUTO-CREATE external issues → syn
 
 **No more "No GitHub issue linked" errors!** The command auto-creates missing issues.
 
+### ⚠️ CRITICAL: Works on COMPLETED/ARCHIVED Increments Too!
+
+**This command MUST create and sync GitHub issues even for completed increments:**
+- Creates issues for historical tracking
+- Closes issues immediately after creation (since increment is complete)
+- Never skips with "no sync needed" for completed increments
+
 ---
 
 ## When to Use This Command

package/plugins/specweave-github/commands/close.md

@@ -7,6 +7,29 @@ description: Close GitHub issue for completed SpecWeave increment. Posts complet
 
 Close the GitHub issue associated with a completed SpecWeave increment.
 
+## ⛔ MANDATORY: Sync Living Docs BEFORE Closing
+
+**GitHub issue content is generated FROM living docs.** If living docs are stale, the closing summary will have outdated information.
+
+**You MUST run `/sw:sync-specs` BEFORE closing (unless using /sw:sync-progress):**
+
+```bash
+# STEP 1: Ensure living docs reflect final state
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then close GitHub issue
+/sw-github:close <increment-id>
+```
+
+**Why?**
+- Closing comment includes final stats from living docs
+- User story completion status read from living docs
+- AC checkboxes reflect living docs state
+
+**Note:** `/sw:done` and `/sw:sync-progress` call sync-specs automatically.
+
+---
+
 **Usage**: `/sw-github:close <increment-id>`
 
 ```bash

package/plugins/specweave-github/commands/create.md

@@ -7,6 +7,30 @@ description: Create a GitHub issue for a SpecWeave increment. Generates issue fr
 
 Create a GitHub issue for the specified SpecWeave increment.
 
+## ⛔ MANDATORY: Sync Living Docs BEFORE Creating Issue
+
+**GitHub issue content is generated FROM living docs.** If living docs don't exist or are stale, the issue will be incomplete.
+
+**You MUST run `/sw:sync-specs` BEFORE creating (unless using /sw:sync-progress):**
+
+```bash
+# STEP 1: Ensure living docs exist and are current
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then create GitHub issue
+/sw-github:create <increment-id>
+```
+
+**Why?**
+- Issue body is generated from `.specweave/docs/internal/specs/FS-XXX/`
+- User stories and ACs come from living docs
+- Task checklist reflects living docs structure
+- Without sync-specs, issue will be created from raw increment spec.md (less structured)
+
+**Note:** `/sw:sync-progress` calls sync-specs automatically before creating issues.
+
+---
+
 **Usage**: `/sw-github:create <increment-id>`
 
 ```bash

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

@@ -5,9 +5,30 @@ description: Synchronize SpecWeave increment with GitHub issue (Multi-Project Su
 
 # Sync Increment with GitHub Issue (Multi-Project)
 
-## ⚠️ CRITICAL: Sync Routing (Read First!)
+## ⚠️ CRITICAL: Pre-Sync Requirements (Read First!)
 
-**Before executing ANY sync, you MUST determine the correct sync path:**
+### ⛔ MANDATORY: Sync Living Docs BEFORE GitHub Sync
+
+**GitHub sync reads FROM living docs.** If living docs are stale, GitHub issues will have outdated content.
+
+**You MUST run `/sw:sync-specs` (or ensure it ran) BEFORE this command:**
+
+```bash
+# STEP 1: Ensure living docs are current (MANDATORY)
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then sync to GitHub
+/sw-github:sync <increment-id>
+```
+
+**Why?**
+- GitHub issues are generated FROM `.specweave/docs/internal/specs/FS-XXX/`
+- If you skip sync-specs, GitHub will show stale user stories/ACs
+- `/sw:sync-progress` calls sync-specs automatically, but `/sw-github:sync` does NOT
+
+**If you're calling this directly (not via /sw:sync-progress), run sync-specs first!**
+
+---
 
 ### Step 0: Detect Project Structure