specweave 0.33.5 → 0.34.0

package/plugins/specweave/hooks/github-metadata-guard.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# github-metadata-guard.sh - Prevents redundant metadata headers in GitHub issue bodies
+# WHY: GitHub has NATIVE fields (labels, milestones) - metadata belongs there, NOT in body
+# See: .specweave/docs/internal/troubleshooting/CRITICAL-remove-metadata-header-from-github-issues.md
+
+# Activation: PreToolUse event for Write/Edit tools
+# Blocks: Any attempt to add metadata header (Feature, Status, Priority, Project) to GitHub issue body builders
+
+# Exit codes:
+# 0 = Allow operation (no metadata header detected)
+# 1 = Block operation (metadata header detected)
+
+# Only validate Write/Edit operations in GitHub plugin files
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Only check GitHub issue body builder files
+if [[ ! "$file_path" =~ plugins/specweave-github/lib/.*issue.*builder\.ts$ ]]; then
+  exit 0
+fi
+
+# Get content to check (new_string for Edit, content for Write)
+content_to_check=""
+if [[ "$TOOL_NAME" == "Edit" ]]; then
+  content_to_check="$new_string"
+elif [[ "$TOOL_NAME" == "Write" ]]; then
+  content_to_check="$content"
+fi
+
+# Check for metadata header patterns (case-insensitive)
+if echo "$content_to_check" | grep -qiE '^\*\*Feature\*\*:|^\*\*Status\*\*:|^\*\*Priority\*\*:|^\*\*Project\*\*:'; then
+  echo "❌ BLOCKED: GitHub issue body MUST NOT contain metadata header!" >&2
+  echo "" >&2
+  echo "WHY: GitHub has NATIVE fields for metadata:" >&2
+  echo "  - Feature → Milestone" >&2
+  echo "  - Status → Label (status:*)" >&2
+  echo "  - Priority → Label (p1, p2, p3)" >&2
+  echo "  - Project → Label (project:*)" >&2
+  echo "" >&2
+  echo "Body should contain ONLY actual work content:" >&2
+  echo "  ✅ ## Progress" >&2
+  echo "  ✅ ## User Story" >&2
+  echo "  ✅ ## Acceptance Criteria" >&2
+  echo "  ✅ ## Tasks" >&2
+  echo "" >&2
+  echo "See: .specweave/docs/internal/troubleshooting/CRITICAL-remove-metadata-header-from-github-issues.md" >&2
+  exit 1
+fi
+
+# Check for metadata at start of body string assignments
+if echo "$content_to_check" | grep -qE 'body \+= `\*\*(Feature|Status|Priority|Project)\*\*:'; then
+  echo "❌ BLOCKED: Metadata header assignment detected in GitHub issue body builder!" >&2
+  echo "" >&2
+  echo "Detected pattern: body += \`**Feature**:\` or similar" >&2
+  echo "" >&2
+  echo "FORBIDDEN CODE:" >&2
+  echo "  body += \`**Feature**: \${featureId}\`;" >&2
+  echo "  body += \`**Status**: \${status}\`;" >&2
+  echo "  body += \`**Priority**: \${priority}\`;" >&2
+  echo "  body += \`**Project**: \${project}\`;" >&2
+  echo "" >&2
+  echo "Use labels instead:" >&2
+  echo "  labels.push(\`status:\${status}\`);" >&2
+  echo "  labels.push(priority.toLowerCase());" >&2
+  echo "  labels.push(\`project:\${project}\`);" >&2
+  echo "" >&2
+  echo "See: .specweave/docs/internal/troubleshooting/CRITICAL-remove-metadata-header-from-github-issues.md" >&2
+  exit 1
+fi
+
+# Allow operation (no metadata header detected)
+exit 0

package/plugins/specweave/hooks/hooks.json

@@ -56,7 +56,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/spec-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/per-us-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
       },
@@ -66,7 +66,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/per-us-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/spec-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
       },
@@ -99,6 +99,36 @@
             "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/increment-root-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
           }
         ]
+      },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/docs/internal/specs/[^/]+/",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/project-folder-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "matcher_content": "/src/.*\\.ts$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/config-env-separator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "matcher_content": "plugins/specweave-github/lib/.*issue.*builder\\.ts$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/github-metadata-guard.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -52,8 +52,8 @@ echo "   - Specs: .specweave/docs/internal/specs/"
 echo "   - Architecture: .specweave/docs/internal/architecture/"
 echo ""
 echo "🚀 Next steps:"
-echo "   - Review your increment: /specweave:status"
-echo "   - Start next increment: /specweave:increment \"feature name\""
+echo "   - Review your increment: /sw:status"
+echo "   - Start next increment: /sw:increment \"feature name\""
 echo ""
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo ""

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

@@ -127,7 +127,7 @@ fi
 # This ensures source-of-truth discipline is maintained.
 #
 # See: Incident 2025-11-20 - metadata.json="completed" but spec.md="active"
-# See: /specweave:sync-status command for manual recovery
+# See: /sw:sync-status command for manual recovery
 
 SPEC_FILE="$INCREMENT_DIR/spec.md"
 
@@ -196,7 +196,7 @@ echo "✅ Status line cache updated"
 #
 # Architecture Decision: Non-blocking execution
 # - If sync fails, log error but don't crash hook (GitHub issue already closed)
-# - Living docs can be manually synced later with /specweave:sync-docs
+# - Living docs can be manually synced later with /sw:sync-docs
 # - Failure mode: Graceful degradation (increment still completes)
 
 if command -v node &> /dev/null; then
@@ -298,19 +298,19 @@ if command -v node &> /dev/null; then
     # Pass FEATURE_ID and PROJECT_ID as environment variables if available
     if [ -n "$FEATURE_ID" ]; then
       (cd "$PROJECT_ROOT" && FEATURE_ID="$FEATURE_ID" PROJECT_ID="$PROJECT_ID" node "$SYNC_SCRIPT" "$INCREMENT_ID") 2>&1 || {
-        echo "  ⚠️  Failed to sync living docs (non-blocking - you can run /specweave:sync-docs manually)" >&2
+        echo "  ⚠️  Failed to sync living docs (non-blocking - you can run /sw:sync-docs manually)" >&2
       }
     else
       # No explicit feature ID - sync will auto-generate
       (cd "$PROJECT_ROOT" && PROJECT_ID="$PROJECT_ID" node "$SYNC_SCRIPT" "$INCREMENT_ID") 2>&1 || {
-        echo "  ⚠️  Failed to sync living docs (non-blocking - you can run /specweave:sync-docs manually)" >&2
+        echo "  ⚠️  Failed to sync living docs (non-blocking - you can run /sw:sync-docs manually)" >&2
       }
     fi
     echo "  ✅ Living docs sync complete"
     echo ""
   else
     echo "  ⚠️  sync-living-docs.js not found in any location - skipping living docs sync" >&2
-    echo "  💡 To manually sync: /specweave:sync-docs update" >&2
+    echo "  💡 To manually sync: /sw:sync-docs update" >&2
     echo ""
   fi
 else
@@ -410,13 +410,13 @@ if command -v node &> /dev/null; then
       echo "  ✅ GitHub sync complete"
       echo ""
     else
-      echo "  ⚠️  Failed to sync GitHub issues (non-blocking - you can run /specweave-github:sync manually)" >&2
+      echo "  ⚠️  Failed to sync GitHub issues (non-blocking - you can run /sw-github:sync manually)" >&2
       echo "  💡 Check that sync.github.enabled=true in .specweave/config.json" >&2
       echo ""
     fi
   else
     echo "  ⚠️  consolidated-sync.js not found in any location - skipping GitHub sync" >&2
-    echo "  💡 To manually sync: /specweave-github:sync" >&2
+    echo "  💡 To manually sync: /sw-github:sync" >&2
     echo ""
   fi
 else

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

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # SpecWeave Post-Increment-Planning Hook
-# Runs automatically after /specweave:inc completes
+# Runs automatically after /sw:inc completes
 #
 # PURPOSE:
 # Translates newly generated spec.md, plan.md, and tasks.md from target language
@@ -13,7 +13,7 @@
 # - Cost: ~$0.01 per increment (using Haiku)
 #
 # WORKFLOW:
-# 1. User runs: /specweave:inc "Добавить AI чат-бот" (in Russian)
+# 1. User runs: /sw:inc "Добавить AI чат-бот" (in Russian)
 # 2. PM agent generates spec.md in Russian (natural, user-friendly)
 # 3. THIS HOOK fires automatically
 # 4. Detects non-English content
@@ -741,7 +741,7 @@ EOF
   #
   # Feature/Increment-level issues like "[FS-047] Title" are NO LONGER created.
   # Instead, use:
-  #   /specweave-github:sync FS-047
+  #   /sw-github:sync FS-047
   #
   # This creates PROPER User Story-level issues:
   #   [FS-047][US-001] User Story Title
@@ -759,10 +759,10 @@ EOF
   local can_upsert=$(cat "$CONFIG_FILE" 2>/dev/null | grep -A 5 '"sync"' | grep -A 5 '"settings"' | grep -o '"canUpsertInternalItems"[[:space:]]*:[[:space:]]*\(true\|false\)' | grep -o '\(true\|false\)' || echo "false")
 
   # DEPRECATED: Override to false unless explicitly enabled via env var
-  # This entire section is deprecated - use /specweave-github:sync for User Story-level issues
+  # This entire section is deprecated - use /sw-github:sync for User Story-level issues
   if [ "$SPECWEAVE_ENABLE_INCREMENT_GITHUB_SYNC" != "true" ]; then
     can_upsert="false"
-    log_debug "Increment GitHub sync disabled (use /specweave-github:sync for User Story-level issues)"
+    log_debug "Increment GitHub sync disabled (use /sw-github:sync for User Story-level issues)"
   fi
 
   log_debug "Can upsert internal items (deprecated increment sync): $can_upsert"
@@ -770,7 +770,7 @@ EOF
 
   if [ "$auto_create" = "true" ]; then
     log_info "  ⚠️  WARNING: Increment-level sync is DEPRECATED"
-    log_info "  ✅ Use /specweave-github:sync for [FS-XXX][US-YYY] format"
+    log_info "  ✅ Use /sw-github:sync for [FS-XXX][US-YYY] format"
     log_info "  📦 Auto-create enabled, checking for GitHub CLI..."
 
     # ============================================================================
@@ -891,7 +891,7 @@ EOF_MINIMAL
 
     log_info "  ✅ Created minimal metadata.json"
     log_info "  ⚠️  Note: No GitHub issue linked"
-    log_info "  💡 Run /specweave-github:create-issue $increment_id to create one manually"
+    log_info "  💡 Run /sw-github:create-issue $increment_id to create one manually"
   else
     log_info "  ✅ metadata.json exists"
 
@@ -921,7 +921,7 @@ EOF_MINIMAL
   # Previous behavior (BROKEN):
   # - Living docs only synced AFTER first task completion
   # - New increments had empty living docs until tasks marked complete
-  # - Manual /specweave:sync-docs required for every new increment
+  # - Manual /sw:sync-docs required for every new increment
   #
   # New behavior (FIXED):
   # - Living docs auto-sync during increment creation
@@ -1034,7 +1034,7 @@ EOF_MINIMAL
       log_info "  ✅ Living docs sync complete!"
     else
       log_info "  ⚠️  sync-living-docs.js not found, skipping auto-sync"
-      log_info "  💡 Run /specweave:sync-docs manually to sync living docs"
+      log_info "  💡 Run /sw:sync-docs manually to sync living docs"
     fi
   else
     if ! command -v node &> /dev/null; then
@@ -1053,7 +1053,7 @@ EOF_MINIMAL
   # 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
+  # - User expects GitHub issues after /sw:increment
   #
   # Retry mechanism: 2 attempts with 3 second delay
   # ============================================================================
@@ -1118,7 +1118,7 @@ EOF_MINIMAL
           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"
+          log_info "  💡 Run /sw-github:sync $FEATURE_ID manually to retry"
         fi
       fi
     else

package/plugins/specweave/hooks/post-increment-status-change.sh

@@ -3,7 +3,7 @@
 # SpecWeave Post-Increment-Status-Change Hook (v0.28.33)
 # Runs automatically after increment status changes (pause/resume/abandon)
 #
-# Trigger: /specweave:pause, /specweave:resume, /specweave:abandon commands
+# Trigger: /sw:pause, /sw:resume, /sw:abandon commands
 # Purpose: Sync GitHub issue state with increment status
 #
 # What it does:

package/plugins/specweave/hooks/post-metadata-change.sh

@@ -207,7 +207,7 @@ case "$CURRENT_STATUS" in
 
   paused|resumed|abandoned)
     # Status change - call post-increment-status-change.sh
-    # Note: This typically gets called manually by /specweave:pause commands
+    # Note: This typically gets called manually by /sw:pause commands
     # But we handle it here for completeness
     echo "[$(date)] post-metadata-change: Status changed to $CURRENT_STATUS - calling post-increment-status-change.sh" >> "$DEBUG_LOG" 2>/dev/null || true
 

package/plugins/specweave/hooks/post-spec-update.sh

@@ -9,7 +9,7 @@
 # - Replaces increment-based sync (which was wrong!)
 #
 # Trigger Points:
-# 1. After /specweave:sync-docs update (spec updated from increment)
+# 1. After /sw:sync-docs update (spec updated from increment)
 # 2. After manual spec.md edits (user updates living docs directly)
 # 3. After bidirectional sync from external tool
 #
@@ -98,7 +98,7 @@ fi
 # No external link found - skip sync
 if [[ -z "$PROVIDER" ]]; then
   echo "   ℹ️  Spec not linked to external tool, skipping sync"
-  echo "   Hint: Use /specweave-github:sync-spec or /specweave-jira:sync-spec to link"
+  echo "   Hint: Use /sw-github:sync-spec or /sw-jira:sync-spec to link"
   exit 0
 fi
 

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

@@ -418,8 +418,8 @@ fi
   #
   # NEW STRATEGY: Run consolidated sync ONLY at:
   # 1. Session end (all tasks done + 120s inactivity)
-  # 2. Manual sync (/specweave:sync-docs command)
-  # 3. Increment closure (/specweave:done validation)
+  # 2. Manual sync (/sw:sync-docs command)
+  # 3. Increment closure (/sw:done validation)
   #
   # See: .specweave/increments/0051-*/reports/CLAUDE-CODE-CRASH-ROOT-CAUSE-2025-11-23.md
   # See: ADR-0072 (Post-Task Hook Simplification)

package/plugins/specweave/hooks/pre-increment-start.sh

@@ -2,7 +2,7 @@
 #
 # Pre-Increment-Start Hook
 #
-# Validates increment readiness before allowing `/specweave:do` to start work.
+# Validates increment readiness before allowing `/sw:do` to start work.
 #
 # **Critical Checks**:
 # 1. spec.md contains Acceptance Criteria
@@ -10,7 +10,7 @@
 # 3. No duplicate task files (tasks.md, tasks-detailed.md)
 # 4. Increment structure is valid
 #
-# **Triggered by**: /specweave:do command (before starting implementation)
+# **Triggered by**: /sw:do command (before starting implementation)
 #
 # **Exit codes**:
 # - 0: Validation passed, safe to start
@@ -62,7 +62,7 @@ if [ -f "$INCREMENT_PATH/spec.md" ]; then
     echo "   Even when using 'structure: user-stories', ACs must be embedded in spec.md."
     echo ""
     echo "   💡 SUGGESTED FIX:"
-    echo "      Run: /specweave:embed-acs $(basename "$INCREMENT_PATH")"
+    echo "      Run: /sw:embed-acs $(basename "$INCREMENT_PATH")"
     echo ""
     VALIDATION_PASSED=false
   fi
@@ -81,7 +81,7 @@ if [ "$AC_COUNT" -eq 0 ]; then
   echo ""
   echo "   💡 SUGGESTED FIX:"
   echo "      1. Add ACs manually to spec.md, OR"
-  echo "      2. Run: /specweave:embed-acs $(basename "$INCREMENT_PATH") (auto-embed from living docs)"
+  echo "      2. Run: /sw:embed-acs $(basename "$INCREMENT_PATH") (auto-embed from living docs)"
   echo ""
   VALIDATION_PASSED=false
 else
@@ -140,7 +140,7 @@ if [ -f "$INCREMENT_PATH/spec.md" ]; then
       echo "  even when living docs exist as documentation layer."
       echo ""
       echo "**IMMEDIATE ACTION REQUIRED**:"
-      echo "  Run: /specweave:embed-acs $(basename "$INCREMENT_PATH")"
+      echo "  Run: /sw:embed-acs $(basename "$INCREMENT_PATH")"
       echo ""
       echo "This will auto-embed ACs from living docs into spec.md."
       echo ""
@@ -158,7 +158,7 @@ if [ "$VALIDATION_PASSED" = true ]; then
   echo "✅ PRE-START VALIDATION: PASSED"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   echo ""
-  echo "Increment is ready to start. Proceeding with /specweave:do..."
+  echo "Increment is ready to start. Proceeding with /sw:do..."
   exit 0
 else
   echo "❌ PRE-START VALIDATION: FAILED"
@@ -167,7 +167,7 @@ else
   echo "Cannot start increment due to validation failures above."
   echo ""
   echo "Fix the issues and try again, or run validation manually:"
-  echo "  /specweave:validate $(basename "$INCREMENT_PATH")"
+  echo "  /sw:validate $(basename "$INCREMENT_PATH")"
   echo ""
   exit 1
 fi