specweave 0.24.1 → 0.24.8

package/plugins/specweave/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "specweave",
   "description": "SpecWeave framework. Provides increment planning (PM, Architect, Tech Lead agents), specification generation, TDD workflow, living docs sync, and brownfield support. Essential for all SpecWeave projects.",
-  "version": "0.24.0",
+  "version": "0.24.4",
   "author": {
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
@@ -27,7 +27,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-task-completion.sh",
-            "timeout": 60
+            "timeout": 2
           }
         ]
       },
@@ -37,7 +37,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-spec.sh",
-            "timeout": 2
+            "timeout": 1
           }
         ]
       },
@@ -47,7 +47,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-write-spec.sh",
-            "timeout": 2
+            "timeout": 1
           }
         ]
       }

package/plugins/specweave/agents/pm/AGENT.md

@@ -842,6 +842,8 @@ Based on your answers, I'll calculate RICE scores and create a prioritized roadm
 
 **MANDATORY STEP**: After creating increment files, you MUST ACTUALLY EXECUTE metadata.json validation using Read and Write tools.
 
+**NOTE (v0.24.5+)**: The `increment-planner` skill now has explicit Step 11 for metadata.json creation. This validation is a **safety net** if the skill is bypassed or if you're invoked directly via `/specweave:increment`.
+
 ### Why This Matters
 
 Without metadata.json:

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

@@ -40,53 +40,6 @@ You are helping the user implement a SpecWeave increment by executing tasks from
 
 ## Workflow
 
-### Step 0: Plugin Validation (MANDATORY - ALWAYS FIRST! v0.9.4+)
-
-🚨 **CRITICAL**: Before ANY task execution, validate SpecWeave plugin installation.
-
-**Why This Matters**:
-- Ensures SpecWeave marketplace is registered in Claude Code
-- Ensures core `specweave` plugin is installed
-- Prevents execution failures from missing dependencies
-- Enables seamless environment migration (local → VM → Cloud IDE)
-
-**Implementation**:
-
-Use the Bash tool to run:
-```bash
-npx specweave validate-plugins --auto-install
-```
-
-**Expected Output (Success)**:
-```
-✅ All plugins validated!
-   • Core plugin: installed (v0.9.4)
-```
-
-**Expected Output (Missing Components)**:
-```
-❌ Missing components detected:
-   • SpecWeave marketplace not registered
-   • Core plugin (specweave) not installed
-
-📦 Installing missing components...
-   ✅ Marketplace registered (.claude/settings.json)
-   ✅ Core plugin installed (specweave)
-
-🎉 Environment ready! Proceeding with task execution...
-```
-
-**What to Do After Validation**:
-
-1. ✅ **If validation passes**: Proceed to Step 1
-2. ⚠️ **If validation fails with errors**: Show error messages and STOP (do NOT proceed)
-3. 🔄 **If auto-install succeeded**: Proceed to Step 1
-4. ⚠️ **If auto-install failed**: Show manual instructions and STOP
-
-**DO NOT PROCEED** to Step 1 until plugin validation passes!
-
----
-
 ### Step 1: Load Context
 
 1. **Find increment directory**:

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

@@ -11,88 +11,6 @@ You are helping the user create a new SpecWeave increment with automatic closure
 
 ## Steps:
 
-### Step 0: Plugin Validation (MANDATORY - ALWAYS FIRST! v0.9.4+)
-
-🚨 **CRITICAL**: Before ANY planning or execution, validate SpecWeave plugin installation.
-
-**Why This Matters**:
-- Ensures SpecWeave marketplace is registered in Claude Code
-- Ensures core `specweave` plugin is installed
-- Detects and suggests context-specific plugins based on your increment description
-- Prevents cryptic "command not found" errors
-- Enables seamless environment migration (local → VM → Cloud IDE)
-
-**Implementation**:
-
-Use the Bash tool to run:
-```bash
-npx specweave validate-plugins --auto-install --context="$(cat <<'EOF'
-$USER_INCREMENT_DESCRIPTION
-EOF
-)"
-```
-
-**Replace `$USER_INCREMENT_DESCRIPTION`** with the actual increment description provided by the user.
-
-**Expected Output (Success)**:
-```
-✅ All plugins validated!
-   • Core plugin: installed (v0.9.4)
-   • Context plugins: specweave-github (detected from "GitHub sync")
-```
-
-**Expected Output (Missing Components)**:
-```
-❌ Missing components detected:
-   • SpecWeave marketplace not registered
-   • Core plugin (specweave) not installed
-   • Context plugin (specweave-github) not installed
-
-📦 Installing missing components...
-   ✅ Marketplace registered (.claude/settings.json)
-   ✅ Core plugin installed (specweave)
-   ✅ Context plugin installed (specweave-github)
-
-🎉 Environment ready! Proceeding with increment planning...
-```
-
-**What to Do After Validation**:
-
-1. ✅ **If validation passes**: Proceed to Step 0A
-2. ⚠️ **If validation fails with errors**: Show error messages and STOP (do NOT proceed)
-3. 🔄 **If auto-install succeeded**: Proceed to Step 0A
-4. ⚠️ **If auto-install failed**: Show manual instructions (see below) and STOP
-
-**Manual Installation Instructions** (if auto-install fails):
-```
-❌ Auto-install failed. Please install manually:
-
-1. Register SpecWeave marketplace:
-   Edit ~/.claude/settings.json and add:
-   {
-     "extraKnownMarketplaces": {
-       "specweave": {
-         "source": {
-           "source": "github",
-           "repo": "anton-abyzov/specweave",
-           "path": ".claude-plugin"
-         }
-       }
-     }
-   }
-
-2. Install core plugin:
-   Run: /plugin install specweave
-
-3. Restart Claude Code
-
-4. Re-run this command
-```
-
-**DO NOT PROCEED** to Step 0A until plugin validation passes!
-
----
-
 ### Step 0A: STRICT Pre-Flight Check (MANDATORY - v0.6.0+)
 
 **⛔ THE IRON RULE: Cannot start increment N+1 until increment N is DONE**

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

@@ -32,53 +32,6 @@ The `/specweave:next` command is your **workflow continuation** command. It:
 
 ## Workflow
 
-### Step 0: Plugin Validation (MANDATORY - ALWAYS FIRST! v0.9.4+)
-
-🚨 **CRITICAL**: Before ANY workflow transition, validate SpecWeave plugin installation.
-
-**Why This Matters**:
-- Ensures SpecWeave marketplace is registered in Claude Code
-- Ensures core `specweave` plugin is installed
-- Prevents workflow interruptions from missing dependencies
-- Enables seamless environment migration (local → VM → Cloud IDE)
-
-**Implementation**:
-
-Use the Bash tool to run:
-```bash
-npx specweave validate-plugins --auto-install
-```
-
-**Expected Output (Success)**:
-```
-✅ All plugins validated!
-   • Core plugin: installed (v0.9.4)
-```
-
-**Expected Output (Missing Components)**:
-```
-❌ Missing components detected:
-   • SpecWeave marketplace not registered
-   • Core plugin (specweave) not installed
-
-📦 Installing missing components...
-   ✅ Marketplace registered (.claude/settings.json)
-   ✅ Core plugin installed (specweave)
-
-🎉 Environment ready! Proceeding with workflow transition...
-```
-
-**What to Do After Validation**:
-
-1. ✅ **If validation passes**: Proceed to Step 1
-2. ⚠️ **If validation fails with errors**: Show error messages and STOP (do NOT proceed)
-3. 🔄 **If auto-install succeeded**: Proceed to Step 1
-4. ⚠️ **If auto-install failed**: Show manual instructions and STOP
-
-**DO NOT PROCEED** to Step 1 until plugin validation passes!
-
----
-
 ### Step 1: Find Active Increment
 
 ```bash

package/plugins/specweave/hooks/post-task-completion.sh

@@ -250,16 +250,48 @@ fi
 (
   set +e  # Disable error propagation in background job
 
-  # Detect current increment ONCE
-  CURRENT_INCREMENT=$(ls -td .specweave/increments/*/ 2>/dev/null | xargs -n1 basename | grep -v "_backlog" | grep -v "_archive" | grep -v "_working" | head -1)
+  # ============================================================================
+  # CRITICAL FIX: Read active increments from state file (NOT time-based detection)
+  # ============================================================================
+  # WHY: The old logic used 'ls -td' which:
+  #   1. Could pick up completed increments if recently modified
+  #   2. Caused infinite loops on increments with bad AC data
+  #   3. Wasted resources syncing 50+ completed increments
+  #
+  # NEW: Only sync increments that are ACTIVELY being worked on
+  # Source of truth: .specweave/state/active-increment.json
+  # ============================================================================
+
+  ACTIVE_STATE_FILE=".specweave/state/active-increment.json"
+  ACTIVE_INCREMENTS=()
+
+  if [[ ! -f "$ACTIVE_STATE_FILE" ]]; then
+    echo "[$(date)] ⚠️  No active state file found, skipping all background work" >> "$DEBUG_LOG" 2>/dev/null || true
+    echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true  # Reset on success
+    exit 0
+  fi
+
+  if command -v jq >/dev/null 2>&1; then
+    # Use jq to parse the active increments array
+    # NOTE: mapfile requires bash 4+, macOS has bash 3.2, use while read instead
+    while IFS= read -r increment; do
+      ACTIVE_INCREMENTS+=("$increment")
+    done < <(jq -r '.ids[]' "$ACTIVE_STATE_FILE" 2>/dev/null)
+  else
+    # Fallback: simple grep parsing (less reliable, but works without jq)
+    # Match only increment IDs: 4 digits, dash, then letters/numbers/dashes
+    echo "[$(date)] ⚠️  jq not found, using fallback parsing" >> "$DEBUG_LOG" 2>/dev/null || true
+    ACTIVE_INCREMENTS=($(grep -o '"[0-9]\{4\}-[a-zA-Z0-9][a-zA-Z0-9_-]*"' "$ACTIVE_STATE_FILE" 2>/dev/null | tr -d '"'))
+  fi
 
-  if [[ -z "$CURRENT_INCREMENT" ]]; then
-    echo "[$(date)] No active increment, skipping all background work" >> "$DEBUG_LOG" 2>/dev/null || true
+  # If no active increments, skip all work
+  if [[ ${#ACTIVE_INCREMENTS[@]} -eq 0 ]]; then
+    echo "[$(date)] ✓ No active increments, skipping all background work (this is normal)" >> "$DEBUG_LOG" 2>/dev/null || true
     echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true  # Reset on success
     exit 0
   fi
 
-  echo "[$(date)] Starting consolidated background work for $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+  echo "[$(date)] 📋 Found ${#ACTIVE_INCREMENTS[@]} active increment(s): ${ACTIVE_INCREMENTS[*]}" >> "$DEBUG_LOG" 2>/dev/null || true
 
   # Only proceed if Node.js is available
   if ! command -v node &> /dev/null; then
@@ -271,6 +303,33 @@ fi
   # Track if ANY operation succeeded (for circuit breaker)
   ANY_SUCCESS=false
 
+  # ============================================================================
+  # PROCESS EACH ACTIVE INCREMENT
+  # ============================================================================
+  for CURRENT_INCREMENT in "${ACTIVE_INCREMENTS[@]}"; do
+    echo "[$(date)] 🔄 Processing increment: $CURRENT_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+    # Safety check: Verify increment exists and is not archived
+    if [[ ! -d ".specweave/increments/$CURRENT_INCREMENT" ]]; then
+      echo "[$(date)] ⚠️  Increment $CURRENT_INCREMENT not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+      continue
+    fi
+
+    if [[ -d ".specweave/increments/_archive/$CURRENT_INCREMENT" ]]; then
+      echo "[$(date)] ⚠️  Increment $CURRENT_INCREMENT is archived, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+      continue
+    fi
+
+    # Additional safety: Check metadata status (skip completed/abandoned)
+    METADATA_FILE=".specweave/increments/$CURRENT_INCREMENT/metadata.json"
+    if [[ -f "$METADATA_FILE" ]] && command -v jq >/dev/null 2>&1; then
+      INCREMENT_STATUS=$(jq -r '.status // "active"' "$METADATA_FILE" 2>/dev/null || echo "active")
+      if [[ "$INCREMENT_STATUS" == "completed" ]] || [[ "$INCREMENT_STATUS" == "abandoned" ]]; then
+        echo "[$(date)] ⏭️  Skipping $CURRENT_INCREMENT (status: $INCREMENT_STATUS)" >> "$DEBUG_LOG" 2>/dev/null || true
+        continue
+      fi
+    fi
+
   # ============================================================================
   # 1. UPDATE TASKS.MD
   # ============================================================================
@@ -429,8 +488,10 @@ fi
     fi
   fi
 
+  done  # End of ACTIVE_INCREMENTS loop
+
   # ============================================================================
-  # 6. STATUS LINE UPDATE
+  # 6. STATUS LINE UPDATE (GLOBAL - outside loop)
   # ============================================================================
   echo "[$(date)] 📊 Updating status line" >> "$DEBUG_LOG" 2>/dev/null || true
 

package/plugins/specweave/hooks/pre-edit-spec.sh

@@ -101,6 +101,17 @@ else
   exit 0  # Let PostToolUse handle it with mtime fallback
 fi
 
+# ============================================================================
+# EARLY EXIT: Only process .specweave/ files (v0.24.4 Performance Fix)
+# ============================================================================
+# 90% of Edit operations are on non-SpecWeave files (src/, tests/, node_modules/)
+# Exit immediately for non-.specweave/ files to reduce hook overhead by 90%
+
+if [[ "$FILE_PATH" != *"/.specweave/"* ]]; then
+  echo "[$(date)] pre-edit-spec: Not a .specweave/ file, skipping (performance optimization)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
 # Check if this is a spec.md or tasks.md file in increments folder
 IS_SPEC_FILE=false
 if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then

package/plugins/specweave/hooks/pre-task-completion.sh

@@ -44,14 +44,74 @@ PROJECT_ROOT="$(find_project_root "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 cd "$PROJECT_ROOT" 2>/dev/null || true
 
 # ============================================================================
-# CONFIGURATION
+# EMERGENCY SAFETY CHECKS (v0.24.4 - Performance Fix)
 # ============================================================================
 
 LOGS_DIR=".specweave/logs"
 DEBUG_LOG="$LOGS_DIR/hooks-debug.log"
-
 mkdir -p "$LOGS_DIR" 2>/dev/null || true
 
+# CIRCUIT BREAKER: Auto-disable after consecutive failures
+CIRCUIT_BREAKER_FILE=".specweave/state/.hook-circuit-breaker-pre"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+mkdir -p ".specweave/state" 2>/dev/null || true
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    # Circuit breaker is OPEN - hooks are disabled
+    exit 0
+  fi
+fi
+
+# FILE LOCK: Only allow 1 pre-task-completion hook at a time
+LOCK_FILE=".specweave/state/.hook-pre-task.lock"
+LOCK_TIMEOUT=5  # seconds (shorter than PostToolUse)
+
+LOCK_ACQUIRED=false
+for i in {1..5}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check for stale lock
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.1
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  # Another instance is running, skip
+  exit 0
+fi
+
+# DEBOUNCING: Prevent duplicate hook fires
+LAST_FIRE_FILE="$LOGS_DIR/last-pre-hook-fire"
+DEBOUNCE_SECONDS=5  # Same as PostToolUse
+
+CURRENT_TIME=$(date +%s)
+
+if [ -f "$LAST_FIRE_FILE" ]; then
+  LAST_FIRE=$(cat "$LAST_FIRE_FILE" 2>/dev/null || echo "0")
+  TIME_DIFF=$((CURRENT_TIME - LAST_FIRE))
+
+  if [ "$TIME_DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
+    # Debounced - skip this execution
+    exit 0
+  fi
+fi
+
+echo "$CURRENT_TIME" > "$LAST_FIRE_FILE"
+
 echo "[$(date)] 🔒 Pre-task-completion hook fired" >> "$DEBUG_LOG" 2>/dev/null || true
 
 # ============================================================================
@@ -170,6 +230,9 @@ if [ "$VALIDATION_EXIT_CODE" = "0" ]; then
   # Validation passed - allow completion
   echo "[$(date)] ✅ AC test validation passed" >> "$DEBUG_LOG" 2>/dev/null || true
 
+  # Reset circuit breaker on success
+  echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+
   VALIDATION_SUMMARY=$(cat "$VALIDATION_OUTPUT" | tail -5 | tr '\n' ' ')
 
   rm -f "$VALIDATION_OUTPUT"
@@ -184,6 +247,10 @@ else
   # Validation failed - block completion
   echo "[$(date)] ❌ AC test validation failed" >> "$DEBUG_LOG" 2>/dev/null || true
 
+  # Increment circuit breaker on failure
+  CURRENT_FAILURES=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  echo "$((CURRENT_FAILURES + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+
   VALIDATION_ERROR=$(cat "$VALIDATION_OUTPUT" | grep -A 10 "VALIDATION FAILED" | tr '\n' ' ' | cut -c 1-300)
 
   rm -f "$VALIDATION_OUTPUT"

package/plugins/specweave/hooks/pre-write-spec.sh

@@ -101,6 +101,17 @@ else
   exit 0  # Let PostToolUse handle it with mtime fallback
 fi
 
+# ============================================================================
+# EARLY EXIT: Only process .specweave/ files (v0.24.4 Performance Fix)
+# ============================================================================
+# 90% of Write operations are on non-SpecWeave files (src/, tests/, node_modules/)
+# Exit immediately for non-.specweave/ files to reduce hook overhead by 90%
+
+if [[ "$FILE_PATH" != *"/.specweave/"* ]]; then
+  echo "[$(date)] pre-write-spec: Not a .specweave/ file, skipping (performance optimization)" >> "$DEBUG_LOG" 2>/dev/null || true
+  exit 0
+fi
+
 # Check if this is a spec.md or tasks.md file in increments folder
 IS_SPEC_FILE=false
 if [[ "$FILE_PATH" == *"/spec.md" ]] || [[ "$FILE_PATH" == *"/tasks.md" ]]; then

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -28,13 +28,14 @@ This skill creates comprehensive, well-structured implementation plans for SpecW
 The increment-planner skill automates the creation of implementation plans for ANY type of work:
 - Auto-numbered increment directories (`0001-9999` 4-digit format)
 - Duplicate detection (prevents creating 0002 when 0002 already exists)
-- Complete increment artifacts (spec.md, plan.md, tasks.md with embedded tests)
+- Complete increment artifacts (spec.md, plan.md, tasks.md with embedded tests, **metadata.json**)
 - Proper context manifests for selective loading
 - Constitutional compliance
 - Separation of WHAT/WHY (spec) from HOW (plan) from STEPS (tasks with test plans)
 - **v0.7.0+**: Test-Aware Planning (bidirectional AC↔Task↔Test linking)
 - **v0.8.0+**: Multi-Project Support (specs organized by project/team)
 - **v0.18.0+**: Bidirectional Task↔User Story Linking (automatic during `/specweave:done`)
+- **v0.24.5+**: **MANDATORY metadata.json creation** (enables status tracking, WIP limits, external tool sync)
 
 ## Bidirectional Linking (v0.18.0+)
 
@@ -593,11 +594,18 @@ Generate the complete feature directory with all required files:
 ├── spec.md                 # Feature specification (WHAT and WHY)
 ├── plan.md                 # Implementation plan (HOW)
 ├── tasks.md                # Executable tasks (STEPS) with embedded test plans (v0.7.0+)
+├── metadata.json           # Increment metadata (MANDATORY - v0.24.5+)
 └── context-manifest.yaml   # Context loading specification
 ```
 
 **v0.7.0 Change**: tests.md eliminated - tests are now embedded in each task in tasks.md
 
+**⚠️ CRITICAL (v0.24.5+)**: `metadata.json` is **MANDATORY** regardless of invocation method (natural language prompt or `/specweave:increment`). Without it:
+- ❌ Status line shows nothing (no active increment tracking)
+- ❌ WIP limits don't work (can't count active increments)
+- ❌ External sync breaks (no GitHub/JIRA/ADO links)
+- ❌ All increment management commands fail (`/status`, `/pause`, `/resume`, `/done`)
+
 ### Step 5: Generate spec.md
 
 **Purpose**: Define WHAT this feature does and WHY it's needed.
@@ -1060,7 +1068,89 @@ tags:
 - Token budget to prevent bloat
 - Related features for dependency tracking
 
-### Step 10: Validate and Finalize
+### Step 11: Generate metadata.json (⚠️ MANDATORY - v0.24.5+)
+
+**Purpose**: Create increment metadata for status tracking, WIP limits, and external tool sync.
+
+**CRITICAL**: This step is **NON-NEGOTIABLE** regardless of how the increment was created (natural language prompt, `/specweave:increment`, or any other method).
+
+**Execution Workflow (MUST USE TOOLS)**:
+
+**STEP 1: Check if metadata.json exists**
+```
+Use Read tool:
+file_path: .specweave/increments/{incrementId}/metadata.json
+```
+
+**STEP 2: If missing (file not found), create it immediately**
+```
+Use Write tool:
+file_path: .specweave/increments/{incrementId}/metadata.json
+content: {
+  "id": "{incrementId}",
+  "status": "planned",
+  "type": "{type}",
+  "priority": "{priority}",
+  "created": "{ISO-8601-timestamp}",
+  "lastActivity": "{ISO-8601-timestamp}",
+  "testMode": "TDD",
+  "coverageTarget": 95,
+  "feature_id": null,
+  "epic_id": null,
+  "externalLinks": {}
+}
+```
+
+**Field Extraction (from spec.md frontmatter)**:
+- `id`: Increment directory name (e.g., "0001-user-authentication")
+- `type`: Extract from `type:` in spec.md frontmatter OR default to "feature"
+- `priority`: Extract from `priority:` in spec.md frontmatter OR default to "P1"
+- `created`/`lastActivity`: Current timestamp in ISO-8601 format (e.g., "2025-11-22T19:30:00Z")
+- `testMode`: Extract from `test_mode:` in spec.md frontmatter OR default to "TDD"
+- `coverageTarget`: Extract from `coverage_target:` in spec.md frontmatter OR default to 95
+
+**STEP 3: Validate creation succeeded**
+```
+Use Read tool again:
+file_path: .specweave/increments/{incrementId}/metadata.json
+```
+
+If Read succeeds, output:
+```
+✅ metadata.json created successfully
+   Status: planned
+   Type: {type}
+   Ready for /specweave:do
+```
+
+**Why This Cannot Be Skipped**:
+Without metadata.json, the increment is **effectively broken**:
+- Status line won't show it as active
+- WIP limit enforcement fails (infinite increments possible!)
+- All increment commands fail (`/status`, `/pause`, `/resume`, `/done`)
+- External tool sync (GitHub/JIRA/ADO) completely broken
+- Hooks can't detect the increment
+
+**Example metadata.json**:
+```json
+{
+  "id": "0001-user-authentication",
+  "status": "planned",
+  "type": "feature",
+  "priority": "P1",
+  "created": "2025-11-22T19:30:00Z",
+  "lastActivity": "2025-11-22T19:30:00Z",
+  "testMode": "TDD",
+  "coverageTarget": 95,
+  "feature_id": null,
+  "epic_id": null,
+  "externalLinks": {}
+}
+```
+
+**⚠️ ENFORCEMENT**: If you complete increment creation without creating metadata.json, you have **failed the task**. This is not optional.
+
+### Step 12: Validate and Finalize
 
 Before completing:
 
@@ -1074,6 +1164,7 @@ Before completing:
    - plan.md has sufficient technical detail + test strategy
    - tasks.md has exact file paths + embedded test plans (BDD format)
    - tasks.md covers all P1 AC-IDs with test cases
+   - **metadata.json exists and is valid** (v0.24.5+ MANDATORY)
    - context-manifest.yaml is precise
 
 3. **Update Features Index**:
@@ -1260,11 +1351,39 @@ max_context_tokens: 8000
 priority: high
 ```
 
-**Step 10**: Validate
+**Step 10**: Generate metadata.json (⚠️ MANDATORY v0.24.5+)
+```typescript
+// Use Read tool to check if exists
+Read({ file_path: ".specweave/increments/0003-stripe-payment-integration/metadata.json" });
+
+// If missing, use Write tool to create
+Write({
+  file_path: ".specweave/increments/0003-stripe-payment-integration/metadata.json",
+  content: JSON.stringify({
+    "id": "0003-stripe-payment-integration",
+    "status": "planned",
+    "type": "feature",
+    "priority": "P1",
+    "created": "2025-11-22T19:30:00Z",
+    "lastActivity": "2025-11-22T19:30:00Z",
+    "testMode": "TDD",
+    "coverageTarget": 95,
+    "feature_id": null,
+    "epic_id": null,
+    "externalLinks": {}
+  }, null, 2)
+});
+
+// Validate creation succeeded
+Read({ file_path: ".specweave/increments/0003-stripe-payment-integration/metadata.json" });
+```
+
+**Step 11**: Validate
 - ✅ spec.md is technology-agnostic with AC-IDs
 - ✅ plan.md documents Stripe SDK choice + test strategy
 - ✅ tasks.md has embedded test plans (BDD format)
 - ✅ tasks.md covers all P1 AC-IDs with tests
+- ✅ **metadata.json exists and is valid** (v0.24.5+ MANDATORY)
 - ✅ Constitutional compliance verified
 
 **Output**:
@@ -1276,12 +1395,13 @@ Files created:
 - spec.md (12 user stories, 34 AC-IDs)
 - plan.md (5 phases, architecture diagrams, test strategy)
 - tasks.md (23 tasks with embedded tests, 85% coverage target)
+- metadata.json ✅ (status: planned, type: feature)
 - context-manifest.yaml
 
 Next steps:
 1. Review spec.md - verify user stories and acceptance criteria
 2. Approve plan.md - validate technical approach
-3. Start implementation: specweave implement 0003
+3. Start implementation: /specweave:do 0003
 ```
 
 ## Helper Scripts

package/plugins/specweave-ado/lib/ado-multi-project-sync.js

@@ -373,7 +373,6 @@ ${userStory.technicalContext}
         return mapping.task || "Task";
       case "Subtask":
         return mapping.task || "Task";
-      // ADO doesn't have subtasks, use Task
       default:
         return "User Story";
     }