specweave 0.26.5 → 0.26.9

package/plugins/specweave/commands/sync-diagnostics.md

@@ -0,0 +1,227 @@
+---
+name: sync-diagnostics
+description: Show sync circuit breaker diagnostics and status
+---
+
+You are executing the SpecWeave sync diagnostics command. This shows the current state of the sync circuit breaker and recent sync activity.
+
+## Purpose
+
+Display diagnostic information about automatic sync system:
+- Circuit breaker state (closed, open, half-open)
+- Recent failure count
+- Last failure timestamp
+- Auto-reset countdown (if circuit open)
+- Sync status for active increments
+
+## Implementation
+
+```typescript
+import { StatusChangeSyncTrigger } from '../../../src/core/increment/status-change-sync-trigger.js';
+import { ActiveIncrementManager } from '../../../src/core/increment/active-increment-manager.js';
+import { MetadataManager } from '../../../src/core/increment/metadata-manager.js';
+import * as path from 'path';
+
+// Get circuit breaker state
+const breakerState = StatusChangeSyncTrigger.getCircuitBreakerState();
+
+console.log('');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('🔧 SYNC DIAGNOSTICS');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('');
+
+// Circuit Breaker Status
+console.log('🔴 Circuit Breaker Status');
+console.log('');
+
+const stateEmoji = {
+  'closed': '✅',
+  'open': '🔴',
+  'half-open': '⚠️'
+};
+
+console.log(`   State: ${stateEmoji[breakerState.state]} ${breakerState.state.toUpperCase()}`);
+console.log(`   Failures: ${breakerState.failures}/3`);
+
+if (breakerState.lastFailure) {
+  const elapsed = Date.now() - breakerState.lastFailure.getTime();
+  const elapsedMin = Math.floor(elapsed / 60000);
+  const resetIn = Math.max(0, 5 - elapsedMin);
+
+  console.log(`   Last Failure: ${breakerState.lastFailure.toISOString()}`);
+  console.log(`   Elapsed: ${elapsedMin} minutes ago`);
+
+  if (breakerState.state === 'open') {
+    console.log(`   ⏰ Auto-reset in: ${resetIn} minutes`);
+  }
+} else {
+  console.log(`   Last Failure: None`);
+}
+
+console.log('');
+
+// Sync Status Explanation
+if (breakerState.state === 'closed') {
+  console.log('✅ Automatic sync is ENABLED');
+  console.log('   Status changes will trigger GitHub/JIRA/ADO sync');
+} else if (breakerState.state === 'open') {
+  console.log('🔴 Automatic sync is DISABLED');
+  console.log('   Circuit breaker opened due to repeated failures');
+  console.log('');
+  console.log('   Possible causes:');
+  console.log('   • GitHub/JIRA/ADO API is down or slow');
+  console.log('   • Network connectivity issues');
+  console.log('   • Authentication token expired');
+  console.log('   • Rate limit exceeded');
+  console.log('');
+  console.log('   Actions:');
+  console.log('   1. Check external service status');
+  console.log('   2. Verify network connectivity');
+  console.log('   3. Wait for auto-reset (${resetIn} minutes)');
+  console.log('   4. Or manually sync: /specweave:sync-progress');
+} else if (breakerState.state === 'half-open') {
+  console.log('⚠️  Automatic sync is TESTING');
+  console.log('   Circuit breaker is testing if service recovered');
+  console.log('   Next sync will close or reopen circuit');
+}
+
+console.log('');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('📊 ACTIVE INCREMENTS');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('');
+
+// Show active increments
+const activeManager = new ActiveIncrementManager();
+const activeIncrements = activeManager.getActiveIncrements();
+
+if (activeIncrements.length === 0) {
+  console.log('   ℹ️  No active increments');
+} else {
+  for (const incrementId of activeIncrements) {
+    try {
+      const metadata = MetadataManager.read(incrementId);
+      console.log(`   📦 ${incrementId}`);
+      console.log(`      Status: ${metadata.status}`);
+      console.log(`      Last Activity: ${metadata.lastActivity || 'Unknown'}`);
+
+      // Show sync status
+      if (metadata.external_tools?.github) {
+        console.log(`      🔗 GitHub: Synced`);
+      }
+      if (metadata.external_tools?.jira) {
+        console.log(`      🔗 JIRA: Synced`);
+      }
+      if (metadata.external_tools?.ado) {
+        console.log(`      🔗 Azure DevOps: Synced`);
+      }
+
+      console.log('');
+    } catch (err) {
+      console.log(`   ⚠️  ${incrementId}: Error reading metadata`);
+    }
+  }
+}
+
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('');
+console.log('💡 Troubleshooting:');
+console.log('');
+console.log('   • Manual sync: /specweave:sync-progress [increment-id]');
+console.log('   • Reset circuit: (automatic after 5 minutes)');
+console.log('   • Check logs: .specweave/logs/');
+console.log('   • GitHub status: https://www.githubstatus.com/');
+console.log('');
+```
+
+## Example Output
+
+### Circuit Closed (Normal)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 SYNC DIAGNOSTICS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 Circuit Breaker Status
+
+   State: ✅ CLOSED
+   Failures: 0/3
+   Last Failure: None
+
+✅ Automatic sync is ENABLED
+   Status changes will trigger GitHub/JIRA/ADO sync
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 ACTIVE INCREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   📦 0058-fix-status-sync-and-auto-github-update
+      Status: active
+      Last Activity: 2025-11-24T12:34:56.789Z
+      🔗 GitHub: Synced
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Circuit Open (Failure Mode)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔧 SYNC DIAGNOSTICS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 Circuit Breaker Status
+
+   State: 🔴 OPEN
+   Failures: 3/3
+   Last Failure: 2025-11-24T12:30:00.000Z
+   Elapsed: 3 minutes ago
+   ⏰ Auto-reset in: 2 minutes
+
+🔴 Automatic sync is DISABLED
+   Circuit breaker opened due to repeated failures
+
+   Possible causes:
+   • GitHub/JIRA/ADO API is down or slow
+   • Network connectivity issues
+   • Authentication token expired
+   • Rate limit exceeded
+
+   Actions:
+   1. Check external service status
+   2. Verify network connectivity
+   3. Wait for auto-reset (2 minutes)
+   4. Or manually sync: /specweave:sync-progress
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Use Cases
+
+### 1. Check Sync Health
+
+```bash
+/specweave:sync-diagnostics
+```
+
+Quickly see if automatic sync is working or if circuit breaker opened.
+
+### 2. Troubleshoot Sync Failures
+
+When sync isn't working, diagnostics shows:
+- How many failures occurred
+- When last failure happened
+- How long until auto-reset
+- What to check next
+
+### 3. Monitor Active Increments
+
+See which increments are active and synced to external tools.
+
+## See Also
+
+- `/specweave:sync-progress` - Manual sync command
+- ADR-0070 (Hook Consolidation)
+- Circuit Breaker Pattern Documentation

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