specweave 0.33.2 → 0.33.4

package/plugins/specweave/commands/specweave-increment.md

@@ -364,6 +364,52 @@ Proceeding with hotfix 0006...
 - Hotfixes and bugs bypass context switching warnings (emergency work)
 - Use sparingly - discipline exists for a reason!
 
+### Step 0D: Get Project Context (MANDATORY - RUN FIRST!)
+
+**⛔ THIS STEP MUST BE COMPLETED BEFORE ANY SPEC GENERATION!**
+
+**🚨 YOU MUST USE THE BASH TOOL TO RUN THIS COMMAND:**
+
+```bash
+specweave context projects
+```
+
+**CAPTURE THE OUTPUT AND STORE IT:**
+
+```json
+// Example 1-level output:
+{
+  "level": 1,
+  "projects": [{"id": "frontend-app"}, {"id": "backend-api"}, {"id": "shared"}]
+}
+
+// Example 2-level output:
+{
+  "level": 2,
+  "projects": [{"id": "acme-corp"}],
+  "boardsByProject": {
+    "acme-corp": [{"id": "digital-ops"}, {"id": "mobile-team"}]
+  }
+}
+```
+
+**STORE THESE VALUES FOR USE IN STEP 5:**
+```
+STRUCTURE_LEVEL = 1 or 2
+AVAILABLE_PROJECTS = ["frontend-app", "backend-api", "shared"]
+AVAILABLE_BOARDS = {...}  // for 2-level only
+```
+
+**WHY THIS IS MANDATORY:**
+- Without this data, spec.md will have `{{PROJECT_ID}}` placeholders
+- Placeholders WILL BE BLOCKED by `spec-project-validator.sh` hook
+- Living docs sync and external tool sync WILL FAIL
+- User will get frustrated with blocked edits
+
+**YOU MUST ACTUALLY RUN THE COMMAND** - reading documentation about it is NOT enough!
+
+---
+
 ### Step 1: Find next increment number
 
 - Scan `.specweave/increments/` directory (active increments)

package/plugins/specweave/commands/specweave-jobs.md

@@ -1,7 +1,7 @@
 ---
 name: specweave:jobs
 description: Show current work status (active increments, progress) and background jobs (imports, cloning). Even with no jobs, shows increment summary and helpful context.
-usage: /specweave:jobs [--all] [--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>]
+usage: /specweave:jobs [--all] [--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>] [--diagnostics]
 ---
 
 # Background Jobs Monitor
@@ -17,6 +17,7 @@ Monitor and manage long-running background operations:
 - **Issue import** (10K+ items from GitHub/JIRA/ADO)
 - **External sync** operations
 - **Brownfield analysis** (codebase documentation gap detection)
+- **Session health monitoring** (watchdog diagnostics)
 
 **ASYNC ARCHITECTURE (2025-12-01)**:
 - Jobs run as **detached processes** that survive terminal close
@@ -29,13 +30,14 @@ Monitor and manage long-running background operations:
 
 | Option | Description |
 |--------|-------------|
-| (none) | Show active jobs |
+| (none) | Show active jobs + session health |
 | `--all` | Show all jobs (including completed) |
 | `--id <jobId>` | Show details for specific job |
 | `--follow <jobId>` | Follow job progress in real-time |
 | `--logs <jobId>` | Show worker log output |
 | `--resume <jobId>` | Resume paused job |
 | `--kill <jobId>` | Kill running background job |
+| `--diagnostics` | Show detailed watchdog diagnostics |
 
 ---
 
@@ -57,7 +59,9 @@ STATE_FILE=".specweave/state/background-jobs.json"
 ### Display Format
 
 ```
-📋 Background Jobs
+📋 Background Jobs & Session Health
+
+🩺 Session Health: ✅ healthy (last check: 30s ago)
 
 🔄 Running (2):
   [abc12345] import-issues (ADO)
@@ -87,6 +91,7 @@ STATE_FILE=".specweave/state/background-jobs.json"
    /specweave:jobs --logs abc12345   → View worker logs
    /specweave:jobs --resume def67890 → Resume paused job
    /specweave:jobs --kill abc12345   → Kill running job
+   /specweave:jobs --diagnostics     → Show watchdog diagnostics
    /specweave:jobs --all             → Show all jobs (including old)
 ```
 
@@ -221,14 +226,57 @@ const result = await launchImportJob({
 ## Implementation
 
 1. Read `.specweave/state/background-jobs.json`
-2. Parse job entries
-3. Display formatted status
-4. For --resume, update job status and continue operation
+2. Read `.specweave/state/.watchdog-diagnostics.json` for session health
+3. Parse job entries
+4. Display formatted status with health indicator
+5. For --resume, update job status and continue operation
+6. For --diagnostics, show detailed watchdog checks
 
-### State File Location
+### State File Locations
 
 ```
-.specweave/state/background-jobs.json
+.specweave/state/background-jobs.json          - Job status and progress
+.specweave/state/.watchdog-diagnostics.json    - Session health checks
+.specweave/state/jobs/<jobId>/config.json      - Job configuration
+.specweave/state/jobs/<jobId>/worker.pid       - Worker process ID
+.specweave/state/jobs/<jobId>/worker.log       - Worker output log
+.specweave/logs/watchdog.log                   - Watchdog history
+```
+
+### Reading Session Health
+
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+
+function getSessionHealth(projectPath: string): SessionHealth | null {
+  const diagnosticsPath = path.join(projectPath, '.specweave/state/.watchdog-diagnostics.json');
+  if (!fs.existsSync(diagnosticsPath)) {
+    return null; // Watchdog not running
+  }
+
+  try {
+    const content = fs.readFileSync(diagnosticsPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+interface SessionHealth {
+  timestamp: string;
+  severity: 0 | 1 | 2;  // INFO | WARNING | CRITICAL
+  status: 'healthy' | 'warning' | 'critical';
+  checks: {
+    lock: { severity: number; message: string };
+    zombies: { count: number; message: string };
+    mcp: { drops: number; message: string };
+    orphanedJobs: { count: number; message: string };
+  };
+  consecutiveWarnings: number;
+  thresholdSeconds: number;
+  checkIntervalSeconds: number;
+}
 ```
 
 ### Job Types
@@ -299,9 +347,106 @@ If job failed:
 
 ---
 
+## Session Health & Watchdog Diagnostics (v2.0)
+
+The `/specweave:jobs` command now includes session health monitoring. The watchdog runs in the background and writes diagnostics that help explain any alerts you may have received.
+
+### Display Format (with health status)
+
+```
+📋 Background Jobs & Session Health
+
+🩺 Session Health: ✅ healthy
+   Last check: 30 seconds ago
+   Consecutive warnings: 0/3
+
+🔄 Running (1):
+  [abc12345] import-issues (ADO)
+     Progress: 2,500/10,000 (25%)
+     ...
+```
+
+### Diagnostics File
+
+The watchdog writes diagnostics to `.specweave/state/.watchdog-diagnostics.json`:
+
+```json
+{
+  "timestamp": "2025-12-10T10:30:00Z",
+  "severity": 0,
+  "status": "healthy",
+  "checks": {
+    "lock": { "severity": 0, "message": "ok" },
+    "zombies": { "count": 0, "message": "none" },
+    "mcp": { "drops": 2, "message": "minor instability" },
+    "orphanedJobs": { "count": 0, "message": "none" }
+  },
+  "consecutiveWarnings": 0,
+  "thresholdSeconds": 300,
+  "checkIntervalSeconds": 60
+}
+```
+
+### View Detailed Diagnostics
+
+```
+/specweave:jobs --diagnostics
+
+🩺 Watchdog Diagnostics
+
+Overall Status: ✅ healthy
+Last Check: 2025-12-10 10:30:00
+Severity Level: INFO (0)
+
+Checks:
+  📁 Lock File:      ✅ ok
+  💀 Zombie Procs:   ✅ none (0)
+  🔌 MCP Connection: ⚠️  2 drops detected (minor instability)
+  📦 Orphaned Jobs:  ✅ none (0)
+
+Alert Threshold: 3 consecutive warnings
+Current Warnings: 0/3
+
+Severity Levels:
+  INFO (0)     - Everything healthy, no action needed
+  WARNING (1)  - Minor issue detected, monitoring (NO notification)
+  CRITICAL (2) - Real stuck condition detected → NOTIFICATION SENT
+
+💡 The watchdog only sends notifications for CRITICAL issues
+   that persist across 3+ consecutive checks (prevents false positives).
+```
+
+### Why You Got a Notification
+
+If you received a notification but your job completed successfully, here's what happened:
+
+1. **Old behavior (v1)**: Watchdog triggered on stale lock files even if no process was stuck
+2. **New behavior (v2)**: Watchdog verifies actual process state before alerting
+
+Common false positive causes (now fixed):
+- Stale `.processor.lock` file from completed job
+- Missing heartbeat file (never written in normal operation)
+- MCP connection drops (warning only, not critical)
+
+**The v2 watchdog now requires**:
+1. **Actual stuck process** (zombie heredoc, hung worker)
+2. **3 consecutive checks** showing the same issue
+3. **CRITICAL severity** (not just warnings)
+
+### Watchdog Log
+
+View historical watchdog checks:
+
+```bash
+cat .specweave/logs/watchdog.log
+```
+
+---
+
 ## Notes
 
 - Jobs persist across Claude sessions
 - Paused jobs can be resumed later
 - Completed jobs cleaned up after 10 entries
 - Rate limiting auto-pauses and notifies
+- Watchdog diagnostics available via `--diagnostics` flag

package/plugins/specweave/hooks/hooks.json

@@ -50,6 +50,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write",
+        "matcher_content": "\\.specweave/increments/\\d{3,4}E?-[^/]+/spec\\.md",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'W=\"${CLAUDE_PLUGIN_ROOT}/hooks/universal/fail-fast-wrapper.sh\"; S=\"${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/per-us-project-validator.sh\"; [[ -x \"$W\" ]] && exec \"$W\" \"$S\" || (cat >/dev/null && printf \"{\\\"decision\\\":\\\"allow\\\"}\")'"
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "matcher_content": "\\.specweave/docs/internal/specs/_features/",

package/plugins/specweave/hooks/spec-project-validator.sh

@@ -61,18 +61,40 @@ fi
 # Extract YAML frontmatter
 FRONTMATTER=$(echo "$CONTENT" | sed -n '/^---$/,/^---$/p' | tail -n +2 | head -n -1)
 
-# Check for unresolved project placeholder
+# Check for unresolved project placeholder (legacy {{PROJECT_ID}})
 if echo "$FRONTMATTER" | grep -q 'project:\s*{{PROJECT_ID}}'; then
   echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{PROJECT_ID}}. Run '\''specweave context projects'\'' to get available projects, then select one."}'
   exit 0
 fi
 
-# Check for unresolved board placeholder
+# Check for unresolved board placeholder (legacy {{BOARD_ID}})
 if echo "$FRONTMATTER" | grep -q 'board:\s*{{BOARD_ID}}'; then
   echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{BOARD_ID}}. Run '\''specweave context boards --project=<id>'\'' to get available boards, then select one."}'
   exit 0
 fi
 
+# Check for ANY unresolved {{...}} placeholder in frontmatter (v0.34.0+)
+# This catches {{RESOLVED_PROJECT}}, {{RESOLVED_BOARD}}, and any other placeholders
+if echo "$FRONTMATTER" | grep -qE '\{\{[A-Z_]+\}\}'; then
+  FOUND_PLACEHOLDERS=$(echo "$FRONTMATTER" | grep -oE '\{\{[A-Z_]+\}\}' | tr '\n' ', ' | sed 's/,$//')
+  echo "{\"decision\": \"block\", \"reason\": \"spec.md has unresolved placeholders: ${FOUND_PLACEHOLDERS}\\n\\nYOU MUST RESOLVE these BEFORE creating spec.md:\\n1. Run: specweave context projects\\n2. Parse the JSON output to get valid project/board IDs\\n3. Replace placeholders with actual values from step 2\\n\\n❌ FORBIDDEN: Using placeholder templates directly\\n✅ REQUIRED: Resolve ALL placeholders to actual values\"}"
+  exit 0
+fi
+
+# Check for ANY unresolved {{...}} placeholder in full content (catches per-US **Project**: {{...}})
+if echo "$CONTENT" | grep -qE '\*\*Project\*\*:\s*\{\{[A-Z_]+\}\}'; then
+  FOUND_PLACEHOLDERS=$(echo "$CONTENT" | grep -oE '\*\*Project\*\*:\s*\{\{[A-Z_]+\}\}' | head -1)
+  echo "{\"decision\": \"block\", \"reason\": \"spec.md has unresolved **Project**: placeholder\\n\\nFound: ${FOUND_PLACEHOLDERS}\\n\\nEach user story MUST have a resolved **Project**: field.\\n\\n1. Run: specweave context projects\\n2. Get valid project IDs from the JSON output\\n3. Replace the placeholder with an actual project ID\"}"
+  exit 0
+fi
+
+# Check for unresolved **Board**: placeholders in full content (2-level structures)
+if echo "$CONTENT" | grep -qE '\*\*Board\*\*:\s*\{\{[A-Z_]+\}\}'; then
+  FOUND_PLACEHOLDERS=$(echo "$CONTENT" | grep -oE '\*\*Board\*\*:\s*\{\{[A-Z_]+\}\}' | head -1)
+  echo "{\"decision\": \"block\", \"reason\": \"spec.md has unresolved **Board**: placeholder\\n\\nFound: ${FOUND_PLACEHOLDERS}\\n\\nEach user story MUST have a resolved **Board**: field (for 2-level structures).\\n\\n1. Run: specweave context projects\\n2. Get valid board IDs from boardsByProject in the JSON output\\n3. Replace the placeholder with an actual board ID\"}"
+  exit 0
+fi
+
 # Extract project and board from frontmatter
 PROJECT=$(echo "$FRONTMATTER" | grep -E '^project:\s*' | sed 's/^project:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
 BOARD=$(echo "$FRONTMATTER" | grep -E '^board:\s*' | sed 's/^board:\s*//' | tr -d '"'"'" | tr -d '[:space:]')

package/plugins/specweave/hooks/universal/hook-wrapper.cmd

@@ -1,26 +1,26 @@
-@echo off
-REM hook-wrapper.cmd - Windows resilient hook launcher
-REM Prevents crashes when dispatcher.mjs is temporarily unavailable
-
-setlocal enabledelayedexpansion
-
-set "HOOK_TYPE=%~1"
-if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
-
-set "SCRIPT_DIR=%~dp0"
-set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
-
-REM Check if dispatcher exists
-if not exist "%DISPATCHER%" (
-    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
-    exit /b 0
-)
-
-REM Run dispatcher with error suppression
-node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
-if errorlevel 1 (
-    echo {"continue":true,"systemMessage":"Hook error, continuing"}
-    exit /b 0
-)
-
-exit /b 0
+@echo off
+REM hook-wrapper.cmd - Windows resilient hook launcher
+REM Prevents crashes when dispatcher.mjs is temporarily unavailable
+
+setlocal enabledelayedexpansion
+
+set "HOOK_TYPE=%~1"
+if "%HOOK_TYPE%"=="" set "HOOK_TYPE=unknown"
+
+set "SCRIPT_DIR=%~dp0"
+set "DISPATCHER=%SCRIPT_DIR%dispatcher.mjs"
+
+REM Check if dispatcher exists
+if not exist "%DISPATCHER%" (
+    echo {"continue":true,"systemMessage":"Hook skipped: dispatcher.mjs not found"}
+    exit /b 0
+)
+
+REM Run dispatcher with error suppression
+node "%DISPATCHER%" "%HOOK_TYPE%" 2>nul
+if errorlevel 1 (
+    echo {"continue":true,"systemMessage":"Hook error, continuing"}
+    exit /b 0
+)
+
+exit /b 0

package/plugins/specweave/hooks/universal/session-start.cmd

@@ -1,16 +1,16 @@
-@echo off
-:: Universal Session Start Hook for Windows
-:: Calls the Node.js dispatcher
-
-:: Find node.exe
-where node >nul 2>&1
-if %ERRORLEVEL% neq 0 (
-    echo {"continue": true, "error": "Node.js not found"}
-    exit /b 0
-)
-
-:: Get the directory of this script
-set "SCRIPT_DIR=%~dp0"
-
-:: Run the dispatcher
-node "%SCRIPT_DIR%dispatcher.mjs" session-start
+@echo off
+:: Universal Session Start Hook for Windows
+:: Calls the Node.js dispatcher
+
+:: Find node.exe
+where node >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo {"continue": true, "error": "Node.js not found"}
+    exit /b 0
+)
+
+:: Get the directory of this script
+set "SCRIPT_DIR=%~dp0"
+
+:: Run the dispatcher
+node "%SCRIPT_DIR%dispatcher.mjs" session-start

package/plugins/specweave/hooks/universal/session-start.ps1

@@ -1,16 +1,16 @@
-# Universal Session Start Hook for Windows PowerShell
-# Calls the Node.js dispatcher for cross-platform compatibility
-
-# Find node.exe
-$nodePath = Get-Command node -ErrorAction SilentlyContinue
-
-if (-not $nodePath) {
-    Write-Host '{"continue": true, "error": "Node.js not found"}'
-    exit 0
-}
-
-# Get script directory
-$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-
-# Run the dispatcher
-& node "$scriptDir\dispatcher.mjs" session-start
+# Universal Session Start Hook for Windows PowerShell
+# Calls the Node.js dispatcher for cross-platform compatibility
+
+# Find node.exe
+$nodePath = Get-Command node -ErrorAction SilentlyContinue
+
+if (-not $nodePath) {
+    Write-Host '{"continue": true, "error": "Node.js not found"}'
+    exit 0
+}
+
+# Get script directory
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Run the dispatcher
+& node "$scriptDir\dispatcher.mjs" session-start

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -204,7 +204,91 @@ fi
 # DISCIPLINE VALIDATION: Warn about WIP limits (configurable, not hard block!)
 # ==============================================================================
 
-if echo "$PROMPT" | grep -q "/specweave:increment"; then
+# ==============================================================================
+# PROJECT CONTEXT + WIP LIMITS FOR /specweave:increment (v0.34.0)
+# ==============================================================================
+# CRITICAL: Inject project/board context BEFORE Claude generates spec.md
+# This ensures Claude knows available projects and uses correct IDs
+# ALSO: Check WIP limits in same block to avoid duplicate command detection
+
+if echo "$PROMPT" | grep -qE "^/specweave:increment"; then
+  # Get project context (uses specweave CLI if available)
+  PROJECT_CONTEXT=""
+
+  if command -v specweave >/dev/null 2>&1; then
+    # Use CLI for accurate project/board detection
+    CONTEXT_JSON=$(specweave context projects 2>/dev/null || echo '{}')
+
+    # Validate JSON before parsing (defensive coding)
+    if [[ -n "$CONTEXT_JSON" ]] && [[ "$CONTEXT_JSON" != "{}" ]]; then
+      if command -v jq >/dev/null 2>&1; then
+        # Verify JSON is parseable before extracting fields
+        if ! echo "$CONTEXT_JSON" | jq empty 2>/dev/null; then
+          CONTEXT_JSON='{}'  # Invalid JSON - reset to empty
+        fi
+      fi
+    fi
+
+    if [[ -n "$CONTEXT_JSON" ]] && [[ "$CONTEXT_JSON" != "{}" ]]; then
+      # Parse JSON with jq
+      if command -v jq >/dev/null 2>&1; then
+        LEVEL=$(echo "$CONTEXT_JSON" | jq -r '.level // 1')
+        PROJECTS=$(echo "$CONTEXT_JSON" | jq -r '.projects | map(.id) | join(", ")' 2>/dev/null || echo "")
+
+        if [[ "$LEVEL" == "2" ]]; then
+          # 2-level structure: include boards
+          BOARDS_JSON=$(echo "$CONTEXT_JSON" | jq -r '.boardsByProject // {}' 2>/dev/null)
+          if [[ -n "$BOARDS_JSON" ]] && [[ "$BOARDS_JSON" != "{}" ]]; then
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (2-LEVEL STRUCTURE)\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have both:\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Project**: <project_id>\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Board**: <board_id>\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Available projects: ${PROJECTS}\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Boards by project:\\n"
+
+            # Format boards
+            for proj in $(echo "$CONTEXT_JSON" | jq -r '.projects[].id' 2>/dev/null); do
+              PROJ_BOARDS=$(echo "$CONTEXT_JSON" | jq -r ".boardsByProject[\"$proj\"] | map(.id) | join(\", \")" 2>/dev/null || echo "")
+              [[ -n "$PROJ_BOARDS" ]] && PROJECT_CONTEXT="${PROJECT_CONTEXT}  - ${proj}: ${PROJ_BOARDS}\\n"
+            done
+
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}\\n❌ FORBIDDEN: Comma-separated values (e.g., **Project**: fe, be)\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}✅ REQUIRED: One project + one board per User Story"
+          fi
+        elif [[ -n "$PROJECTS" ]]; then
+          # 1-level structure: projects only
+          PROJECT_COUNT=$(echo "$CONTEXT_JSON" | jq '.projects | length' 2>/dev/null || echo "0")
+
+          if [[ "$PROJECT_COUNT" -gt 1 ]]; then
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (MULTI-PROJECT)\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have:\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}  - **Project**: <project_id>\\n\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Available projects: ${PROJECTS}\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}\\n❌ FORBIDDEN: Comma-separated values\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}✅ REQUIRED: One project per User Story"
+          elif [[ "$PROJECT_COUNT" -eq 1 ]]; then
+            # Single project: auto-select
+            SINGLE_PROJECT=$(echo "$CONTEXT_JSON" | jq -r '.projects[0].id' 2>/dev/null)
+            PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT\\n"
+            PROJECT_CONTEXT="${PROJECT_CONTEXT}Single project detected: ${SINGLE_PROJECT} (auto-selected)"
+          fi
+        fi
+      fi
+    fi
+  else
+    # Fallback: Check for multi-project folders
+    if [[ -d "$SPECWEAVE_DIR/docs/internal/specs" ]]; then
+      PROJ_COUNT=$(find "$SPECWEAVE_DIR/docs/internal/specs" -maxdepth 1 -type d | wc -l)
+      if [[ "$PROJ_COUNT" -gt 2 ]]; then
+        PROJ_LIST=$(ls -1 "$SPECWEAVE_DIR/docs/internal/specs" 2>/dev/null | grep -v "_" | tr '\n' ', ' | sed 's/,$//')
+        PROJECT_CONTEXT="\\n\\n📦 PROJECT CONTEXT (MULTI-PROJECT)\\n"
+        PROJECT_CONTEXT="${PROJECT_CONTEXT}⚠️ MANDATORY: Each User Story MUST have **Project**: field\\n"
+        PROJECT_CONTEXT="${PROJECT_CONTEXT}Available folders: ${PROJ_LIST}"
+      fi
+    fi
+  fi
+
+  # WIP LIMITS CHECK (inside same block - no duplicate command detection)
   # Read limits from config.json (respect user's settings!)
   CONFIG_FILE="$SPECWEAVE_DIR/config.json"
   SOFT_LIMIT=1
@@ -226,13 +310,31 @@ if echo "$PROMPT" | grep -q "/specweave:increment"; then
 
   # Above hard cap: strong warning but NOT a block (user decides!)
   if [[ "$ACTIVE_COUNT" -ge "$HARD_CAP" ]]; then
-    printf '{"decision":"approve","systemMessage":"⚠️  WIP LIMIT EXCEEDED (%s/%s)\\n\\nYou have %s active increments (configured maximum: %s)\\n\\nActive increments:\\n%s\\n\\n🧠 Research shows 3+ concurrent tasks = 40%% slower + more bugs\\n\\n💡 Options:\\n  1️⃣  Complete an increment: /specweave:done <id>\\n  2️⃣  Pause an increment: /specweave:pause <id>\\n  3️⃣  Increase limit: Edit .specweave/config.json limits.hardCap\\n  4️⃣  Continue anyway (not recommended)\\n\\n📝 To proceed anyway, just confirm your intent."}\n' "$ACTIVE_COUNT" "$HARD_CAP" "$ACTIVE_COUNT" "$HARD_CAP" "$ACTIVE_LIST"
+    WIP_MSG="⚠️  WIP LIMIT EXCEEDED (${ACTIVE_COUNT}/${HARD_CAP})\\n\\nYou have ${ACTIVE_COUNT} active increments (configured maximum: ${HARD_CAP})\\n\\nActive increments:\\n${ACTIVE_LIST}\\n\\n🧠 Research shows 3+ concurrent tasks = 40%% slower + more bugs\\n\\n💡 Options:\\n  1️⃣  Complete an increment: /specweave:done <id>\\n  2️⃣  Pause an increment: /specweave:pause <id>\\n  3️⃣  Increase limit: Edit .specweave/config.json limits.hardCap\\n  4️⃣  Continue anyway (not recommended)\\n\\n📝 To proceed anyway, just confirm your intent."
+    # Prepend project context if available
+    if [[ -n "$PROJECT_CONTEXT" ]]; then
+      printf '{"decision":"approve","systemMessage":"%s%s"}\n' "$PROJECT_CONTEXT" "$WIP_MSG"
+    else
+      printf '{"decision":"approve","systemMessage":"%s"}\n' "$WIP_MSG"
+    fi
     exit 0
   fi
 
   # At soft limit: mild warning, approve
   if [[ "$ACTIVE_COUNT" -ge "$SOFT_LIMIT" ]]; then
-    printf '{"decision":"approve","systemMessage":"⚠️  WIP LIMIT REACHED (%s/%s)\\n\\nYou have %s active increment(s) (recommended limit: %s)\\n\\nActive increments:\\n%s\\n\\n🧠 Focus Principle: Fewer active increments = maximum productivity\\n\\n💡 Consider:\\n  1️⃣  Complete current work (recommended)\\n  2️⃣  Pause current work (/specweave:pause)\\n  3️⃣  Continue anyway\\n\\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug"}\n' "$ACTIVE_COUNT" "$SOFT_LIMIT" "$ACTIVE_COUNT" "$SOFT_LIMIT" "$ACTIVE_LIST"
+    WIP_MSG="⚠️  WIP LIMIT REACHED (${ACTIVE_COUNT}/${SOFT_LIMIT})\\n\\nYou have ${ACTIVE_COUNT} active increment(s) (recommended limit: ${SOFT_LIMIT})\\n\\nActive increments:\\n${ACTIVE_LIST}\\n\\n🧠 Focus Principle: Fewer active increments = maximum productivity\\n\\n💡 Consider:\\n  1️⃣  Complete current work (recommended)\\n  2️⃣  Pause current work (/specweave:pause)\\n  3️⃣  Continue anyway\\n\\n⚠️  Emergency hotfix/bug? Use --type=hotfix or --type=bug"
+    # Prepend project context if available
+    if [[ -n "$PROJECT_CONTEXT" ]]; then
+      printf '{"decision":"approve","systemMessage":"%s%s"}\n' "$PROJECT_CONTEXT" "$WIP_MSG"
+    else
+      printf '{"decision":"approve","systemMessage":"%s"}\n' "$WIP_MSG"
+    fi
+    exit 0
+  fi
+
+  # No WIP limit warning, but we may have project context to inject
+  if [[ -n "$PROJECT_CONTEXT" ]]; then
+    printf '{"decision":"approve","systemMessage":"%s"}\n' "$PROJECT_CONTEXT"
     exit 0
   fi
 fi