specweave 1.0.43 → 1.0.46

package/CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- SW:META template="claude" version="1.0.41" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
+<!-- SW:META template="claude" version="1.0.44" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
 
-<!-- SW:SECTION:header version="1.0.41" -->
+<!-- SW:SECTION:header version="1.0.44" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
-<!-- SW:SECTION:start version="1.0.41" -->
+<!-- SW:SECTION:start version="1.0.44" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -14,7 +14,7 @@
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.41" -->
+<!-- SW:SECTION:autodetect version="1.0.44" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -24,7 +24,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.41" -->
+<!-- SW:SECTION:metarule version="1.0.44" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -35,7 +35,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.41" -->
+<!-- SW:SECTION:rules version="1.0.44" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
@@ -45,7 +45,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.41" -->
+<!-- SW:SECTION:workflow version="1.0.44" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -62,7 +62,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
 <!-- SW:END:workflow -->
 
-<!-- SW:SECTION:structure version="1.0.41" -->
+<!-- SW:SECTION:structure version="1.0.44" -->
 ## Structure
 
 ```
@@ -79,12 +79,12 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 
 **Multi-repo permissions**: In `.claude/settings.json`:
 ```json
-{"permissions":{"allow":["Write(**)","Edit(//**)"],"defaultMode":"bypassPermissions"}}
+{"permissions":{"allow":["Write(//**)","Edit(//**)"],"additionalDirectories":["repositories"],"defaultMode":"bypassPermissions"}}
 ```
-**Path syntax**: `//` = absolute path | `/` = relative to settings file | `**` = recursive
+**Path syntax**: `//path` = absolute | `/path` = relative to settings file | `**` = recursive | `additionalDirectories` = explicit working dirs
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.41" -->
+<!-- SW:SECTION:taskformat version="1.0.44" -->
 ## Task Format
 
 ```markdown
@@ -94,7 +94,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.41" -->
+<!-- SW:SECTION:secrets version="1.0.44" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -105,7 +105,7 @@ gh auth status
 ```
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.41" -->
+<!-- SW:SECTION:syncing version="1.0.44" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **After increment creation**: Run `/sw-github:sync {id}` to create issues!
@@ -124,7 +124,7 @@ Living docs sync ≠ External sync. They are separate:
 **Verify tokens**: `grep GITHUB_TOKEN .env` | `gh auth status`
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:mapping version="1.0.41" -->
+<!-- SW:SECTION:mapping version="1.0.44" -->
 ## GitHub Mapping
 
 | SpecWeave | GitHub |
@@ -134,7 +134,7 @@ Living docs sync ≠ External sync. They are separate:
 | Task T-XXX | Checkbox |
 <!-- SW:END:mapping -->
 
-<!-- SW:SECTION:testing version="1.0.41" -->
+<!-- SW:SECTION:testing version="1.0.44" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -146,13 +146,13 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:limits version="1.0.41" -->
+<!-- SW:SECTION:limits version="1.0.44" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.41" -->
+<!-- SW:SECTION:troubleshooting version="1.0.44" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -166,11 +166,11 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 | GitHub not syncing | Run `/sw-github:sync {id}` explicitly |
 | Permission denied | Set `canUpsertInternalItems: true` in config.json |
 | No GITHUB_TOKEN | Check `.env` file or run `gh auth login` |
-| Edits blocked in repositories/ | Add `Write(**)`, `Edit(//**)` to `.claude/settings.json` |
-| Path patterns not working | Claude Code: `//path` = absolute, `/path` = relative to settings file |
+| Edits blocked in repositories/ | Add `"additionalDirectories":["repositories"]` + `Write(//**)`, `Edit(//**)` to `.claude/settings.json` |
+| Path patterns not working | `//path` = absolute, `/path` = relative to settings file, `additionalDirectories` for explicit working dirs |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:principles version="1.0.41" -->
+<!-- SW:SECTION:principles version="1.0.44" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -180,7 +180,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 5. **Clean**: All files in increment folders
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.41" -->
+<!-- SW:SECTION:linking version="1.0.44" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -188,7 +188,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:docs version="1.0.41" -->
+<!-- SW:SECTION:docs version="1.0.44" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.43",
+  "version": "1.0.46",
   "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/hooks/lib/hook-errors.sh

@@ -0,0 +1,400 @@
+#!/bin/bash
+# hook-errors.sh - Centralized hook error logging and warning output
+#
+# PRINCIPLE: Hooks MUST NEVER block operations. All errors become warnings.
+#
+# Usage:
+#   source "$HOOK_DIR/lib/hook-errors.sh"
+#   log_hook_warning "task-ac-sync" "Pattern not found in spec.md"
+#   log_hook_error "metadata-guard" "JSON parse failed" "$details"
+#
+# Environment:
+#   SPECWEAVE_HOOK_VERBOSE=1 - Show all warnings to user
+#   SPECWEAVE_HOOK_DEBUG=1 - Log debug info to files
+#
+# All functions are non-blocking and always return 0
+
+set +e
+
+# ============================================================================
+# Configuration
+# ============================================================================
+
+HOOK_ERRORS_VERSION="1.0.0"
+
+# Find project root
+_find_hook_project_root() {
+  local dir="${1:-$PWD}"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.specweave" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir=$(dirname "$dir")
+  done
+  echo "$PWD"
+}
+
+_HOOK_PROJECT_ROOT=$(_find_hook_project_root)
+_HOOK_LOGS_DIR="$_HOOK_PROJECT_ROOT/.specweave/logs"
+_HOOK_STATE_DIR="$_HOOK_PROJECT_ROOT/.specweave/state"
+
+# Ensure directories exist
+mkdir -p "$_HOOK_LOGS_DIR" 2>/dev/null || true
+mkdir -p "$_HOOK_STATE_DIR" 2>/dev/null || true
+
+# Log files
+_HOOK_ERROR_LOG="$_HOOK_LOGS_DIR/hook-errors.log"
+_HOOK_WARNING_LOG="$_HOOK_LOGS_DIR/hook-warnings.log"
+_HOOK_DEBUG_LOG="$_HOOK_LOGS_DIR/hook-debug.log"
+
+# ============================================================================
+# Internal Helpers
+# ============================================================================
+
+_timestamp() {
+  date '+%Y-%m-%d %H:%M:%S'
+}
+
+_rotate_log_if_needed() {
+  local log_file="$1"
+  local max_size="${2:-1048576}"  # 1MB default
+
+  if [[ -f "$log_file" ]]; then
+    local size=$(stat -f%z "$log_file" 2>/dev/null || stat -c%s "$log_file" 2>/dev/null || echo 0)
+    if [[ "$size" -gt "$max_size" ]]; then
+      mv "$log_file" "${log_file}.old" 2>/dev/null || true
+    fi
+  fi
+}
+
+# ============================================================================
+# Public API: Logging Functions
+# ============================================================================
+
+# Log a warning - operation continues, user sees message if VERBOSE=1
+# Usage: log_hook_warning "hook-name" "message"
+log_hook_warning() {
+  local hook_name="${1:-unknown}"
+  local message="${2:-No message}"
+  local timestamp=$(_timestamp)
+
+  # Always log to file
+  echo "[$timestamp] WARNING [$hook_name]: $message" >> "$_HOOK_WARNING_LOG" 2>/dev/null || true
+
+  # Show to user if verbose mode
+  if [[ "${SPECWEAVE_HOOK_VERBOSE:-0}" == "1" ]]; then
+    echo ""
+    echo "  WARNING [$hook_name]: $message"
+    echo ""
+  fi
+
+  return 0
+}
+
+# Log an error - operation continues, but this is significant
+# Usage: log_hook_error "hook-name" "message" ["details"]
+log_hook_error() {
+  local hook_name="${1:-unknown}"
+  local message="${2:-No message}"
+  local details="${3:-}"
+  local timestamp=$(_timestamp)
+
+  # Rotate log if too large
+  _rotate_log_if_needed "$_HOOK_ERROR_LOG"
+
+  # Always log to file with details
+  {
+    echo "============================================================"
+    echo "[$timestamp] ERROR [$hook_name]"
+    echo "Message: $message"
+    if [[ -n "$details" ]]; then
+      echo "Details: $details"
+    fi
+    echo "============================================================"
+  } >> "$_HOOK_ERROR_LOG" 2>/dev/null || true
+
+  # Always show errors to user (they're significant)
+  echo ""
+  echo "  [Hook Warning] $hook_name: $message"
+  if [[ -n "$details" ]] && [[ "${SPECWEAVE_HOOK_DEBUG:-0}" == "1" ]]; then
+    echo "  Details: $details"
+  fi
+  echo "  (Operation continues - hook errors are non-blocking)"
+  echo ""
+
+  return 0
+}
+
+# Log debug info - only to file if DEBUG=1
+# Usage: log_hook_debug "hook-name" "message"
+log_hook_debug() {
+  local hook_name="${1:-unknown}"
+  local message="${2:-}"
+
+  if [[ "${SPECWEAVE_HOOK_DEBUG:-0}" == "1" ]]; then
+    local timestamp=$(_timestamp)
+    _rotate_log_if_needed "$_HOOK_DEBUG_LOG"
+    echo "[$timestamp] DEBUG [$hook_name]: $message" >> "$_HOOK_DEBUG_LOG" 2>/dev/null || true
+  fi
+
+  return 0
+}
+
+# Log hook start - for tracking which hooks ran
+# Usage: log_hook_start "hook-name" ["context"]
+log_hook_start() {
+  local hook_name="${1:-unknown}"
+  local context="${2:-}"
+
+  log_hook_debug "$hook_name" "START ${context:+- $context}"
+  return 0
+}
+
+# Log hook end - with success/failure status
+# Usage: log_hook_end "hook-name" "success|failure" ["message"]
+log_hook_end() {
+  local hook_name="${1:-unknown}"
+  local status="${2:-success}"
+  local message="${3:-}"
+
+  log_hook_debug "$hook_name" "END ($status) ${message:+- $message}"
+  return 0
+}
+
+# ============================================================================
+# Public API: Safe Execution Helpers
+# ============================================================================
+
+# Run a command safely, logging errors but never failing
+# Usage: safe_run "hook-name" command arg1 arg2...
+safe_run() {
+  local hook_name="${1:-unknown}"
+  shift
+
+  local output
+  local exit_code
+
+  output=$("$@" 2>&1)
+  exit_code=$?
+
+  if [[ $exit_code -ne 0 ]]; then
+    log_hook_warning "$hook_name" "Command failed (exit $exit_code): $*"
+    log_hook_debug "$hook_name" "Output: $output"
+  fi
+
+  return 0  # Always succeed
+}
+
+# Run a file modification safely with backup
+# Usage: safe_file_modify "hook-name" "file" "command with \$file placeholder"
+safe_file_modify() {
+  local hook_name="${1:-unknown}"
+  local file="$2"
+  local command="$3"
+
+  if [[ ! -f "$file" ]]; then
+    log_hook_warning "$hook_name" "File not found: $file"
+    return 0
+  fi
+
+  # Create backup
+  local backup="${file}.hook-backup"
+  cp "$file" "$backup" 2>/dev/null || {
+    log_hook_warning "$hook_name" "Failed to create backup of $file"
+    return 0
+  }
+
+  # Run command (replace $file placeholder)
+  local actual_command="${command//\$file/$file}"
+  if ! eval "$actual_command" 2>/dev/null; then
+    log_hook_warning "$hook_name" "Modification failed, restoring backup"
+    mv "$backup" "$file" 2>/dev/null || true
+    return 0
+  fi
+
+  # Verify file is valid (not empty, not truncated)
+  if [[ ! -s "$file" ]]; then
+    log_hook_error "$hook_name" "File became empty after modification, restoring"
+    mv "$backup" "$file" 2>/dev/null || true
+    return 0
+  fi
+
+  # Success - remove backup
+  rm -f "$backup" 2>/dev/null || true
+  return 0
+}
+
+# ============================================================================
+# Public API: Pattern Matching Helpers
+# ============================================================================
+
+# Check if a pattern exists in file (with logging)
+# Usage: if pattern_exists "hook-name" "file" "pattern"; then ...
+pattern_exists() {
+  local hook_name="${1:-unknown}"
+  local file="$2"
+  local pattern="$3"
+
+  if [[ ! -f "$file" ]]; then
+    log_hook_debug "$hook_name" "pattern_exists: file not found: $file"
+    return 1
+  fi
+
+  if grep -qE "$pattern" "$file" 2>/dev/null; then
+    log_hook_debug "$hook_name" "pattern_exists: found '$pattern' in $file"
+    return 0
+  else
+    log_hook_debug "$hook_name" "pattern_exists: NOT found '$pattern' in $file"
+    return 1
+  fi
+}
+
+# Safe sed replacement with pattern existence check
+# Usage: safe_sed_replace "hook-name" "file" "pattern" "replacement"
+safe_sed_replace() {
+  local hook_name="${1:-unknown}"
+  local file="$2"
+  local pattern="$3"
+  local replacement="$4"
+
+  if [[ ! -f "$file" ]]; then
+    log_hook_warning "$hook_name" "Cannot replace: file not found: $file"
+    return 0
+  fi
+
+  # Check if pattern exists first
+  if ! grep -qE "$pattern" "$file" 2>/dev/null; then
+    log_hook_debug "$hook_name" "Pattern not found (may already be updated): $pattern"
+    return 0  # Not an error - pattern may have been updated already
+  fi
+
+  # Try macOS sed first, then Linux
+  if sed -i '' "s|$pattern|$replacement|g" "$file" 2>/dev/null; then
+    log_hook_debug "$hook_name" "Replaced pattern (macOS sed)"
+    return 0
+  elif sed -i "s|$pattern|$replacement|g" "$file" 2>/dev/null; then
+    log_hook_debug "$hook_name" "Replaced pattern (Linux sed)"
+    return 0
+  else
+    log_hook_warning "$hook_name" "sed replacement failed for pattern: $pattern"
+    return 0  # Still don't fail
+  fi
+}
+
+# ============================================================================
+# Public API: JSON Helpers
+# ============================================================================
+
+# Safe JSON read with fallback
+# Usage: value=$(safe_json_get "hook-name" "file.json" ".key")
+safe_json_get() {
+  local hook_name="${1:-unknown}"
+  local file="$2"
+  local key="$3"
+  local default="${4:-}"
+
+  if [[ ! -f "$file" ]]; then
+    echo "$default"
+    return 0
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    log_hook_debug "$hook_name" "jq not available, returning default"
+    echo "$default"
+    return 0
+  fi
+
+  local value
+  value=$(jq -r "$key // empty" "$file" 2>/dev/null)
+
+  if [[ -z "$value" ]] || [[ "$value" == "null" ]]; then
+    echo "$default"
+  else
+    echo "$value"
+  fi
+
+  return 0
+}
+
+# Safe JSON update
+# Usage: safe_json_set "hook-name" "file.json" ".key" "value"
+safe_json_set() {
+  local hook_name="${1:-unknown}"
+  local file="$2"
+  local key="$3"
+  local value="$4"
+
+  if [[ ! -f "$file" ]]; then
+    log_hook_warning "$hook_name" "Cannot update JSON: file not found: $file"
+    return 0
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    log_hook_warning "$hook_name" "jq not available, skipping JSON update"
+    return 0
+  fi
+
+  local tmp_file
+  tmp_file=$(mktemp)
+
+  if jq "$key = $value" "$file" > "$tmp_file" 2>/dev/null && [[ -s "$tmp_file" ]]; then
+    mv "$tmp_file" "$file" 2>/dev/null || {
+      log_hook_warning "$hook_name" "Failed to write JSON update"
+      rm -f "$tmp_file"
+    }
+  else
+    log_hook_warning "$hook_name" "jq update failed for $key"
+    rm -f "$tmp_file"
+  fi
+
+  return 0
+}
+
+# ============================================================================
+# Public API: Output Helpers
+# ============================================================================
+
+# Output a visible warning banner to user
+# Usage: show_hook_warning_banner "title" "message line 1" "message line 2"
+show_hook_warning_banner() {
+  local title="$1"
+  shift
+
+  echo ""
+  echo "  WARNING: $title"
+  echo "  ----------------------------------------"
+  for line in "$@"; do
+    echo "  $line"
+  done
+  echo "  ----------------------------------------"
+  echo ""
+}
+
+# Output a non-blocking info message
+# Usage: show_hook_info "Operation completed with warnings"
+show_hook_info() {
+  local message="$1"
+  echo ""
+  echo "  [Info] $message"
+  echo ""
+}
+
+# ============================================================================
+# Initialization
+# ============================================================================
+
+# Export all functions for use in subshells
+export -f log_hook_warning 2>/dev/null || true
+export -f log_hook_error 2>/dev/null || true
+export -f log_hook_debug 2>/dev/null || true
+export -f log_hook_start 2>/dev/null || true
+export -f log_hook_end 2>/dev/null || true
+export -f safe_run 2>/dev/null || true
+export -f safe_file_modify 2>/dev/null || true
+export -f pattern_exists 2>/dev/null || true
+export -f safe_sed_replace 2>/dev/null || true
+export -f safe_json_get 2>/dev/null || true
+export -f safe_json_set 2>/dev/null || true
+export -f show_hook_warning_banner 2>/dev/null || true
+export -f show_hook_info 2>/dev/null || true