specweave 0.28.1 → 0.28.5

package/dist/src/utils/auth-helpers.js

@@ -10,6 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'js-yaml';
+import { execSync } from 'child_process';
 /**
  * Get GitHub authentication token
  * Priority: GITHUB_TOKEN (CI) > GH_TOKEN (custom) > gh CLI config (local)
@@ -23,7 +24,18 @@ export function getGitHubAuth() {
     if (process.env.GH_TOKEN) {
         return { token: process.env.GH_TOKEN, source: 'GH_TOKEN' };
     }
-    // 3. Try to parse gh CLI config (~/.config/gh/hosts.yml)
+    // 3. Try to get token via gh CLI command (works with Keychain, plain-text, etc.)
+    try {
+        const token = execSync('gh auth token', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (token && token.length > 0) {
+            return { token, source: 'gh-cli' };
+        }
+    }
+    catch (error) {
+        // gh CLI not installed or not authenticated - silently fail
+    }
+    // 4. Fallback: Try to parse gh CLI config directly (~/.config/gh/hosts.yml)
+    // This covers edge cases where gh CLI isn't available but config file exists
     try {
         const ghConfigPath = path.join(os.homedir(), '.config', 'gh', 'hosts.yml');
         if (fs.existsSync(ghConfigPath)) {

package/dist/src/utils/auth-helpers.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.28.1",
+  "version": "0.28.5",
   "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",

package/plugins/specweave/commands/specweave-validate-features.md

@@ -0,0 +1,203 @@
+---
+name: specweave:validate-features
+description: Validate feature folder consistency between _features/ and project folders. Detects orphaned features and auto-repairs discrepancies. Use when features appear in _features but not in project folders.
+---
+
+# Validate Feature Folder Consistency
+
+Validates that features in `_features/` have corresponding project folders (e.g., `specweave/FS-XXX/`).
+
+---
+
+## STEP 1: Parse Arguments
+
+```
+Arguments: [user's arguments]
+```
+
+**Options**:
+- `--repair`: Auto-repair discrepancies (create missing project folders)
+- `--dry-run`: Show what would be repaired without making changes
+
+---
+
+## STEP 2: Run Consistency Validation
+
+**Execute**:
+
+```typescript
+import { FeatureConsistencyValidator } from './dist/src/core/living-docs/feature-consistency-validator.js';
+
+const validator = new FeatureConsistencyValidator(process.cwd(), {
+  defaultProject: 'specweave'
+});
+
+// Parse repair flag
+const autoRepair = process.argv.includes('--repair');
+const dryRun = process.argv.includes('--dry-run');
+
+if (dryRun) {
+  console.log('🔍 DRY RUN MODE - No files will be modified\n');
+}
+
+// Run validation
+const result = await validator.validate(autoRepair && !dryRun);
+```
+
+---
+
+## STEP 3: Report Results
+
+**Output format**:
+
+```
+═══════════════════════════════════════════════════════
+📊 FEATURE CONSISTENCY VALIDATION REPORT
+═══════════════════════════════════════════════════════
+
+Total features scanned: {total}
+Consistent: {consistent}
+Discrepancies found: {discrepancies}
+
+───────────────────────────────────────────────────────
+{if discrepancies > 0}
+⚠️  DISCREPANCIES FOUND
+
+{for each discrepancy}
+Feature: {featureId}
+Type: {type}
+Description: {description}
+Auto-repairable: {yes/no}
+{if linkedIncrement}
+Linked increment: {incrementId} ({exists/not found})
+{/if}
+
+{/for}
+───────────────────────────────────────────────────────
+{/if}
+
+{if repairs}
+🔧 REPAIR RESULTS
+
+{for each repair}
+{✅/❌} {featureId}: {action}
+{if error}   Error: {error}{/if}
+{/for}
+{/if}
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## STEP 4: Provide Next Steps
+
+```
+🎯 NEXT STEPS
+───────────────────────────────────────────────────────
+
+{if discrepancies > 0 && !repair}
+To auto-repair these discrepancies:
+  /specweave:validate-features --repair
+
+This will:
+  • Create missing project folders
+  • Generate README.md files
+  • Link to existing FEATURE.md
+{/if}
+
+{if all repaired}
+✅ All discrepancies have been repaired!
+
+Verify the repairs:
+  ls -la .specweave/docs/internal/specs/specweave/
+{/if}
+
+{if orphaned features}
+⚠️  Some features could not be auto-repaired.
+
+Manual intervention required for:
+{list orphaned features}
+
+Options:
+  1. Delete orphaned _features folder if no longer needed
+  2. Re-sync from increment if increment still exists
+  3. Create project folder manually
+{/if}
+```
+
+---
+
+## EXAMPLES
+
+### Example 1: Check for discrepancies
+```
+User: /specweave:validate-features
+
+Output:
+═══════════════════════════════════════════════════════
+📊 FEATURE CONSISTENCY VALIDATION REPORT
+═══════════════════════════════════════════════════════
+
+Total features scanned: 7
+Consistent: 6
+Discrepancies found: 1
+
+───────────────────────────────────────────────────────
+⚠️  DISCREPANCIES FOUND
+
+Feature: FS-062
+Type: missing_project_folder
+Description: Feature FS-062 exists in _features/ but not in any project folder
+Auto-repairable: Yes
+Linked increment: 0062-test-living-docs-auto-sync (not found)
+
+───────────────────────────────────────────────────────
+
+🎯 To repair: /specweave:validate-features --repair
+═══════════════════════════════════════════════════════
+```
+
+### Example 2: Auto-repair discrepancies
+```
+User: /specweave:validate-features --repair
+
+Output:
+═══════════════════════════════════════════════════════
+📊 FEATURE CONSISTENCY VALIDATION REPORT
+═══════════════════════════════════════════════════════
+
+Total features scanned: 7
+Consistent: 7
+Discrepancies found: 1
+
+───────────────────────────────────────────────────────
+🔧 REPAIR RESULTS
+
+✅ FS-062: Created .specweave/docs/internal/specs/specweave/FS-062/README.md
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## WHEN TO USE
+
+**Use this command when**:
+- Features appear in `_features/` but not in project folders
+- After interrupted/failed sync operations
+- After manual cleanup of increments
+- Periodic health check of living docs structure
+
+**Root cause of discrepancies**:
+1. Sync interrupted between creating _features and project folders
+2. Increment deleted without cleaning up living docs
+3. Manual editing of living docs structure
+
+---
+
+## RELATED COMMANDS
+
+- `/specweave:sync-specs` - Sync increment to living docs (includes consistency check)
+- `/specweave:validate` - Validate increment structure
+- `/specweave:archive` - Archive completed increments

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/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/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