specweave 0.28.0 → 0.28.3

package/dist/src/utils/env-file-generator.js

@@ -1,21 +1,18 @@
 /**
  * Environment File Generator
  *
- * Generates .env files with GitHub configuration for sync.
- * Handles security (gitignore, permissions) and multi-provider support.
+ * Generates minimal .env files containing ONLY secrets (tokens).
+ * All configuration is stored in config.json.
  *
- * Features:
- * - Auto-generate .env with GitHub config
- * - Add .env to .gitignore automatically
- * - Create .env.example for team sharing
- * - Multi-provider support (GitHub, JIRA, ADO)
+ * gh CLI is the recommended authentication method.
+ * GITHUB_TOKEN in .env is only needed when gh CLI is not available.
  *
  * @module env-file-generator
  */
 import * as fs from '../utils/fs-native.js';
 import path from 'path';
 /**
- * Generate .env file with GitHub configuration
+ * Generate .env file with GitHub token (only when gh CLI not available)
  *
  * @param projectRoot - Project root directory
  * @param config - Environment configuration
@@ -38,45 +35,29 @@ export async function generateEnvFile(projectRoot, config) {
     await updateGitignore(projectRoot);
 }
 /**
- * Build .env file content
+ * Build .env file content (secrets only)
  *
  * @param config - Environment configuration
  * @returns .env content
  */
 function buildEnvContent(config) {
     const lines = [];
-    lines.push('# GitHub Configuration (Auto-generated by SpecWeave)');
+    lines.push('# GitHub Token (Auto-generated by SpecWeave)');
     lines.push(`# Created: ${new Date().toISOString()}`);
+    lines.push('#');
+    lines.push('# NOTE: gh CLI authentication is recommended over tokens.');
+    lines.push('# Run: gh auth login');
+    lines.push('# This file is only needed if gh CLI is not available.');
     lines.push('');
-    // GitHub token
+    // GitHub token - the ONLY secret
     if (config.githubToken) {
         lines.push(`GITHUB_TOKEN=${config.githubToken}`);
     }
     else {
         lines.push('GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx');
     }
-    // GitHub owner
-    if (config.githubOwner) {
-        lines.push(`GITHUB_OWNER=${config.githubOwner}`);
-    }
-    else {
-        lines.push('GITHUB_OWNER=myorg');
-    }
-    lines.push('');
-    lines.push('# Repository Mapping (id:repo-name)');
-    // Repos
-    if (config.repos && config.repos.length > 0) {
-        const repoMappings = config.repos.map(r => `${r.id}:${r.repo}`).join(',');
-        lines.push(`GITHUB_REPOS=${repoMappings}`);
-    }
-    else {
-        lines.push('GITHUB_REPOS=parent:my-project-parent,frontend:my-project-frontend,backend:my-project-backend');
-    }
     lines.push('');
-    lines.push('# Sync Configuration');
-    lines.push(`GITHUB_SYNC_ENABLED=${config.syncEnabled !== false ? 'true' : 'false'}`);
-    lines.push(`GITHUB_AUTO_CREATE_ISSUE=${config.autoCreateIssue !== false ? 'true' : 'false'}`);
-    lines.push(`GITHUB_SYNC_DIRECTION=${config.syncDirection || 'bidirectional'}`);
+    lines.push('# All other configuration is in .specweave/config.json');
     return lines.join('\n') + '\n';
 }
 /**
@@ -87,21 +68,19 @@ function buildEnvContent(config) {
 function buildEnvExampleContent() {
     const lines = [];
     lines.push('# GitHub Configuration');
-    lines.push('# Copy this file to .env and fill in your values');
+    lines.push('#');
+    lines.push('# RECOMMENDED: Use gh CLI instead of tokens');
+    lines.push('#   gh auth login');
+    lines.push('#');
+    lines.push('# Only use this file if gh CLI is not available.');
+    lines.push('# Copy to .env and fill in your token.');
     lines.push('');
-    lines.push('# GitHub Personal Access Token (get from https://github.com/settings/tokens)');
+    lines.push('# GitHub Personal Access Token');
+    lines.push('# Get from: https://github.com/settings/tokens');
+    lines.push('# Scopes: repo, read:org');
     lines.push('GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx');
     lines.push('');
-    lines.push('# GitHub owner (user or organization)');
-    lines.push('GITHUB_OWNER=your-username-or-org');
-    lines.push('');
-    lines.push('# Repository Mapping (id:repo-name,id:repo-name,...)');
-    lines.push('GITHUB_REPOS=parent:my-project-parent,frontend:my-project-frontend,backend:my-project-backend');
-    lines.push('');
-    lines.push('# Sync Configuration');
-    lines.push('GITHUB_SYNC_ENABLED=true');
-    lines.push('GITHUB_AUTO_CREATE_ISSUE=true');
-    lines.push('GITHUB_SYNC_DIRECTION=bidirectional');
+    lines.push('# All other configuration is in .specweave/config.json');
     return lines.join('\n') + '\n';
 }
 /**
@@ -145,10 +124,10 @@ export async function envFileExists(projectRoot) {
     return fs.pathExists(envPath);
 }
 /**
- * Load configuration from .env file
+ * Load GitHub token from .env file
  *
  * @param projectRoot - Project root directory
- * @returns Environment configuration
+ * @returns GitHub token or null
  */
 export async function loadEnvConfig(projectRoot) {
     const envPath = path.join(projectRoot, '.env');
@@ -163,32 +142,13 @@ export async function loadEnvConfig(projectRoot) {
         if (trimmed.startsWith('#') || !trimmed) {
             continue;
         }
-        const [key, value] = trimmed.split('=');
-        if (!key || !value) {
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1)
             continue;
-        }
-        switch (key.trim()) {
-            case 'GITHUB_TOKEN':
-                config.githubToken = value.trim();
-                break;
-            case 'GITHUB_OWNER':
-                config.githubOwner = value.trim();
-                break;
-            case 'GITHUB_REPOS':
-                config.repos = value.trim().split(',').map(mapping => {
-                    const [id, repo] = mapping.split(':');
-                    return { id: id.trim(), repo: repo.trim() };
-                });
-                break;
-            case 'GITHUB_SYNC_ENABLED':
-                config.syncEnabled = value.trim() === 'true';
-                break;
-            case 'GITHUB_AUTO_CREATE_ISSUE':
-                config.autoCreateIssue = value.trim() === 'true';
-                break;
-            case 'GITHUB_SYNC_DIRECTION':
-                config.syncDirection = value.trim();
-                break;
+        const key = trimmed.slice(0, eqIndex).trim();
+        const value = trimmed.slice(eqIndex + 1).trim();
+        if (key === 'GITHUB_TOKEN') {
+            config.githubToken = value;
         }
     }
     return config;

package/dist/src/utils/env-file-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"env-file-generator.js","sourceRoot":"","sources":["../../../src/utils/env-file-generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"env-file-generator.js","sourceRoot":"","sources":["../../../src/utils/env-file-generator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.0",
+  "version": "0.28.3",
   "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",
@@ -34,7 +34,12 @@
     "docs:build": "cd docs-site && npm run build",
     "docs:install": "cd docs-site && npm install --legacy-peer-deps",
     "docs:internal": "mkdocs serve -f docs-site/mkdocs-internal.yml",
-    "docs:internal:build": "mkdocs build -f docs-site/mkdocs-internal.yml"
+    "docs:internal:build": "mkdocs build -f docs-site/mkdocs-internal.yml",
+    "release:patch": "bash scripts/bump-version.sh patch",
+    "release:minor": "bash scripts/bump-version.sh minor",
+    "release:major": "bash scripts/bump-version.sh major",
+    "release": "bash scripts/bump-version.sh",
+    "setup:hooks": "bash scripts/install-git-hooks.sh"
   },
   "keywords": [
     "specweave",

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

@@ -2,8 +2,8 @@
 name: architect
 description: System Architect and technical design expert. Creates system architecture, technical specifications, Architecture Decision Records (ADRs), component designs, API contracts, data models, and deployment architectures. Handles design patterns, scalability planning, technology stack decisions, microservices architecture, event-driven systems, CQRS, domain-driven design. Activates for: architecture, system design, technical design, ADR, architecture decision record, design patterns, microservices, API design, data model, database schema, scalability, performance architecture, technology stack, tech stack selection, distributed systems, event-driven, CQRS, DDD, domain model, component architecture, integration patterns, CAP theorem, consistency, availability, partition tolerance.
 tools: Read, Write, 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/agents/docs-writer/AGENT.md

@@ -2,8 +2,8 @@
 name: docs-writer
 description: Technical documentation writer that generates docs ONE SECTION AT A TIME (Installation → Usage → API → Examples) to prevent crashes. Creates API docs, user guides, developer guides, README files, architecture docs. **CRITICAL CHUNKING RULE - Prevents 3000+ line doc crashes.** Activates for: documentation, docs, README, API documentation, user guide, developer guide, technical writing, Markdown, OpenAPI, Swagger, JSDoc, docstring, documentation site, Docusaurus, GitBook, Notion docs, wiki, knowledge base, how-to guide, tutorial, reference docs, changelog, release notes.
 tools: Read, Write, Edit
-model: claude-haiku-4-5-20251001
-model_preference: auto
+model: claude-opus-4-5-20251101
+model_preference: opus
 cost_profile: hybrid
 fallback_behavior: auto
 max_response_tokens: 2000

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

@@ -2,8 +2,8 @@
 name: pm
 description: Product Manager AI agent that works in PHASES (Research → Spec → Architect → Plan → Validate) to prevent crashes. Creates product strategy, requirements, user stories, prioritization. **CRITICAL CHUNKING RULE - Large specs (6+ US) generated in chunks.** Activates for product planning, roadmap creation, requirement analysis, user research, business case development. Keywords: product strategy, chunked planning, user stories, requirements, roadmap, prioritization, MVP, feature planning, stakeholders, business case, product vision, RICE, MoSCoW, Kano, product-market fit.
 tools: Read, Write, Grep, Glob
-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/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/hooks.json

@@ -34,6 +34,16 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-edit.sh"
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "matcher_content": "\\.specweave/increments/[0-9]{4}-.+/metadata\\.json",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-metadata-change.sh"
+          }
+        ]
       }
     ]
   }

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/hooks/post-metadata-change.sh

@@ -61,6 +61,24 @@ fi
 # Ensure logs directory exists
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
+# ============================================================================
+# CREATE RECURSION GUARD (v0.28.2 - CRITICAL FIX)
+# ============================================================================
+# PROBLEM FIXED: Guard was only created in post-increment-completion.sh, but
+# post-increment-status-change.sh had NO guard protection.
+#
+# SOLUTION: Create guard here in the dispatcher so ALL dispatches are protected.
+# The sub-hooks (post-increment-completion.sh, post-increment-status-change.sh)
+# will see this guard and exit early if they're called recursively.
+#
+# This prevents infinite loops if any sync operation modifies metadata.json.
+
+mkdir -p "$PROJECT_ROOT/.specweave/state" 2>/dev/null || true
+touch "$RECURSION_GUARD_FILE"
+
+# Ensure guard file is ALWAYS removed when script exits (even on error)
+trap 'rm -f "$RECURSION_GUARD_FILE" 2>/dev/null || true' EXIT SIGINT SIGTERM
+
 # ============================================================================
 # READ STDIN (v0.26.1 - CRITICAL FIX)
 # ============================================================================