specweave 1.0.44 → 1.0.46

package/CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- SW:META template="claude" version="1.0.41" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
+<!-- SW:META template="claude" version="1.0.44" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
 
-<!-- SW:SECTION:header version="1.0.41" -->
+<!-- SW:SECTION:header version="1.0.44" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
-<!-- SW:SECTION:start version="1.0.41" -->
+<!-- SW:SECTION:start version="1.0.44" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -14,7 +14,7 @@
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.41" -->
+<!-- SW:SECTION:autodetect version="1.0.44" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -24,7 +24,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.41" -->
+<!-- SW:SECTION:metarule version="1.0.44" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -35,7 +35,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.41" -->
+<!-- SW:SECTION:rules version="1.0.44" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
@@ -45,7 +45,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.41" -->
+<!-- SW:SECTION:workflow version="1.0.44" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -62,7 +62,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
 <!-- SW:END:workflow -->
 
-<!-- SW:SECTION:structure version="1.0.41" -->
+<!-- SW:SECTION:structure version="1.0.44" -->
 ## Structure
 
 ```
@@ -84,7 +84,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Path syntax**: `//path` = absolute | `/path` = relative to settings file | `**` = recursive | `additionalDirectories` = explicit working dirs
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.41" -->
+<!-- SW:SECTION:taskformat version="1.0.44" -->
 ## Task Format
 
 ```markdown
@@ -94,7 +94,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.41" -->
+<!-- SW:SECTION:secrets version="1.0.44" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -105,7 +105,7 @@ gh auth status
 ```
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.41" -->
+<!-- SW:SECTION:syncing version="1.0.44" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **After increment creation**: Run `/sw-github:sync {id}` to create issues!
@@ -124,7 +124,7 @@ Living docs sync ≠ External sync. They are separate:
 **Verify tokens**: `grep GITHUB_TOKEN .env` | `gh auth status`
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:mapping version="1.0.41" -->
+<!-- SW:SECTION:mapping version="1.0.44" -->
 ## GitHub Mapping
 
 | SpecWeave | GitHub |
@@ -134,7 +134,7 @@ Living docs sync ≠ External sync. They are separate:
 | Task T-XXX | Checkbox |
 <!-- SW:END:mapping -->
 
-<!-- SW:SECTION:testing version="1.0.41" -->
+<!-- SW:SECTION:testing version="1.0.44" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -146,13 +146,13 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:limits version="1.0.41" -->
+<!-- SW:SECTION:limits version="1.0.44" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.41" -->
+<!-- SW:SECTION:troubleshooting version="1.0.44" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -170,7 +170,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 | Path patterns not working | `//path` = absolute, `/path` = relative to settings file, `additionalDirectories` for explicit working dirs |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:principles version="1.0.41" -->
+<!-- SW:SECTION:principles version="1.0.44" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -180,7 +180,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 5. **Clean**: All files in increment folders
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.41" -->
+<!-- SW:SECTION:linking version="1.0.44" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -188,7 +188,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:docs version="1.0.41" -->
+<!-- SW:SECTION:docs version="1.0.44" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "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/hooks/v2/handlers/github-sync-handler.sh

@@ -1,24 +1,38 @@
 #!/bin/bash
-# github-sync-handler.sh - Sync increment to GitHub (create issues for User Stories)
+# github-sync-handler.sh - Sync increment to GitHub (create/update issues for User Stories)
 # Called async by processor, non-blocking, error-tolerant
 #
 # Argument formats supported:
 # 1. (event_type, increment_id) - from lifecycle/spec.updated events
-# 2. (increment_id) - from metadata.changed events (legacy)
+# 2. (event_type, INC_ID:US_ID) - from user-story.completed/reopened events (v1.0.45+)
+# 3. (increment_id) - from metadata.changed events (legacy)
+#
+# CRITICAL FIX (v1.0.45): Added user-story.completed/reopened support
+# Root cause: GitHub issues were created but NEVER UPDATED when User Stories completed!
 #
 # IMPORTANT: Never crash Claude, always exit 0
 set +e
 
 [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
 
-# Support both argument formats:
-# - Called from increment.created/spec.updated: $1 = event_type, $2 = increment_id
-# - Called from metadata.changed: $1 = increment_id
-INC_ID="${1:-}"
-if [[ "$INC_ID" == increment.* ]] || [[ "$INC_ID" == spec.* ]] || [[ "$INC_ID" == metadata.* ]]; then
-  # First arg is event type, second is increment ID
-  INC_ID="${2:-}"
+# Parse arguments - support multiple formats
+EVENT_TYPE="${1:-}"
+EVENT_DATA="${2:-}"
+INC_ID=""
+US_ID=""
+
+if [[ "$EVENT_TYPE" == user-story.* ]]; then
+  # user-story.completed/reopened: $2 = INC_ID:US_ID
+  INC_ID="${EVENT_DATA%%:*}"
+  US_ID="${EVENT_DATA##*:}"
+elif [[ "$EVENT_TYPE" == increment.* ]] || [[ "$EVENT_TYPE" == spec.* ]] || [[ "$EVENT_TYPE" == metadata.* ]]; then
+  # Lifecycle events: $2 = increment_id
+  INC_ID="$EVENT_DATA"
+else
+  # Legacy format: $1 = increment_id directly
+  INC_ID="$EVENT_TYPE"
 fi
+
 [[ -z "$INC_ID" ]] && exit 0
 
 # Find project root
@@ -35,12 +49,24 @@ CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
 GITHUB_ENABLED=$(grep -o '"enabled"[[:space:]]*:[[:space:]]*true' "$CONFIG_FILE" | head -1)
 [[ -z "$GITHUB_ENABLED" ]] && exit 0
 
-# Throttle: max once per 5 minutes per increment
-THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID"
+# Throttle configuration:
+# - Full sync (increment lifecycle): 5 minutes (creates all issues)
+# - US completion sync: 60 seconds (more targeted, less aggressive)
 THROTTLE_LOG="$PROJECT_ROOT/.specweave/logs/throttle.log"
-THROTTLE_WINDOW=300  # 5 minutes
 mkdir -p "$(dirname "$THROTTLE_LOG")" 2>/dev/null
 
+if [[ -n "$US_ID" ]]; then
+  # Per-US throttle (60 seconds) - more frequent for targeted updates
+  THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID-$US_ID"
+  THROTTLE_WINDOW=60
+  SYNC_TYPE="US:$US_ID"
+else
+  # Per-increment throttle (5 minutes) - less frequent for full sync
+  THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID"
+  THROTTLE_WINDOW=300
+  SYNC_TYPE="increment"
+fi
+
 if [[ -f "$THROTTLE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
@@ -49,12 +75,12 @@ if [[ -f "$THROTTLE_FILE" ]]; then
   fi
   if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
     REMAINING=$((THROTTLE_WINDOW - AGE))
-    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID (wait ${REMAINING}s, use /sw:sync-progress to bypass)" >> "$THROTTLE_LOG" 2>/dev/null
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID ($SYNC_TYPE, wait ${REMAINING}s)" >> "$THROTTLE_LOG" 2>/dev/null
     exit 0
   fi
 fi
 touch "$THROTTLE_FILE"
-echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] EXECUTING $INC_ID" >> "$THROTTLE_LOG" 2>/dev/null
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] EXECUTING $INC_ID ($SYNC_TYPE) event=$EVENT_TYPE" >> "$THROTTLE_LOG" 2>/dev/null
 
 # Cross-platform timeout wrapper
 run_with_timeout() {
@@ -90,6 +116,16 @@ FEATURE_ID=""
 [[ -z "$FEATURE_ID" ]] && exit 0
 
 # Run sync (timeout 60s)
+# The github-feature-sync-cli.js script will:
+# 1. Find all User Stories in the feature
+# 2. For each US, call updateUserStoryIssue() which:
+#    - Updates issue body with latest content
+#    - Calculates completion via CompletionCalculator (verifies [x] checkboxes)
+#    - CLOSES the issue if ALL ACs and tasks are verified complete
+#    - Updates status labels (status:complete, status:active, status:not_started)
 cd "$PROJECT_ROOT" || exit 0
-GITHUB_TOKEN="$GITHUB_TOKEN" run_with_timeout 60 node "$SYNC_SCRIPT" "$FEATURE_ID" >/dev/null 2>&1
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] Running: node $SYNC_SCRIPT $FEATURE_ID" >> "$THROTTLE_LOG" 2>/dev/null
+GITHUB_TOKEN="$GITHUB_TOKEN" run_with_timeout 60 node "$SYNC_SCRIPT" "$FEATURE_ID" >> "$THROTTLE_LOG" 2>&1
+SYNC_EXIT=$?
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] COMPLETED $INC_ID ($SYNC_TYPE) exit=$SYNC_EXIT" >> "$THROTTLE_LOG" 2>/dev/null
 exit 0

package/plugins/specweave/hooks/v2/queue/processor.sh

@@ -6,11 +6,15 @@
 #
 # Event routing (EDA v2):
 # - increment.created/done/archived/reopened -> living-specs-handler + status-line-handler + project-bridge-handler + github-sync-handler
-# - user-story.completed/reopened -> status-line-handler + project-bridge-handler
+# - user-story.completed/reopened -> status-line-handler + project-bridge-handler + github-sync-handler (v1.0.45+: CRITICAL FIX)
 # - spec.updated -> living-docs-handler + ac-validation-handler + github-sync-handler (creates GitHub issues for User Stories)
 # - task.updated -> living-docs-handler + ac-validation-handler (legacy)
 # - metadata.changed -> github-sync-handler
 #
+# CRITICAL FIX (v1.0.45): user-story.completed now triggers github-sync-handler!
+# Root cause: GitHub issues were CREATED but NEVER UPDATED when User Stories completed.
+# Result: Issues stayed OPEN forever even after all tasks/ACs were marked complete.
+#
 # The project-bridge-handler connects increment events to project-level EDA,
 # enabling automatic sync to GitHub, ADO, and JIRA via ProjectService.
 #
@@ -167,11 +171,15 @@ process_event() {
       run_handler "$HANDLER_DIR/github-sync-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       ;;
 
-    # User story events -> status-line-handler + project-bridge-handler
+    # User story events -> status-line-handler + project-bridge-handler + github-sync-handler
+    # CRITICAL FIX (v1.0.45): Added github-sync-handler to update GitHub issues when US completes
+    # Root cause: user-story.completed was NOT triggering GitHub sync → issues stayed open!
     user-story.completed|user-story.reopened)
       run_handler "$HANDLER_DIR/status-line-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       # Bridge to project-level EDA (may trigger issue updates)
       run_handler "$HANDLER_DIR/project-bridge-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
+      # Sync to GitHub (updates User Story issue status when US completes/reopens)
+      run_handler "$HANDLER_DIR/github-sync-handler.sh" "$EVENT_TYPE" "$EVENT_DATA"
       ;;
 
     # Spec updated -> sync to living docs + validate ACs + sync to GitHub