specweave 0.28.0 → 0.28.1

package/plugins/specweave/agents/qa-lead/AGENT.md

@@ -2,8 +2,8 @@
 name: qa-lead
 description: QA Lead that creates test suites ONE FILE AT A TIME to prevent crashes. Handles test plans, test cases, testing strategies, quality gates. **CRITICAL CHUNKING RULE - Large test suites (15 files) done incrementally.** Activates for: QA, quality assurance, testing, test strategy, test plan, test cases, unit tests, integration tests, E2E tests, end-to-end testing, Playwright, Jest, Mocha, Cypress, test automation, test coverage, regression, test-driven development, TDD, BDD, behavior-driven development, quality gates, acceptance criteria, test data, test scenarios, smoke tests, sanity tests, exploratory testing.
 tools: Read, Write, Edit, Bash
-model: claude-sonnet-4-5-20250929
-model_preference: haiku
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: execution
 fallback_behavior: flexible
 max_response_tokens: 2000

package/plugins/specweave/agents/security/AGENT.md

@@ -2,8 +2,8 @@
 name: security
 description: Security Engineer and application security expert. Performs threat modeling, security architecture review, penetration testing, vulnerability assessment, and security compliance. Handles OWASP Top 10, authentication security, authorization, encryption, secrets management, HTTPS/TLS, CORS, CSRF, XSS, SQL injection prevention, secure coding practices, security audits, and compliance (GDPR, HIPAA, PCI-DSS, SOC 2). Activates for: security, security review, threat model, vulnerability, penetration testing, pen test, OWASP, authentication security, authorization, encryption, secrets, HTTPS, TLS, SSL, CORS, CSRF, XSS, SQL injection, secure coding, security audit, compliance, GDPR, HIPAA, PCI-DSS, SOC 2, security architecture, secrets management, rate limiting, brute force protection, session security, token security, JWT security.
 tools: Read, Bash, Grep
-model: claude-sonnet-4-5-20250929
-model_preference: sonnet
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: planning
 fallback_behavior: strict
 max_response_tokens: 2000

package/plugins/specweave/agents/tdd-orchestrator/AGENT.md

@@ -1,8 +1,8 @@
 ---
 name: tdd-orchestrator
 description: Master TDD orchestrator specializing in red-green-refactor discipline, multi-agent workflow coordination, and comprehensive test-driven development practices. Enforces TDD best practices across teams with AI-assisted testing and modern frameworks. Use PROACTIVELY for TDD implementation and governance.
-model: claude-sonnet-4-5-20250929
-model_preference: haiku
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: execution
 fallback_behavior: flexible
 max_response_tokens: 2000

package/plugins/specweave/agents/tech-lead/AGENT.md

@@ -2,8 +2,8 @@
 name: tech-lead
 description: Technical Lead that implements code ONE FILE AT A TIME to prevent crashes. Handles code review, best practices, mentorship, implementation planning. **CRITICAL CHUNKING RULE - Large implementations (auth system = auth.ts + tests + middleware) done incrementally.** Activates for: tech lead, code review, best practices, refactoring, technical debt, code quality, design patterns, SOLID principles, clean code, code standards, implementation plan, technical guidance, mentorship, code optimization, complexity analysis, technical planning, estimation, implementation strategy, code architecture.
 tools: Read, Write, Edit, Bash
-model: claude-sonnet-4-5-20250929
-model_preference: haiku
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: execution
 fallback_behavior: flexible
 max_response_tokens: 2000

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -2,8 +2,8 @@
 name: test-aware-planner
 description: Test-Aware Planning agent that generates tasks.md **ONE USER STORY AT A TIME** with embedded test plans. **CRITICAL CHUNKING RULE - Prevents crashes.** Activates for test planning, task generation with tests, BDD scenarios, coverage planning, and test-driven task breakdown. Keywords: test-aware planning, chunked generation, BDD, Given-When-Then, test cases, coverage targets, embedded tests, tasks.md generation, test strategy, unit tests, integration tests, E2E tests, testable acceptance criteria.
 tools: Read, Write, Grep, Glob, Edit
-model: claude-sonnet-4-5-20250929
-model_preference: sonnet
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: planning
 fallback_behavior: strict
 max_response_tokens: 2000

package/plugins/specweave/hooks/post-increment-completion.sh

@@ -366,4 +366,88 @@ else
   echo ""
 fi
 
+# ============================================================================
+# GITHUB ISSUE CLOSURE (v0.28.1 - CRITICAL FIX)
+# ============================================================================
+# After creating/syncing GitHub issues, close User Story issues for this increment.
+# This was the MISSING feature causing issues to stay open indefinitely.
+#
+# WHY THIS IS SEPARATE FROM consolidated-sync.js:
+# - consolidated-sync.js handles task-level sync (called by post-task-completion too)
+# - sync-increment-closure.js ONLY runs on increment completion
+# - Closing issues is a DESTRUCTIVE operation that should only happen once
+#
+# GATE CHECK: All gates are checked inside sync-increment-closure.js
+# - canUpdateExternalItems must be true
+# - autoSyncOnCompletion must be true
+# - sync.github.enabled must be true
+#
+# See: Root cause analysis - User Story issues created but never closed
+
+if command -v node &> /dev/null; then
+  echo ""
+  echo "🔒 Closing GitHub issues for completed user stories..."
+
+  # ========================================================================
+  # LOCATE CLOSURE SYNC SCRIPT
+  # ========================================================================
+  # Find sync-increment-closure.js in order of preference:
+  # 1. In-place compiled (development, esbuild output)
+  # 2. Local dist (development, tsc output)
+  # 3. node_modules (installed as dependency) ← USER PROJECTS
+  # 4. Plugin marketplace (Claude Code global installation)
+
+  CLOSURE_SCRIPT=""
+  if [ -f "$PROJECT_ROOT/plugins/specweave/lib/hooks/sync-increment-closure.js" ]; then
+    # Development: Use in-place compiled hooks (esbuild, not tsc)
+    CLOSURE_SCRIPT="$PROJECT_ROOT/plugins/specweave/lib/hooks/sync-increment-closure.js"
+    echo "  🔧 Using in-place compiled hook (development mode)"
+  elif [ -f "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/sync-increment-closure.js" ]; then
+    # Development: Use project's compiled files (has node_modules)
+    CLOSURE_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/sync-increment-closure.js"
+    echo "  🔧 Using local dist (development mode)"
+  elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/sync-increment-closure.js" ]; then
+    # Installed as dependency: Use node_modules version (MOST USER PROJECTS)
+    CLOSURE_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/sync-increment-closure.js"
+    echo "  📦 Using node_modules version"
+  elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/sync-increment-closure.js" ]; then
+    # Fallback: Plugin marketplace (may fail if deps missing)
+    CLOSURE_SCRIPT="${CLAUDE_PLUGIN_ROOT}/lib/hooks/sync-increment-closure.js"
+    echo "  🌐 Using plugin marketplace version"
+  fi
+
+  # ========================================================================
+  # EXECUTE CLOSURE SYNC
+  # ========================================================================
+  # Run closure sync to close all User Story GitHub issues.
+  # Non-blocking: Errors logged but don't crash hook (increment already closed)
+
+  if [ -n "$CLOSURE_SCRIPT" ]; then
+    # Ensure GITHUB_TOKEN is available (may have been set earlier)
+    if [ -z "$GITHUB_TOKEN" ] && [ -f "$PROJECT_ROOT/.env" ]; then
+      GITHUB_TOKEN_FROM_ENV=$(grep -E '^GITHUB_TOKEN=' "$PROJECT_ROOT/.env" 2>/dev/null | head -1 | cut -d'=' -f2- | sed 's/^["'\'']//' | sed 's/["'\'']$//')
+      if [ -n "$GITHUB_TOKEN_FROM_ENV" ]; then
+        export GITHUB_TOKEN="$GITHUB_TOKEN_FROM_ENV"
+      fi
+    fi
+
+    # Run closure sync (synchronous - user sees immediate feedback)
+    if (cd "$PROJECT_ROOT" && node "$CLOSURE_SCRIPT" "$INCREMENT_ID") 2>&1; then
+      echo "  ✅ GitHub issue closure complete"
+      echo ""
+    else
+      echo "  ⚠️  Failed to close GitHub issues (non-blocking - you can close manually)" >&2
+      echo ""
+    fi
+  else
+    echo "  ⚠️  sync-increment-closure.js not found in any location - skipping issue closure" >&2
+    echo "  💡 User Story GitHub issues may remain open until manually closed" >&2
+    echo ""
+  fi
+else
+  echo ""
+  echo "  ⚠️  Node.js not found - skipping GitHub issue closure" >&2
+  echo ""
+fi
+
 exit 0

package/plugins/specweave/hooks/post-increment-planning.sh

@@ -896,8 +896,12 @@ EOF_MINIMAL
     local spec_md_path="$increment_dir/spec.md"
 
     if [ -f "$spec_md_path" ]; then
+      # Extract feature ID from multiple possible frontmatter fields:
+      # - epic: (preferred)
+      # - feature_id:
+      # - feature:
       FEATURE_ID=$(awk '
-        BEGIN { in_frontmatter=0 }
+        BEGIN { in_frontmatter=0; feature_id="" }
         /^---$/ {
           if (in_frontmatter == 0) {
             in_frontmatter=1; next
@@ -908,15 +912,32 @@ EOF_MINIMAL
         in_frontmatter == 1 && /^epic:/ {
           gsub(/^epic:[ \t]*/, "");
           gsub(/["'\'']/, "");
-          print;
-          exit
+          feature_id = $0;
         }
+        in_frontmatter == 1 && /^feature_id:/ {
+          gsub(/^feature_id:[ \t]*/, "");
+          gsub(/["'\'']/, "");
+          if (feature_id == "") feature_id = $0;
+        }
+        in_frontmatter == 1 && /^feature:/ {
+          gsub(/^feature:[ \t]*/, "");
+          gsub(/["'\'']/, "");
+          if (feature_id == "") feature_id = $0;
+        }
+        END { print feature_id }
       ' "$spec_md_path" | tr -d '\r\n')
 
       if [ -n "$FEATURE_ID" ]; then
         log_debug "  📎 Extracted feature ID: $FEATURE_ID"
       else
-        log_debug "  ⚠️  No epic field in spec.md, sync will auto-generate ID"
+        # AUTO-GENERATE feature ID from increment number (NEW - ADR-0139)
+        local increment_num=$(echo "$increment_id" | grep -oE '^[0-9]+')
+        if [ -n "$increment_num" ]; then
+          FEATURE_ID="FS-${increment_num}"
+          log_info "  📝 Auto-generated feature ID: $FEATURE_ID (no epic/feature_id in spec.md)"
+        else
+          log_debug "  ⚠️  No feature ID found and could not auto-generate"
+        fi
       fi
     fi
 
@@ -979,10 +1000,96 @@ EOF_MINIMAL
     fi
   fi
 
-  # Note: Spec-level sync (SPECS → GitHub Projects/JIRA Epics) is handled separately
-  # See: /specweave-github:sync-spec, /specweave-jira:sync-spec, /specweave-ado:sync-spec
+  # ============================================================================
+  # STEP 8: EXPLICIT GITHUB ISSUE CREATION (NEW - ADR-0139)
+  # ============================================================================
+  # After living docs are created, explicitly create GitHub issues for User Stories.
+  # This ensures GitHub issues are created even if sync-living-docs.js gates fail.
+  #
+  # Why this is needed:
+  # - sync-living-docs.js has 5 config gates that can silently skip GitHub sync
+  # - Living docs exist but GitHub issues might not be created
+  # - User expects GitHub issues after /specweave:increment
+  #
+  # Retry mechanism: 2 attempts with 3 second delay
+  # ============================================================================
+
+  log_info ""
+  log_info "🐙 Creating GitHub issues for User Stories..."
+
+  # Check if GitHub is enabled
+  local github_enabled=$(cat "$CONFIG_FILE" 2>/dev/null | grep -A 5 '"github"' | grep -o '"enabled"[[:space:]]*:[[:space:]]*\(true\|false\)' | head -1 | grep -o '\(true\|false\)' || echo "false")
+
+  if [ "$github_enabled" = "true" ] && [ -n "$FEATURE_ID" ]; then
+    # Find the GitHub feature sync script
+    # Priority: dist/ first (compiled with correct imports), then marketplace
+    local GITHUB_SYNC_SCRIPT=""
+    if [ -f "$PROJECT_ROOT/dist/plugins/specweave-github/lib/github-feature-sync-cli.js" ]; then
+      # Prefer dist/ (compiled with correct imports)
+      GITHUB_SYNC_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave-github/lib/github-feature-sync-cli.js"
+    elif [ -n "${CLAUDE_PLUGIN_ROOT}" ]; then
+      # Try specweave-github plugin path (marketplace)
+      local github_plugin_root="${CLAUDE_PLUGIN_ROOT/specweave/specweave-github}"
+      if [ -f "$github_plugin_root/lib/github-feature-sync-cli.js" ]; then
+        GITHUB_SYNC_SCRIPT="$github_plugin_root/lib/github-feature-sync-cli.js"
+      fi
+    elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave-github/lib/github-feature-sync-cli.js" ]; then
+      # Try node_modules (npm install)
+      GITHUB_SYNC_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave-github/lib/github-feature-sync-cli.js"
+    fi
+
+    if [ -n "$GITHUB_SYNC_SCRIPT" ]; then
+      log_info "  🔄 Syncing $FEATURE_ID to GitHub..."
+
+      # Load GitHub token
+      local GITHUB_TOKEN=""
+      if [ -f "$PROJECT_ROOT/.env" ]; then
+        GITHUB_TOKEN=$(grep -E '^GITHUB_TOKEN=' "$PROJECT_ROOT/.env" 2>/dev/null | head -1 | cut -d'=' -f2- | sed 's/^["'\'']//' | sed 's/["'\'']$//')
+      fi
+
+      if [ -z "$GITHUB_TOKEN" ]; then
+        log_info "  ⚠️  GITHUB_TOKEN not found in .env - skipping GitHub sync"
+        log_info "  💡 To enable: Add GITHUB_TOKEN=ghp_xxx to .env"
+      else
+        # Retry mechanism: 2 attempts
+        local github_sync_success=false
+        local max_attempts=2
+
+        for attempt in $(seq 1 $max_attempts); do
+          log_debug "  GitHub sync attempt $attempt of $max_attempts..."
+
+          if GITHUB_TOKEN="$GITHUB_TOKEN" node "$GITHUB_SYNC_SCRIPT" "$FEATURE_ID" 2>&1 | \
+            grep -E "✅|❌|⚠️|📝|🎯|Issue|Milestone" | while read -r line; do echo "  $line"; done; then
+            github_sync_success=true
+            break
+          else
+            if [ "$attempt" -lt "$max_attempts" ]; then
+              log_info "  ⚠️  Attempt $attempt failed, retrying in 3 seconds..."
+              sleep 3
+            fi
+          fi
+        done
+
+        if [ "$github_sync_success" = "true" ]; then
+          log_info "  ✅ GitHub issues created successfully!"
+        else
+          log_info "  ⚠️  GitHub sync failed after $max_attempts attempts (non-blocking)"
+          log_info "  💡 Run /specweave-github:sync $FEATURE_ID manually to retry"
+        fi
+      fi
+    else
+      log_debug "  GitHub sync script not found"
+      log_info "  ℹ️  GitHub sync will be handled by living docs sync"
+    fi
+  elif [ "$github_enabled" != "true" ]; then
+    log_info "  ℹ️  GitHub sync disabled (sync.github.enabled = false)"
+    log_info "  💡 To enable: Set sync.github.enabled = true in config.json"
+  elif [ -z "$FEATURE_ID" ]; then
+    log_info "  ⚠️  No feature ID - GitHub issues cannot be created"
+    log_info "  💡 Add epic: FS-XXX or feature_id: FS-XXX to spec.md frontmatter"
+  fi
 
-  # 8. Sync spec content to external tools (if configured)
+  # 9. Sync spec content to external tools (if configured)
   log_info ""
   log_info "🔗 Checking spec content sync..."
 

package/plugins/specweave/lib/hooks/sync-increment-closure.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { SyncCoordinator } from "../../../../dist/src/sync/sync-coordinator.js";
+import { consoleLogger } from "../vendor/utils/logger.js";
+async function syncIncrementClosure(incrementId) {
+  try {
+    console.log("\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    console.log(`\u{1F512} SYNC INCREMENT CLOSURE: ${incrementId}`);
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    const projectRoot = process.cwd();
+    const coordinator = new SyncCoordinator({
+      projectRoot,
+      incrementId,
+      logger: consoleLogger
+    });
+    const result = await coordinator.syncIncrementClosure();
+    console.log("\n\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+    if (result.success) {
+      console.log("\u2705 INCREMENT CLOSURE SYNC COMPLETED");
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      if (result.closedIssues.length > 0) {
+        console.log(`   Issue numbers: ${result.closedIssues.join(", ")}`);
+      }
+    } else {
+      console.log("\u26A0\uFE0F  INCREMENT CLOSURE SYNC HAD ERRORS");
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      console.log(`   Errors: ${result.errors.length}`);
+    }
+    console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\n");
+    return {
+      success: result.success,
+      closedIssues: result.closedIssues,
+      errors: result.errors
+    };
+  } catch (error) {
+    console.error("\n\u274C FATAL ERROR in sync increment closure:", error.message);
+    return {
+      success: false,
+      closedIssues: [],
+      errors: [error.message]
+    };
+  }
+}
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+  if (!incrementId) {
+    console.error("Usage: node sync-increment-closure.js <increment-id>");
+    console.error("Example: node sync-increment-closure.js 0059-progressive-plugin");
+    process.exit(1);
+  }
+  syncIncrementClosure(incrementId).then((result) => {
+    if (result.success) {
+      console.log("\n\u2705 Increment closure sync completed successfully");
+      process.exit(0);
+    } else {
+      console.error("\n\u26A0\uFE0F  Increment closure sync had errors (non-blocking)");
+      process.exit(0);
+    }
+  }).catch((error) => {
+    console.error("\n\u274C Fatal error:", error);
+    process.exit(0);
+  });
+}
+export {
+  syncIncrementClosure
+};

package/plugins/specweave/lib/hooks/sync-increment-closure.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Sync Increment Closure Hook (NEW in v0.28.1)
+ *
+ * This script handles the CLOSURE flow for increments - closing GitHub issues
+ * when an increment is marked as "completed".
+ *
+ * CRITICAL FIX: Previously, User Story GitHub issues were CREATED but NEVER CLOSED.
+ * This script ensures proper closure of all related issues.
+ *
+ * Called by: post-increment-completion.sh (after increment status → "completed")
+ *
+ * Flow:
+ * 1. Load SyncCoordinator for the increment
+ * 2. Call syncIncrementClosure() which:
+ *    - Ensures all GitHub issues exist (idempotent)
+ *    - Closes all User Story issues with completion comment
+ * 3. Report results
+ *
+ * Usage:
+ *   node sync-increment-closure.js <increment-id>
+ *
+ * Environment:
+ *   GITHUB_TOKEN - Required for GitHub API access
+ */
+
+import { SyncCoordinator } from '../../../../dist/src/sync/sync-coordinator.js';
+import { consoleLogger } from '../vendor/utils/logger.js';
+
+/**
+ * Main function to sync increment closure
+ */
+async function syncIncrementClosure(incrementId: string): Promise<{
+  success: boolean;
+  closedIssues: number[];
+  errors: string[];
+}> {
+  try {
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`🔒 SYNC INCREMENT CLOSURE: ${incrementId}`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+    const projectRoot = process.cwd();
+
+    const coordinator = new SyncCoordinator({
+      projectRoot,
+      incrementId,
+      logger: consoleLogger
+    });
+
+    const result = await coordinator.syncIncrementClosure();
+
+    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    if (result.success) {
+      console.log('✅ INCREMENT CLOSURE SYNC COMPLETED');
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      if (result.closedIssues.length > 0) {
+        console.log(`   Issue numbers: ${result.closedIssues.join(', ')}`);
+      }
+    } else {
+      console.log('⚠️  INCREMENT CLOSURE SYNC HAD ERRORS');
+      console.log(`   Issues closed: ${result.closedIssues.length}`);
+      console.log(`   Errors: ${result.errors.length}`);
+    }
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+    return {
+      success: result.success,
+      closedIssues: result.closedIssues,
+      errors: result.errors
+    };
+  } catch (error: any) {
+    console.error('\n❌ FATAL ERROR in sync increment closure:', error.message);
+    return {
+      success: false,
+      closedIssues: [],
+      errors: [error.message]
+    };
+  }
+}
+
+// CLI Interface
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const incrementId = process.argv[2];
+
+  if (!incrementId) {
+    console.error('Usage: node sync-increment-closure.js <increment-id>');
+    console.error('Example: node sync-increment-closure.js 0059-progressive-plugin');
+    process.exit(1);
+  }
+
+  syncIncrementClosure(incrementId)
+    .then((result) => {
+      if (result.success) {
+        console.log('\n✅ Increment closure sync completed successfully');
+        process.exit(0);
+      } else {
+        console.error('\n⚠️  Increment closure sync had errors (non-blocking)');
+        // Exit 0 to not block the hook chain
+        process.exit(0);
+      }
+    })
+    .catch((error) => {
+      console.error('\n❌ Fatal error:', error);
+      // Exit 0 to not block the hook chain
+      process.exit(0);
+    });
+}
+
+export { syncIncrementClosure };

package/plugins/specweave-github/lib/github-client-v2.js

@@ -138,27 +138,51 @@ class GitHubClientV2 {
    * Validate issue title format
    *
    * CRITICAL: Enforces correct data flow architecture
-   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story - STANDARD)
+   * - ✅ CORRECT: "[FS-XXX] Title" (Feature-level, rare)
    * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   * - ❌ WRONG: "[BUG] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[HOTFIX] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[FEATURE] Title" (type prefixes are labels, not title)
    *
-   * @throws Error if title uses deprecated [Increment XXXX] format
+   * @throws Error if title uses invalid format
    */
   validateIssueTitle(title) {
-    const deprecatedPattern = /\[Increment\s+\d+\]/i;
-    if (deprecatedPattern.test(title)) {
+    const deprecatedIncrementPattern = /\[Increment\s+\d+\]/i;
+    if (deprecatedIncrementPattern.test(title)) {
       throw new Error(
         `\u274C DEPRECATED FORMAT DETECTED: "${title}"
 
 GitHub issues MUST use living docs format:
-  \u2705 CORRECT: "US-XXX: Title" (User Story)
-  \u2705 CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)
+  \u2705 CORRECT: "[FS-XXX][US-YYY] Title" (User Story)
   \u274C WRONG: "[Increment XXXX] Title" (old format)
 
 WHY: Correct data flow is: Increment \u2192 Living Docs \u2192 GitHub
       Living docs are the source of truth for GitHub sync.
 
-FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.
-     OR: Use US/FS ID format directly if creating issues manually.`
+FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.`
+      );
+    }
+    const typePrefixPattern = /^\[(BUG|HOTFIX|FEATURE|DOCS|REFACTOR|CHORE|EXPERIMENT|Bug|Hotfix|Feature|Docs|Refactor|Chore|Experiment)\]/i;
+    if (typePrefixPattern.test(title)) {
+      const match = title.match(typePrefixPattern);
+      const badPrefix = match ? match[0] : "[TYPE]";
+      throw new Error(
+        `\u274C INVALID TITLE FORMAT: "${title}"
+
+Type prefixes like ${badPrefix} belong as LABELS, not in the title!
+
+GitHub issues MUST use this format:
+  \u2705 CORRECT: "[FS-XXX][US-YYY] Title" (User Story)
+  \u274C WRONG: "${badPrefix} Title" (use 'bug' label instead)
+
+WHY: All SpecWeave issues follow [FS-XXX][US-YYY] format for traceability.
+     Use GitHub labels for categorization (bug, enhancement, etc.).
+
+FIX:
+  1. Link this work to a Feature (FS-XXX) and User Story (US-YYY)
+  2. Use /specweave-github:sync to create issue with correct format
+  3. Add '${match ? match[1].toLowerCase() : "bug"}' as a label instead`
       );
     }
   }

package/plugins/specweave-github/lib/github-client-v2.ts

@@ -196,26 +196,48 @@ export class GitHubClientV2 {
    * Validate issue title format
    *
    * CRITICAL: Enforces correct data flow architecture
-   * - ✅ CORRECT: "US-XXX: Title" or "FS-YY-MM-DD: Title"
+   * - ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story - STANDARD)
+   * - ✅ CORRECT: "[FS-XXX] Title" (Feature-level, rare)
    * - ❌ WRONG: "[Increment XXXX] Title" (deprecated old format)
+   * - ❌ WRONG: "[BUG] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[HOTFIX] Title" (type prefixes are labels, not title)
+   * - ❌ WRONG: "[FEATURE] Title" (type prefixes are labels, not title)
    *
-   * @throws Error if title uses deprecated [Increment XXXX] format
+   * @throws Error if title uses invalid format
    */
   private validateIssueTitle(title: string): void {
     // Check for deprecated [Increment XXXX] format
-    const deprecatedPattern = /\[Increment\s+\d+\]/i;
-
-    if (deprecatedPattern.test(title)) {
+    const deprecatedIncrementPattern = /\[Increment\s+\d+\]/i;
+    if (deprecatedIncrementPattern.test(title)) {
       throw new Error(
         `❌ DEPRECATED FORMAT DETECTED: "${title}"\n\n` +
         `GitHub issues MUST use living docs format:\n` +
-        `  ✅ CORRECT: "US-XXX: Title" (User Story)\n` +
-        `  ✅ CORRECT: "FS-YY-MM-DD: Title" (Feature Spec)\n` +
+        `  ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story)\n` +
         `  ❌ WRONG: "[Increment XXXX] Title" (old format)\n\n` +
         `WHY: Correct data flow is: Increment → Living Docs → GitHub\n` +
         `      Living docs are the source of truth for GitHub sync.\n\n` +
-        `FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.\n` +
-        `     OR: Use US/FS ID format directly if creating issues manually.`
+        `FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.`
+      );
+    }
+
+    // Check for type-based prefixes (CRITICAL FIX for issue #749)
+    // These prefixes belong as LABELS, not in the issue title!
+    const typePrefixPattern = /^\[(BUG|HOTFIX|FEATURE|DOCS|REFACTOR|CHORE|EXPERIMENT|Bug|Hotfix|Feature|Docs|Refactor|Chore|Experiment)\]/i;
+    if (typePrefixPattern.test(title)) {
+      const match = title.match(typePrefixPattern);
+      const badPrefix = match ? match[0] : '[TYPE]';
+      throw new Error(
+        `❌ INVALID TITLE FORMAT: "${title}"\n\n` +
+        `Type prefixes like ${badPrefix} belong as LABELS, not in the title!\n\n` +
+        `GitHub issues MUST use this format:\n` +
+        `  ✅ CORRECT: "[FS-XXX][US-YYY] Title" (User Story)\n` +
+        `  ❌ WRONG: "${badPrefix} Title" (use 'bug' label instead)\n\n` +
+        `WHY: All SpecWeave issues follow [FS-XXX][US-YYY] format for traceability.\n` +
+        `     Use GitHub labels for categorization (bug, enhancement, etc.).\n\n` +
+        `FIX:\n` +
+        `  1. Link this work to a Feature (FS-XXX) and User Story (US-YYY)\n` +
+        `  2. Use /specweave-github:sync to create issue with correct format\n` +
+        `  3. Add '${match ? match[1].toLowerCase() : 'bug'}' as a label instead`
       );
     }
   }