specweave 1.0.22 → 1.0.24

package/plugins/specweave/hooks/docs-changed.sh.backup

@@ -0,0 +1,79 @@
+#!/bin/bash
+
+# SpecWeave Docs-Changed Hook
+# Runs after file changes are detected
+# Detects if documentation was changed during implementation
+# Triggers review workflow if needed
+
+set -e
+
+# Find project root by searching upward for .specweave/ directory
+# Works regardless of where hook is installed (source or .claude/hooks/)
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT"
+
+# Colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Get changed files (git)
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  # Not a git repository, skip
+  exit 0
+fi
+
+CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null || echo "")
+
+if [ -z "$CHANGED_FILES" ]; then
+  # No changes
+  exit 0
+fi
+
+# Check if any documentation files changed
+DOC_CHANGES=$(echo "$CHANGED_FILES" | grep -E '\.specweave/(docs|increments/.*/.*\.md)' || true)
+
+if [ -n "$DOC_CHANGES" ]; then
+  echo -e "${RED}⚠️  Documentation changed during implementation${NC}"
+  echo ""
+  echo "📋 Files changed:"
+  echo "$DOC_CHANGES" | sed 's/^/   /'
+  echo ""
+  echo -e "${YELLOW}🔔 Recommended actions:${NC}"
+  echo "  1. Review documentation changes"
+  echo "  2. Update tasks.md if architecture changed"
+  echo "  3. Type /review-docs to see full impact"
+  echo ""
+
+  # Play notification sound
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga 2>/dev/null || true
+      ;;
+  esac
+
+  # Log to hooks log
+  LOGS_DIR=".specweave/logs"
+  mkdir -p "$LOGS_DIR"
+  echo "[$(date)] Documentation changed: $DOC_CHANGES" >> "$LOGS_DIR/hooks.log"
+fi

package/plugins/specweave/hooks/human-input-required.sh.backup

@@ -0,0 +1,75 @@
+#!/bin/bash
+
+# SpecWeave Human-Input-Required Hook
+# Runs when Claude needs clarification or approval
+#
+# Actions:
+# 1. Play notification sound (Ping.aiff)
+# 2. Log the question/requirement
+# 3. Record in current increment's work log (if applicable)
+
+set -e
+
+# Find project root by searching upward for .specweave/ directory
+# Works regardless of where hook is installed (source or .claude/hooks/)
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  # Fallback: try current directory
+  if [ -d "$(pwd)/.specweave" ]; then
+    pwd
+  else
+    echo "$(pwd)"
+  fi
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT"
+
+# Get question/requirement (passed as argument or default)
+QUESTION="${1:-User input required}"
+
+echo "❓ Human input required"
+
+# 1. Play notification sound (cross-platform)
+play_sound() {
+  case "$(uname -s)" in
+    Darwin)
+      afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+      ;;
+    Linux)
+      paplay /usr/share/sounds/freedesktop/stereo/dialog-question.oga 2>/dev/null || \
+      aplay /usr/share/sounds/alsa/Side_Left.wav 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      powershell -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\notify.wav').PlaySync();" 2>/dev/null || true
+      ;;
+  esac
+}
+
+play_sound &
+
+# 2. Log to main hooks log
+LOGS_DIR=".specweave/logs"
+mkdir -p "$LOGS_DIR"
+echo "[$(date)] Human input required: $QUESTION" >> "$LOGS_DIR/hooks.log"
+
+# 3. Log to current work context (if exists)
+CURRENT_WORK=$(find .specweave/work -maxdepth 1 -type d -name "current-*" | head -1 || true)
+
+if [ -n "$CURRENT_WORK" ] && [ -d "$CURRENT_WORK" ]; then
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "## Input Required ($(date +%Y-%m-%d\ %H:%M))" >> "$CURRENT_WORK/notes.md"
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "$QUESTION" >> "$CURRENT_WORK/notes.md"
+    echo "" >> "$CURRENT_WORK/notes.md"
+    echo "📝 Logged to $CURRENT_WORK/notes.md"
+fi
+
+echo "✅ Hook complete"

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# SpecWeave Post-First-Increment Hook
+#
+# Triggers after the first increment is completed
+# Congratulates the user on completing their first increment
+#
+# NON-INTERACTIVE: Just shows a message (hooks run in background)
+
+set -euo pipefail
+
+# Get project root (where .specweave/ lives)
+PROJECT_ROOT="$(pwd)"
+
+# Check if .specweave directory exists
+if [ ! -d ".specweave" ]; then
+  # Not in SpecWeave project, skip
+  exit 0
+fi
+
+# Check if this is the first increment completion
+# Count completed increments in .specweave/increments/
+COMPLETED_COUNT=0
+if [ -d ".specweave/increments" ]; then
+  # Count directories that have COMPLETION-REPORT.md or completion metadata
+  for inc_dir in .specweave/increments/[0-9][0-9][0-9][0-9]-*/; do
+    if [ -d "$inc_dir" ]; then
+      if [ -f "${inc_dir}reports/COMPLETION-REPORT.md" ] || \
+         [ -f "${inc_dir}COMPLETION-SUMMARY.md" ] || \
+         ([ -f "${inc_dir}metadata.json" ] && grep -q '"status".*"completed"' "${inc_dir}metadata.json" 2>/dev/null); then
+        COMPLETED_COUNT=$((COMPLETED_COUNT + 1))
+      fi
+    fi
+  done
+fi
+
+# Only trigger on first completion
+if [ "$COMPLETED_COUNT" -ne 1 ]; then
+  exit 0
+fi
+
+# Show congratulations message (non-interactive)
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 Congratulations! You completed your first increment!"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "✅ Your increment has been documented in:"
+echo "   .specweave/increments/[increment-id]/"
+echo ""
+echo "📚 View your documentation:"
+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 ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+exit 0

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

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# SpecWeave Post-Increment-Change Hook
+# Runs automatically after increment files (spec.md, plan.md, tasks.md) are modified
+#
+# Trigger: File watcher or git hook (pre-commit/post-commit)
+# Purpose: Sync increment file changes to GitHub issues
+#
+# What it does:
+# 1. Detects which file changed (spec.md, plan.md, tasks.md)
+# 2. Invokes GitHub sync for increment changes
+# 3. Updates GitHub issue with scope/plan/task changes
+#
+# Usage:
+#   ./post-increment-change.sh <incrementId> <changedFile>
+#
+# Example:
+#   ./post-increment-change.sh 0015-hierarchical-sync spec.md
+
+set -e
+
+# Find project root
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  pwd
+}
+
+PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)")"
+cd "$PROJECT_ROOT" 2>/dev/null || true
+
+# Configuration
+LOGS_DIR=".specweave/logs"
+DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
+
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+# Arguments
+INCREMENT_ID="$1"
+CHANGED_FILE="$2"
+
+if [ -z "$INCREMENT_ID" ] || [ -z "$CHANGED_FILE" ]; then
+  echo "Usage: $0 <incrementId> <changedFile>" >&2
+  echo "Example: $0 0015-hierarchical-sync spec.md" >&2
+  exit 1
+fi
+
+echo "[$(date)] 📝 Increment file changed: $CHANGED_FILE" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Validate changed file
+case "$CHANGED_FILE" in
+  spec.md|plan.md|tasks.md)
+    ;;
+  *)
+    echo "[$(date)] ⚠️  Unknown file type: $CHANGED_FILE (skipping sync)" >> "$DEBUG_LOG" 2>/dev/null || true
+    exit 0
+    ;;
+esac
+
+# Check if Node.js available
+if ! command -v node &> /dev/null; then
+  echo "[$(date)] ⚠️  Node.js not found, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Check if GitHub CLI available
+if ! command -v gh &> /dev/null; then
+  echo "[$(date)] ℹ️  GitHub CLI not found, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Check if authenticated
+if ! gh auth status &> /dev/null; then
+  echo "[$(date)] ℹ️  GitHub CLI not authenticated, skipping sync" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
+# Sync to GitHub
+echo "[$(date)] 🔄 Syncing $CHANGED_FILE changes to GitHub..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+node dist/plugins/specweave-github/lib/github-sync-increment-changes.js "$INCREMENT_ID" "$CHANGED_FILE" 2>&1 | tee -a "$DEBUG_LOG" >/dev/null || {
+  echo "[$(date)] ⚠️  Failed to sync increment changes (non-blocking)" >> "$DEBUG_LOG" 2>/dev/null || true
+}
+
+echo "[$(date)] ✅ Post-increment-change hook complete" >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Update status line cache (increment changed)
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
+# Return success (non-blocking)
+exit 0

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

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+
+# Post-Increment-Completion Hook
+# Runs after an increment is marked as complete
+#
+# This hook closes GitHub issues automatically when increments complete
+
+set -e
+
+HOOK_NAME="post-increment-completion"
+INCREMENT_ID="${1:-}"
+
+# Check if increment ID provided
+if [ -z "$INCREMENT_ID" ]; then
+  echo "⚠️  $HOOK_NAME: No increment ID provided" >&2
+  exit 0
+fi
+
+# Get project root
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+INCREMENT_DIR="$PROJECT_ROOT/.specweave/increments/$INCREMENT_ID"
+
+# Check if increment exists
+if [ ! -d "$INCREMENT_DIR" ]; then
+  echo "⚠️  $HOOK_NAME: Increment $INCREMENT_ID not found" >&2
+  exit 0
+fi
+
+# Read metadata.json
+METADATA_FILE="$INCREMENT_DIR/metadata.json"
+if [ ! -f "$METADATA_FILE" ]; then
+  echo "⚠️  $HOOK_NAME: No metadata.json found for $INCREMENT_ID" >&2
+  exit 0
+fi
+
+# Extract GitHub issue number
+ISSUE_NUMBER=$(jq -r '.github.issue // empty' "$METADATA_FILE" 2>/dev/null)
+
+if [ -z "$ISSUE_NUMBER" ] || [ "$ISSUE_NUMBER" = "null" ]; then
+  # No GitHub issue linked - skip GitHub closure but continue with sync
+  echo "ℹ️  No GitHub issue linked to increment $INCREMENT_ID"
+  SKIP_GITHUB_CLOSURE=true
+else
+  SKIP_GITHUB_CLOSURE=false
+fi
+
+# ============================================================================
+# GITHUB ISSUE CLOSURE (if linked)
+# ============================================================================
+
+if [ "$SKIP_GITHUB_CLOSURE" = "false" ]; then
+  # Check if gh CLI is available
+  if ! command -v gh &> /dev/null; then
+    echo "⚠️  $HOOK_NAME: GitHub CLI (gh) not found - skipping issue closure" >&2
+  else
+    # Check if issue is already closed
+    ISSUE_STATE=$(gh issue view "$ISSUE_NUMBER" --json state --jq '.state' 2>/dev/null || echo "")
+
+    if [ "$ISSUE_STATE" = "CLOSED" ]; then
+      echo "✓ GitHub issue #$ISSUE_NUMBER already closed"
+    else
+      # Close the GitHub issue with completion message
+      echo "🔗 Closing GitHub issue #$ISSUE_NUMBER for increment $INCREMENT_ID..."
+
+      # Create completion comment
+      COMPLETION_COMMENT="## ✅ Increment Complete
+
+Increment \`$INCREMENT_ID\` has been marked as complete.
+
+**Completion Details:**
+- Completed: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- All tasks completed
+- Tests passed
+- Documentation updated
+
+---
+🤖 Auto-closed by SpecWeave post-increment-completion hook"
+
+      # Close issue with comment
+      gh issue close "$ISSUE_NUMBER" --comment "$COMPLETION_COMMENT" 2>/dev/null || {
+        echo "⚠️  Failed to close issue #$ISSUE_NUMBER" >&2
+      }
+
+      echo "✅ GitHub issue #$ISSUE_NUMBER closed successfully"
+    fi
+  fi
+fi
+
+# Update status line cache (increment no longer open)
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
+# ============================================================================
+# SYNC LIVING DOCS (NEW in v0.24.0 - Critical Missing Feature)
+# ============================================================================
+# After increment completes, perform FULL living docs sync to ensure:
+# - Feature specs finalized with all user stories marked complete
+# - ADRs created/updated with final architecture decisions
+# - Architecture docs updated with implementation details
+# - Delivery docs updated with what was shipped
+# - Internal/public docs reflect completed work
+#
+# This is the FINAL, COMPREHENSIVE sync that happens once per increment.
+# (Task-level sync in post-task-completion.sh handles incremental updates)
+#
+# 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
+# - Failure mode: Graceful degradation (increment still completes)
+
+if command -v node &> /dev/null; then
+  echo ""
+  echo "📚 Performing final living docs sync for increment $INCREMENT_ID..."
+
+  # ========================================================================
+  # EXTRACT FEATURE ID (v0.23.0+)
+  # ========================================================================
+  # Extract epic field from spec.md frontmatter (e.g., epic: FS-047)
+  # This ensures sync uses the explicitly defined feature ID rather than
+  # auto-generating one, maintaining traceability with living docs structure.
+
+  FEATURE_ID=""
+  SPEC_MD_PATH="$INCREMENT_DIR/spec.md"
+
+  if [ -f "$SPEC_MD_PATH" ]; then
+    # Extract epic field from YAML frontmatter
+    FEATURE_ID=$(awk '
+      BEGIN { in_frontmatter=0 }
+      /^---$/ {
+        if (in_frontmatter == 0) {
+          in_frontmatter=1; next
+        } else {
+          exit
+        }
+      }
+      in_frontmatter == 1 && /^epic:/ {
+        gsub(/^epic:[ \t]*/, "");
+        gsub(/["'\'']/, "");
+        print;
+        exit
+      }
+    ' "$SPEC_MD_PATH" | tr -d '\r\n')
+
+    if [ -n "$FEATURE_ID" ]; then
+      echo "  📎 Using feature ID from spec.md: $FEATURE_ID"
+    else
+      echo "  ℹ️  No epic field found in spec.md - will auto-generate feature ID"
+    fi
+  else
+    echo "  ⚠️  spec.md not found at $SPEC_MD_PATH" >&2
+  fi
+
+  # ========================================================================
+  # EXTRACT PROJECT ID (v0.20.0+)
+  # ========================================================================
+  # Extract activeProject from config.json (defaults to "default")
+  # Supports multi-project mode where specs are organized by project.
+
+  PROJECT_ID="default"
+  CONFIG_PATH="$PROJECT_ROOT/.specweave/config.json"
+
+  if [ -f "$CONFIG_PATH" ]; then
+    if command -v jq >/dev/null 2>&1; then
+      ACTIVE_PROJECT=$(jq -r '.activeProject // "default"' "$CONFIG_PATH" 2>/dev/null || echo "default")
+      if [ -n "$ACTIVE_PROJECT" ] && [ "$ACTIVE_PROJECT" != "null" ]; then
+        PROJECT_ID="$ACTIVE_PROJECT"
+      fi
+    fi
+  fi
+  echo "  📁 Project ID: $PROJECT_ID"
+
+  # ========================================================================
+  # LOCATE SYNC SCRIPT
+  # ========================================================================
+  # Find sync-living-docs.js in order of preference:
+  # 1. In-place compiled (development, esbuild output)
+  # 2. Local dist (development, tsc output)
+  # 3. node_modules (installed as dependency)
+  # 4. Plugin marketplace (Claude Code global installation)
+
+  SYNC_SCRIPT=""
+  if [ -f "$PROJECT_ROOT/plugins/specweave/lib/hooks/sync-living-docs.js" ]; then
+    # Development: Use in-place compiled hooks (esbuild, not tsc)
+    SYNC_SCRIPT="$PROJECT_ROOT/plugins/specweave/lib/hooks/sync-living-docs.js"
+    echo "  🔧 Using in-place compiled hook (development mode)"
+  elif [ -f "$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/sync-living-docs.js" ]; then
+    # Development: Use project's compiled files (has node_modules)
+    SYNC_SCRIPT="$PROJECT_ROOT/dist/plugins/specweave/lib/hooks/sync-living-docs.js"
+    echo "  🔧 Using local dist (development mode)"
+  elif [ -f "$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/sync-living-docs.js" ]; then
+    # Installed as dependency: Use node_modules version
+    SYNC_SCRIPT="$PROJECT_ROOT/node_modules/specweave/dist/plugins/specweave/lib/hooks/sync-living-docs.js"
+    echo "  📦 Using node_modules version"
+  elif [ -n "${CLAUDE_PLUGIN_ROOT}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/lib/hooks/sync-living-docs.js" ]; then
+    # Fallback: Plugin marketplace (may fail if deps missing)
+    SYNC_SCRIPT="${CLAUDE_PLUGIN_ROOT}/lib/hooks/sync-living-docs.js"
+    echo "  🌐 Using plugin marketplace version"
+  fi
+
+  # ========================================================================
+  # EXECUTE SYNC
+  # ========================================================================
+  # Run living docs sync with feature ID and project ID
+  # Non-blocking: Errors logged but don't crash hook
+
+  if [ -n "$SYNC_SCRIPT" ]; 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
+      }
+    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
+      }
+    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 ""
+  fi
+else
+  echo "  ⚠️  Node.js not found - skipping living docs sync" >&2
+  echo "  💡 Install Node.js to enable automatic living docs sync" >&2
+  echo ""
+fi
+
+exit 0