specweave 1.0.31 → 1.0.33

package/plugins/specweave/hooks/v2/guards/spec-validation-guard.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# spec-validation-guard.sh - Consolidated spec.md and living docs validation
+#
+# COMBINES (v0.35.4+):
+# - per-us-project-validator.sh (deleted) - Per-US **Project**: validation
+# - spec-project-validator.sh (deleted) - Placeholder detection
+# - project-folder-guard.sh (deleted) - Living docs folder validation
+#
+# Activation:
+# - tool_name: Write
+# - file_path matches: .specweave/increments/*/spec.md OR .specweave/docs/internal/specs/*/
+#
+# Exit 0 = allow (with JSON), Exit 2 = block (with JSON)
+#
+# Bypasses:
+# - SPECWEAVE_DISABLE_HOOKS=1 - Disable all hooks
+# - SPECWEAVE_FORCE_PROJECT=1 - Skip project validation
+# - SPECWEAVE_FORCE_METADATA=1 - Skip all spec validation
+
+set +e  # CRITICAL: Never use set -e in hooks
+
+# Source shared library if available
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="${SCRIPT_DIR}/../../lib"
+if [[ -f "$LIB_DIR/common-setup.sh" ]]; then
+  source "$LIB_DIR/common-setup.sh"
+  init_pretool_guard || exit 0
+else
+  # Fallback inline implementation
+  [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && echo '{"decision":"allow"}' && exit 0
+  HOOK_INPUT=$(cat 2>/dev/null || echo '{}')
+  if ! command -v jq >/dev/null 2>&1; then
+    echo '{"decision":"allow"}'
+    exit 0
+  fi
+  HOOK_TOOL_NAME=$(echo "$HOOK_INPUT" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+  HOOK_FILE_PATH=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // .file_path // ""' 2>/dev/null || echo "")
+  HOOK_CONTENT=$(echo "$HOOK_INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null || echo "")
+fi
+
+# Check bypass flags
+[[ "$SPECWEAVE_FORCE_PROJECT" == "1" ]] && echo '{"decision":"allow","message":"Project validation bypassed"}' && exit 0
+[[ "$SPECWEAVE_FORCE_METADATA" == "1" ]] && echo '{"decision":"allow","message":"Spec validation bypassed"}' && exit 0
+
+# Only validate Write tool
+[[ "$HOOK_TOOL_NAME" != "Write" ]] && echo '{"decision":"allow"}' && exit 0
+
+# No file path = allow
+[[ -z "$HOOK_FILE_PATH" ]] && echo '{"decision":"allow"}' && exit 0
+
+# ============================================================================
+# VALIDATION 1: spec.md placeholder detection
+# ============================================================================
+if [[ "$HOOK_FILE_PATH" =~ \.specweave/increments/[0-9]{3,4}E?-[^/]+/spec\.md$ ]]; then
+
+  # Check for unresolved {{...}} placeholders
+  if echo "$HOOK_CONTENT" | grep -qE '\{\{[A-Z_]+\}\}'; then
+    PLACEHOLDERS=$(echo "$HOOK_CONTENT" | grep -oE '\{\{[A-Z_]+\}\}' | sort -u | tr '\n' ', ' | sed 's/,$//')
+    printf '{"decision":"block","reason":"🚫 UNRESOLVED PLACEHOLDERS\\n\\nFound: %s\\n\\n🔧 FIX: Replace placeholders with actual values.\\nRun: specweave context projects\\nThen use values from the JSON output."}\n' "$PLACEHOLDERS"
+    exit 2
+  fi
+
+  # Check for **Project**: field in User Stories (soft validation - warn, don't block)
+  # Pattern: ### US-XXX or #### US-XXX followed by **Project**:
+  US_COUNT=$(echo "$HOOK_CONTENT" | grep -cE '^#{3,4} US-' 2>/dev/null || echo "0")
+  PROJECT_COUNT=$(echo "$HOOK_CONTENT" | grep -cE '^\*\*Project\*\*:' 2>/dev/null || echo "0")
+
+  # Trim to just the number
+  US_COUNT="${US_COUNT//[^0-9]/}"
+  PROJECT_COUNT="${PROJECT_COUNT//[^0-9]/}"
+  [[ -z "$US_COUNT" ]] && US_COUNT=0
+  [[ -z "$PROJECT_COUNT" ]] && PROJECT_COUNT=0
+
+  # Only warn if there are User Stories but no Project fields
+  # Don't block - just allow with warning
+  if [[ "$US_COUNT" -gt 0 ]] && [[ "$PROJECT_COUNT" -eq 0 ]]; then
+    echo '{"decision":"allow","message":"⚠️ WARNING: No **Project**: fields found. Add **Project**: after each US heading for proper sync."}'
+    exit 0
+  fi
+
+  # Check for comma-separated projects (forbidden - 1:1 mapping required)
+  if echo "$HOOK_CONTENT" | grep -qE '^\*\*Project\*\*:.*,'; then
+    printf '{"decision":"block","reason":"🚫 MULTIPLE PROJECTS IN ONE US\\n\\nEach User Story MUST map to exactly ONE project.\\n\\n🔧 FIX: Split cross-project features into separate User Stories:\\n\\nWRONG:\\n### US-001: OAuth Implementation\\n**Project**: frontend, backend\\n\\nCORRECT:\\n### US-001: OAuth Login Form\\n**Project**: frontend\\n\\n### US-002: OAuth API\\n**Project**: backend"}\n'
+    exit 2
+  fi
+
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# ============================================================================
+# VALIDATION 2: Living docs folder validation
+# ============================================================================
+if [[ "$HOOK_FILE_PATH" =~ \.specweave/docs/internal/specs/([^/]+)/ ]]; then
+  PROJECT_NAME="${BASH_REMATCH[1]}"
+
+  # Skip README.md and _features/_archive special folders
+  [[ "$PROJECT_NAME" == "README.md" ]] && echo '{"decision":"allow"}' && exit 0
+  [[ "$PROJECT_NAME" == "_features" ]] && echo '{"decision":"allow"}' && exit 0
+  [[ "$PROJECT_NAME" == "_archive" ]] && echo '{"decision":"allow"}' && exit 0
+
+  # Check for template placeholders
+  if [[ "$PROJECT_NAME" =~ \{\{.*\}\} ]]; then
+    printf '{"decision":"block","reason":"🚫 UNRESOLVED PLACEHOLDER: %s\\n\\n🔧 FIX: Replace {{...}} with actual project name"}\n' "$PROJECT_NAME"
+    exit 2
+  fi
+
+  # Check for comma-separated (invalid)
+  if [[ "$PROJECT_NAME" =~ , ]]; then
+    printf '{"decision":"block","reason":"🚫 COMMA-SEPARATED PROJECTS: %s\\n\\nEach User Story = ONE project folder.\\n\\n🔧 FIX: Split into separate specs"}\n' "$PROJECT_NAME"
+    exit 2
+  fi
+
+  # Check for common example/placeholder names
+  EXAMPLE_NAMES="frontend-app|backend-api|mobile-app|shared-lib|acme-corp|my-app|myapp|example-project|test-project"
+  if [[ "$PROJECT_NAME" =~ ^($EXAMPLE_NAMES)$ ]]; then
+    # Try to get valid projects from config
+    PROJECT_ROOT="${HOOK_FILE_PATH%%/.specweave/*}"
+    CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
+
+    if [[ -f "$CONFIG_FILE" ]]; then
+      # Check if this example name is actually configured
+      IS_CONFIGURED=$(jq -r --arg name "$PROJECT_NAME" '.multiProject.projects[$name] // .project.name == $name' "$CONFIG_FILE" 2>/dev/null || echo "false")
+
+      if [[ "$IS_CONFIGURED" != "true" ]]; then
+        VALID_PROJECTS=$(jq -r '.multiProject.projects | keys | join(", ") // .project.name // "specweave"' "$CONFIG_FILE" 2>/dev/null || echo "specweave")
+        printf '{"decision":"block","reason":"🚫 EXAMPLE PROJECT NAME: %s\\n\\nThis looks like a placeholder/example name from documentation.\\n\\nConfigured projects: %s\\n\\n🔧 FIX: Edit spec.md and use a real project name"}\n' "$PROJECT_NAME" "$VALID_PROJECTS"
+        exit 2
+      fi
+    fi
+  fi
+
+  echo '{"decision":"allow"}'
+  exit 0
+fi
+
+# Not a spec.md or living docs file - allow
+echo '{"decision":"allow"}'
+exit 0

package/plugins/specweave/hooks/v2/guards/task-ac-sync-guard.sh

@@ -17,6 +17,8 @@
 # - Supports both - and * bullet formats
 #
 # CRITICAL: This hook must be NON-BLOCKING to prevent Claude Code crashes
+# PostToolUse hooks run AFTER the tool completes, so they don't need JSON responses.
+# However, they must NEVER crash or hang.
 set +e
 
 [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
@@ -43,8 +45,8 @@ LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
 DEBUG_LOG="$LOGS_DIR/task-ac-sync.log"
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
-# Read stdin for tool input
-INPUT=$(cat)
+# Read stdin for tool input (with safe fallback to prevent hanging)
+INPUT=$(cat 2>/dev/null || echo '{}')
 
 # Extract file_path from tool input
 FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"/\1/')

package/plugins/specweave/hooks/v2/session-end.sh

@@ -4,8 +4,10 @@
 #
 # Triggered: When Claude Code session ends normally
 # Purpose: Clean up session registry and child processes
+#
+# v0.35.3 - Fixed: use set +e for hook safety
 
-set -euo pipefail
+set +e  # CRITICAL: Never use set -e in hooks (causes cascading failures)
 
 PROJECT_ROOT="${PWD}"
 LOG_DIR="${PROJECT_ROOT}/.specweave/logs/sessions"

package/plugins/specweave/hooks/v2/session-start.sh

@@ -4,8 +4,10 @@
 #
 # Triggered: When Claude Code session starts
 # Purpose: Track session for zombie prevention
+#
+# v0.35.3 - Fixed: use set +e for hook safety
 
-set -euo pipefail
+set +e  # CRITICAL: Never use set -e in hooks (causes cascading failures)
 
 PROJECT_ROOT="${PWD}"
 SESSION_ID="session-$$-$(date +%s)"

package/plugins/specweave/skills/increment-planner/templates/plan.md

@@ -48,3 +48,17 @@
 ### Challenge 1: [Description]
 **Solution**: [Approach]
 **Risk**: [Mitigation]
+
+## Recommended Agents
+
+> **Tip**: Use specialized agents for domain expertise. See `plugins/PLUGINS-INDEX.md` for full catalog.
+
+| Domain | Agent | When to Use |
+|--------|-------|-------------|
+| Architecture | `specweave:architect:architect` | System design, ADRs |
+| Frontend | `specweave-frontend:frontend-architect:frontend-architect` | React/Vue/Next.js |
+| Backend | `specweave-backend:database-optimizer:database-optimizer` | API, database |
+| K8s | `specweave-kubernetes:kubernetes-architect:kubernetes-architect` | Manifests, GitOps |
+| Infra | `specweave-infrastructure:devops:devops` | Terraform, CI/CD |
+| Testing | `specweave-testing:qa-engineer:qa-engineer` | E2E, test strategy |
+| Security | `specweave:security:security` | Security review |

package/plugins/specweave/skills/update-instructions/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: update-instructions
+description: Update CLAUDE.md and AGENTS.md instruction files with smart merge. Preserves user customizations while updating SpecWeave sections. Use after plugin refresh, version upgrade, or when instruction files need sync. Activates for: update instructions, refresh claude.md, merge agents.md, sync instruction files, upgrade specweave config.
+---
+
+# Update Instructions Skill
+
+Smart merge for CLAUDE.md and AGENTS.md instruction files.
+
+## What It Does
+
+1. **Reads existing instruction files** (if present)
+2. **Parses SW-managed sections** (marked with `<!-- SW:SECTION:X -->`)
+3. **Preserves user content** (anything between or after SW sections)
+4. **Updates SW sections** with latest template content
+5. **Writes merged result** back to file
+
+## When to Use
+
+- After running `bash scripts/refresh-marketplace.sh`
+- After upgrading SpecWeave version (`npm update specweave`)
+- When CLAUDE.md or AGENTS.md seem outdated
+- To sync instruction files with latest framework features
+
+## Usage
+
+```
+/sw:update-instructions
+```
+
+Or via CLI:
+```bash
+npx specweave update-instructions
+```
+
+## How Merge Works
+
+### Fresh Install (no existing file)
+Creates new file with all SW sections + meta header
+
+### Legacy File (no SW markers)
+Prepends new SW content, preserves original below separator
+
+### Marked File (has SW markers)
+Updates SW sections in-place, preserves user content between sections
+
+## Section Format
+
+Template sections (in `.template` files):
+```markdown
+<!-- SECTION:rules required -->
+## Rules
+Content here...
+<!-- /SECTION -->
+```
+
+Generated sections (in output files):
+```markdown
+<!-- SW:META template="claude" version="1.0.0" sections="header,rules,..." -->
+
+<!-- SW:SECTION:header version="1.0.0" -->
+Content...
+<!-- SW:END:header -->
+```
+
+## User Customization
+
+Add custom content **between** SW sections or **after** the last section:
+```markdown
+<!-- SW:END:docs -->
+
+## My Custom Section
+
+This will be preserved during updates!
+```
+
+## Files Affected
+
+- `CLAUDE.md` - Claude Code instruction file
+- `AGENTS.md` - Generic AI tool instruction file

package/plugins/specweave-ado/hooks/post-living-docs-update.sh

@@ -327,7 +327,7 @@ main() {
 
     if [ -z "$spec_path" ]; then
         log_error "No spec path provided"
-        exit 1
+        exit 0  # SAFETY: Never use exit 1 in hooks - causes Claude Code failures
     fi
 
     # Detect external tool

package/plugins/specweave-mobile/README.md

@@ -1,45 +1,54 @@
 # SpecWeave Mobile Plugin
 
-Comprehensive React Native and Expo development support for SpecWeave. Streamlines mobile app development with expert guidance on setup, debugging, performance optimization, and testing.
+Comprehensive **React Native 0.83+** and **Expo SDK 54+** development support for SpecWeave. Streamlines mobile app development with expert guidance on setup, debugging, performance optimization, and testing.
 
 ## Overview
 
-The SpecWeave Mobile plugin provides specialized skills and agents for React Native and Expo development, covering the entire mobile development lifecycle from environment setup to production deployment.
+The SpecWeave Mobile plugin provides specialized skills and agents for modern React Native and Expo development, covering the entire mobile development lifecycle from environment setup to production deployment.
+
+### What's New (December 2025)
+
+- **React Native 0.83**: Zero breaking changes, React 19.2, Activity component, useEffectEvent
+- **Expo SDK 54**: Native tabs, iOS Liquid Glass, Android edge-to-edge, expo-video/expo-audio
+- **Hermes V1**: Next-generation JavaScript engine (experimental)
+- **New Architecture**: Default since RN 0.76 - Turbo Modules, Fabric, JSI
+- **Web APIs**: Intersection Observer (Canary), Web Performance APIs (Stable)
 
 ## Features
 
 ### 7 Specialized Skills
 
-1. **react-native-setup** - Environment setup and configuration
-   - Node.js, Xcode, Android Studio installation
-   - iOS simulators and Android emulators setup
-   - CocoaPods, watchman, SDK configuration
-   - Troubleshooting common setup issues
+1. **react-native-setup** - Environment setup and configuration (2025)
+   - Node.js 20+, Xcode 16.1+, Android Studio Ladybug
+   - iOS simulators (iOS 26 for Liquid Glass) and Android emulators (API 35)
+   - CocoaPods 1.15+, watchman, EAS Build setup
+   - New Architecture setup and troubleshooting
 
-2. **expo-workflow** - Expo development workflows
+2. **expo-workflow** - Expo SDK 54+ development workflows
    - EAS Build and EAS Update
-   - Expo Go vs Development Builds
-   - OTA updates and deployment
-   - app.json and eas.json configuration
+   - Native tab navigation and Expo Router v6
+   - iOS Liquid Glass and Android edge-to-edge
+   - expo-video/expo-audio (replacing expo-av)
 
 3. **mobile-debugging** - Debugging strategies
-   - React DevTools, Flipper, Chrome DevTools
+   - React DevTools Desktop App (RN 0.83)
+   - Flipper, Chrome DevTools
    - Network request debugging
    - Error boundaries and crash analysis
-   - Platform-specific debugging
 
-4. **performance-optimization** - Performance tuning
-   - Bundle size reduction
-   - FlatList optimization
-   - Image optimization
-   - Memory leak prevention
-   - Animation performance
+4. **performance-optimization** - Modern performance tuning
+   - Hermes V1 experimental engine
+   - React 19.2 Activity component for state preservation
+   - Intersection Observer API for lazy loading
+   - Web Performance APIs (performance.now, User Timing)
+   - FlashList, expo-image v2
 
-5. **native-modules** - Native module integration
-   - Third-party native module installation
-   - Custom native module development
-   - iOS (Swift/Objective-C) and Android (Kotlin/Java)
-   - Turbo Modules and JSI
+5. **native-modules** - New Architecture native integration
+   - Turbo Modules with Codegen
+   - Fabric components
+   - JSI for synchronous calls
+   - Expo config plugins
+   - Interop layer for legacy Bridge modules
 
 6. **device-testing** - Testing strategies
    - Jest unit and integration testing
@@ -53,18 +62,18 @@ The SpecWeave Mobile plugin provides specialized skills and agents for React Nat
    - Bundle size analysis
    - Cache management
    - Monorepo configuration
-   - Performance optimization
+   - Hermes bytecode optimization
 
 ### Mobile Architect Agent
 
 The `mobile-architect` agent specializes in:
-- Application architecture design
-- State management selection (Redux, Zustand, MobX, React Query)
-- Navigation patterns and deep linking
-- Performance architecture
-- Platform-specific strategies
+- Application architecture design for RN 0.83+ / Expo SDK 54+
+- State management selection (Zustand, TanStack Query v5, Jotai, Legend State)
+- Navigation with Expo Router v6 and React Navigation v7
+- Performance architecture with React 19.2 features
+- Platform-specific strategies (iOS Liquid Glass, Android edge-to-edge)
 - Testing architecture
-- Build and deployment pipelines
+- Build and deployment pipelines with EAS
 
 ## Installation
 
@@ -284,11 +293,13 @@ React Navigation with:
 
 ## Pro Tips
 
-1. **Fast Device Testing**: Use real devices with Expo Go for quickest iteration
-2. **Performance**: Enable Hermes for faster startup and smaller bundles
-3. **Debugging**: Use Flipper for network and layout debugging
+1. **Fast Device Testing**: Use development builds with EAS for custom native code
+2. **Performance**: Enable Hermes V1 (experimental) for faster startup and smaller bundles
+3. **Debugging**: Use the new React DevTools Desktop App (RN 0.83)
 4. **Testing**: Start with React Native Testing Library, add Detox for critical paths
-5. **Optimization**: Profile before optimizing - use React DevTools Profiler
+5. **Optimization**: Use Web Performance APIs (performance.now, User Timing) for profiling
+6. **iOS**: Target iOS 26+ for Liquid Glass effects
+7. **Android**: Use API 35 with edge-to-edge for modern UI
 
 ## Troubleshooting
 
@@ -316,6 +327,15 @@ To add new skills or improve existing ones:
 
 ## Version History
 
+- **2.0.0** (December 2025)
+  - React Native 0.83 support (React 19.2, Activity component, useEffectEvent)
+  - Expo SDK 54 support (native tabs, Liquid Glass, edge-to-edge)
+  - Hermes V1 experimental engine support
+  - Turbo Modules with Codegen documentation
+  - Intersection Observer and Web Performance APIs
+  - expo-video/expo-audio (replacing expo-av)
+  - Updated all skills with 2025 requirements
+
 - **1.0.0** (November 2024)
   - Initial release
   - 7 specialized skills