specweave 0.33.5 → 0.34.0

package/plugins/specweave/hooks/project-folder-guard.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# Project Folder Guard (Pre-tool-use Hook)
+# Prevents creation of project folders unless project exists in config.json
+#
+# Triggers: Write tool creating files in .specweave/docs/internal/specs/{project}/
+# Blocks: Project folders not in config.json multiProject.projects
+# Version: 0.35.1+ (Enhanced with example project detection)
+#
+# CRITICAL v0.35.1: Added detection of common example project names
+# These are NEVER allowed unless explicitly configured:
+# - frontend-app, backend-api, mobile-app, shared-lib (common examples)
+# - acme-corp, my-app, myapp (placeholder names)
+# - Comma-separated values like "frontend-app, backend-api"
+# - Placeholder patterns like {{PROJECT_ID}}
+
+set -euo pipefail
+
+TOOL_NAME="$1"
+shift
+TOOL_ARGS="$*"
+
+# Only check Write tool operations to specs/ folder
+if [ "$TOOL_NAME" != "Write" ]; then
+  exit 0
+fi
+
+# Extract file_path from tool args (JSON format)
+FILE_PATH=$(echo "$TOOL_ARGS" | jq -r '.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Check if writing to specs folder
+if [[ ! "$FILE_PATH" =~ \.specweave/docs/internal/specs/([^/]+)/ ]]; then
+  exit 0
+fi
+
+# Extract project name from path
+PROJECT_NAME="${BASH_REMATCH[1]}"
+
+# Skip validation for README.md in specs root
+if [ "$PROJECT_NAME" = "README.md" ]; then
+  exit 0
+fi
+
+# CRITICAL v0.35.1: Check for template placeholders like {{PROJECT_ID}}
+if [[ "$PROJECT_NAME" =~ \{\{.*\}\} ]]; then
+  echo "❌ BLOCKED: Unresolved placeholder detected: '$PROJECT_NAME'"
+  echo ""
+  echo "   Project name contains template placeholder syntax: {{ ... }}"
+  echo "   This is NOT a valid project name."
+  echo ""
+  echo "   🔧 Edit spec.md and replace {{...}} with your actual project name"
+  exit 1
+fi
+
+# CRITICAL v0.35.1: Check for comma-separated values (invalid format)
+if [[ "$PROJECT_NAME" =~ , ]]; then
+  echo "❌ BLOCKED: Comma-separated project names detected: '$PROJECT_NAME'"
+  echo ""
+  echo "   Each User Story must have exactly ONE project."
+  echo "   Multiple comma-separated projects are NOT allowed."
+  echo ""
+  echo "   🔧 Split into separate User Stories, one per project"
+  exit 1
+fi
+
+# CRITICAL v0.35.1: Check for parentheses (often seen in examples)
+if [[ "$PROJECT_NAME" =~ \( || "$PROJECT_NAME" =~ \) ]]; then
+  echo "❌ BLOCKED: Invalid characters in project name: '$PROJECT_NAME'"
+  echo ""
+  echo "   Project names cannot contain parentheses."
+  echo "   This looks like an example/documentation string."
+  echo ""
+  echo "   🔧 Use a valid kebab-case project name (e.g., my-project)"
+  exit 1
+fi
+
+# CRITICAL v0.35.1: Check ProjectRegistry FIRST (.specweave/state/projects.json)
+# This is the single source of truth for projects (v0.35.0+)
+REGISTRY_FILE=".specweave/state/projects.json"
+CONFIG_FILE=".specweave/config.json"
+
+# CRITICAL v0.35.1: List of known example project names
+# These are blocked UNLESS explicitly registered
+EXAMPLE_PROJECTS="frontend-app backend-api mobile-app shared-lib acme-corp my-app myapp example-project sample-project test-project demo placeholder per default"
+
+# Check if project is in example list (case-insensitive)
+PROJECT_NAME_LOWER=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]')
+IS_EXAMPLE="false"
+for EXAMPLE in $EXAMPLE_PROJECTS; do
+  if [ "$PROJECT_NAME_LOWER" = "$EXAMPLE" ]; then
+    IS_EXAMPLE="true"
+    break
+  fi
+done
+
+# PRIMARY: Check ProjectRegistry (projects.json)
+if [ -f "$REGISTRY_FILE" ]; then
+  # Get all project IDs from registry
+  REGISTRY_PROJECTS=$(jq -r '.projects | keys[]' "$REGISTRY_FILE" 2>/dev/null || echo "")
+
+  if [ -n "$REGISTRY_PROJECTS" ]; then
+    # Check if project exists in registry (case-insensitive)
+    PROJECT_IN_REGISTRY="false"
+    for REG_PROJECT in $REGISTRY_PROJECTS; do
+      REG_PROJECT_LOWER=$(echo "$REG_PROJECT" | tr '[:upper:]' '[:lower:]')
+      if [ "$PROJECT_NAME_LOWER" = "$REG_PROJECT_LOWER" ]; then
+        PROJECT_IN_REGISTRY="true"
+        break
+      fi
+    done
+
+    if [ "$PROJECT_IN_REGISTRY" = "true" ]; then
+      # Project exists in registry - ALLOW
+      exit 0
+    fi
+
+    # Project NOT in registry
+    VALID_PROJECTS=$(echo "$REGISTRY_PROJECTS" | tr '\n' ', ' | sed 's/,$//')
+
+    if [ "$IS_EXAMPLE" = "true" ]; then
+      echo "❌ BLOCKED: Example project name detected: '$PROJECT_NAME'"
+      echo ""
+      echo "   '$PROJECT_NAME' is a common example/placeholder name used in documentation."
+      echo "   It was likely extracted from example User Stories in spec.md."
+      echo ""
+      echo "   ⚠️  This is NOT a real project - it's a documentation example!"
+      echo ""
+      echo "   Registered projects: $VALID_PROJECTS"
+      echo ""
+      echo "   🔧 How to fix:"
+      echo "   1. Edit the spec.md file and update **Project**: fields"
+      echo "   2. Replace example names with a registered project"
+      echo "   3. Re-run the sync command"
+    else
+      echo "❌ BLOCKED: Project '$PROJECT_NAME' not in registry"
+      echo ""
+      echo "   Project '$PROJECT_NAME' is NOT registered in .specweave/state/projects.json"
+      echo ""
+      echo "   Registered projects: $VALID_PROJECTS"
+      echo ""
+      echo "   🔧 To add this project:"
+      echo "   specweave project add $PROJECT_NAME --name \"Project Display Name\""
+    fi
+    exit 1
+  fi
+fi
+
+# FALLBACK: Check config.json if registry doesn't exist or is empty
+if [ ! -f "$CONFIG_FILE" ]; then
+  echo "❌ ERROR: Neither projects.json nor config.json found"
+  echo "   Cannot validate project folder creation without configuration"
+  exit 1
+fi
+
+# Check if multi-project mode is enabled
+MULTI_PROJECT_ENABLED=$(jq -r '.multiProject.enabled // false' "$CONFIG_FILE")
+
+if [ "$MULTI_PROJECT_ENABLED" != "true" ]; then
+  # Single-project mode - only allow configured project name
+  ALLOWED_PROJECT=$(jq -r '.project.name // "specweave"' "$CONFIG_FILE")
+
+  if [ "$PROJECT_NAME" != "$ALLOWED_PROJECT" ]; then
+    # Special message for example projects
+    if [ "$IS_EXAMPLE" = "true" ]; then
+      echo "❌ BLOCKED: Example project name detected: '$PROJECT_NAME'"
+      echo ""
+      echo "   '$PROJECT_NAME' is a common example/placeholder name used in documentation."
+      echo "   It was likely extracted from example User Stories in spec.md."
+      echo ""
+      echo "   ⚠️  This is NOT a real project - it's a documentation example!"
+      echo ""
+      echo "   🔧 How to fix:"
+      echo "   1. Edit the spec.md file and update **Project**: fields"
+      echo "   2. Replace example names with: $ALLOWED_PROJECT"
+      echo "   3. Re-run the sync command"
+      echo ""
+      echo "   📋 Example fix in spec.md:"
+      echo "   BEFORE: **Project**: $PROJECT_NAME  ← EXAMPLE (WRONG)"
+      echo "   AFTER:  **Project**: $ALLOWED_PROJECT  ← Your actual project"
+      echo ""
+    else
+      echo "❌ BLOCKED: Project folder creation for '$PROJECT_NAME'"
+      echo ""
+      echo "   This repository is in SINGLE-PROJECT mode."
+      echo "   Only folder allowed: $ALLOWED_PROJECT"
+      echo ""
+      echo "   Current config (.specweave/config.json):"
+      echo "   {"
+      echo "     \"project\": { \"name\": \"$ALLOWED_PROJECT\" },"
+      echo "     \"multiProject\": { \"enabled\": false }"
+      echo "   }"
+      echo ""
+      echo "   ⚠️  If '$PROJECT_NAME' is an example/placeholder in spec.md, update it to:"
+      echo "   **Project**: $ALLOWED_PROJECT"
+      echo ""
+      echo "   💡 To add new projects:"
+      echo "   1. Run: specweave config set multiProject.enabled true"
+      echo "   2. Run: specweave config set multiProject.projects.$PROJECT_NAME.id \"$PROJECT_NAME\""
+      echo "   3. Re-run your command"
+    fi
+    exit 1
+  fi
+
+  exit 0
+fi
+
+# Multi-project mode - check if project exists in config
+if jq -e ".multiProject.projects.\"$PROJECT_NAME\"" "$CONFIG_FILE" &>/dev/null; then
+  PROJECT_EXISTS="true"
+else
+  PROJECT_EXISTS="false"
+fi
+
+if [ "$PROJECT_EXISTS" = "false" ]; then
+  # Get list of valid projects
+  VALID_PROJECTS=$(jq -r '.multiProject.projects | keys[]' "$CONFIG_FILE" 2>/dev/null | tr '\n' ', ' | sed 's/,$//' || echo "")
+
+  # Special message for example projects
+  if [ "$IS_EXAMPLE" = "true" ]; then
+    echo "❌ BLOCKED: Example project name detected: '$PROJECT_NAME'"
+    echo ""
+    echo "   '$PROJECT_NAME' is a common example/placeholder name used in documentation."
+    echo "   It was likely extracted from example User Stories in spec.md."
+    echo ""
+    echo "   ⚠️  This is NOT a real project - it's a documentation example!"
+    echo ""
+    if [ -n "$VALID_PROJECTS" ]; then
+      echo "   Valid projects: $VALID_PROJECTS"
+      echo ""
+    fi
+    echo "   🔧 How to fix:"
+    echo "   1. Edit the spec.md file and update **Project**: fields"
+    echo "   2. Replace example names with a configured project"
+    echo "   3. Re-run the sync command"
+    echo ""
+  else
+    echo "❌ BLOCKED: Project folder creation for '$PROJECT_NAME'"
+    echo ""
+    echo "   Project '$PROJECT_NAME' is NOT configured in .specweave/config.json"
+    echo ""
+    if [ -n "$VALID_PROJECTS" ]; then
+      echo "   Valid projects: $VALID_PROJECTS"
+      echo ""
+    fi
+    echo "   ⚠️  Common causes:"
+    echo "   1. Example/placeholder project in spec.md User Stories"
+    echo "   2. Typo in **Project**: field (e.g., 'MyApp (3 repos)' instead of real project)"
+    echo "   3. Missing project configuration"
+    echo ""
+    echo "   🔧 How to fix:"
+    if [ -n "$VALID_PROJECTS" ]; then
+      echo "   • If this is an EXAMPLE in spec.md, update to a real project:"
+      echo "     **Project**: ${VALID_PROJECTS%%,*}  # Use first valid project"
+      echo ""
+    fi
+    echo "   • If this is a NEW project, add it to config:"
+    echo "     specweave config set multiProject.projects.$PROJECT_NAME.id \"$PROJECT_NAME\""
+    echo "     specweave config set multiProject.projects.$PROJECT_NAME.name \"Project Display Name\""
+    echo ""
+    echo "   • Check spec.md for placeholder User Stories like:"
+    echo "     **Project**: frontend-app, backend-api  ← FORBIDDEN (comma-separated)"
+    echo "     **Project**: MyApp (3 repos)  ← FORBIDDEN (parentheses not allowed)"
+    echo ""
+  fi
+  exit 1
+fi
+
+# Project exists - allow creation
+exit 0

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

@@ -2,18 +2,19 @@
 #
 # spec-project-validator.sh
 #
-# Pre-tool-use hook that validates spec.md has required project/board fields
+# Pre-tool-use hook that validates spec.md project/board configuration
 # before allowing Write tool to create/update spec.md files.
 #
 # Activation:
 # - tool_name: Write
 # - file_path matches: .specweave/increments/*/spec.md
 #
-# Rules:
-# - 1-level structure: spec.md MUST have `project:` in YAML frontmatter
-# - 2-level structure: spec.md MUST have BOTH `project:` AND `board:` in frontmatter
-# - Project MUST exist in configuration (validated via specweave context projects)
-# - Board MUST exist under project for 2-level (validated via specweave context boards)
+# Rules (ADR-0140 v0.35.0+):
+# - Frontmatter `project:` and `board:` fields are OPTIONAL (deprecated)
+# - Per-US `**Project**:` and `**Board**:` fields are the PRIMARY source
+# - Validates no unresolved {{...}} placeholders exist
+# - Single-project mode: frontmatter project must match config if present
+# - Multi-project mode: validates projects exist in config if referenced
 #
 # Returns exit code 1 (block) if validation fails, 0 (allow) otherwise.
 #
@@ -105,6 +106,10 @@ PROJECT_ROOT="${FILE_PATH%%/.specweave/*}"
 # Change to project root for specweave command
 cd "$PROJECT_ROOT" 2>/dev/null || true
 
+# Check if single-project or multi-project mode (NEW - v0.34.0+)
+CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
+MULTI_PROJECT_ENABLED=$(jq -r '.multiProject.enabled // false' "$CONFIG_FILE" 2>/dev/null || echo "false")
+
 # Get project context via CLI command
 CONTEXT_OUTPUT=$(specweave context projects 2>/dev/null || echo '{"level": 1, "projects": []}')
 
@@ -114,63 +119,79 @@ STRUCTURE_LEVEL=$(echo "$CONTEXT_OUTPUT" | jq -r '.level // 1')
 # Parse available projects
 AVAILABLE_PROJECTS=$(echo "$CONTEXT_OUTPUT" | jq -r '.projects[].id // empty' | tr '\n' ', ' | sed 's/,$//')
 
-# Validation based on structure level
-if [ "$STRUCTURE_LEVEL" = "2" ]; then
-  # 2-level: BOTH project AND board required
+# NEW (v0.34.0+): Single-project mode validation
+if [ "$MULTI_PROJECT_ENABLED" = "false" ]; then
+  # Single-project mode: project field is OPTIONAL
+  # If provided, validate it matches config.project.name
+  CONFIGURED_PROJECT=$(jq -r '.project.name // "specweave"' "$CONFIG_FILE" 2>/dev/null)
 
-  # Check project field exists
-  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
-    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'project:' field in YAML frontmatter.\\n\\n2-level structure detected.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS:-none detected}\\n\\nAdd 'project: <project_name>' to frontmatter.\\n\\nRun 'specweave context projects' to see all options.\"}"
+  if [ -n "$PROJECT" ] && [ "$PROJECT" != "null" ] && [ "$PROJECT" != "$CONFIGURED_PROJECT" ]; then
+    echo "{\"decision\": \"block\", \"reason\": \"spec.md has project: '${PROJECT}' but config has project.name: '${CONFIGURED_PROJECT}'.\\n\\nIn single-project mode, the project: field MUST match config.project.name OR be omitted.\\n\\nFix:\\n1. Remove project: field (recommended for single-project mode)\\n2. OR change to: project: ${CONFIGURED_PROJECT}\\n3. OR enable multi-project mode: /sw:enable-multiproject\"}"
     exit 0
   fi
 
-  # Check board field exists
-  if [ -z "$BOARD" ] || [ "$BOARD" = "null" ]; then
-    # Get available boards for the project
-    AVAILABLE_BOARDS=$(specweave context boards --project="$PROJECT" 2>/dev/null | jq -r '.boards[].id // empty' | tr '\n' ', ' | sed 's/,$//')
-
-    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'board:' field in YAML frontmatter.\\n\\n2-level structure detected (project: ${PROJECT}).\\n\\nAvailable boards: ${AVAILABLE_BOARDS:-none detected}\\n\\nAdd 'board: <board_name>' to frontmatter.\\n\\nRun 'specweave context boards --project=${PROJECT}' to see all options.\"}"
+  # ALWAYS block board: field in single-project mode
+  if [ -n "$BOARD" ] && [ "$BOARD" != "null" ]; then
+    echo "{\"decision\": \"block\", \"reason\": \"spec.md has board: field but this is a SINGLE-PROJECT repository.\\n\\nThe board: field is ONLY for multi-project mode.\\n\\nFix:\\n1. Remove the board: field\\n2. OR enable multi-project mode: /sw:enable-multiproject\"}"
     exit 0
   fi
 
-  # Validate project exists in configuration
-  PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id == $proj)' 2>/dev/null)
-  if [ -z "$PROJECT_EXISTS" ]; then
-    # Try case-insensitive match
-    PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id | ascii_downcase == ($proj | ascii_downcase))' 2>/dev/null)
-  fi
+  # All validations passed for single-project mode
+  echo '{"decision": "allow"}'
+  exit 0
+fi
 
-  if [ -z "$PROJECT_EXISTS" ] && [ -n "$AVAILABLE_PROJECTS" ]; then
-    echo "{\"decision\": \"block\", \"reason\": \"Project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nEither:\\n1. Update project: field to a valid project\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
-    exit 0
-  fi
+# Multi-project mode validation continues below
+# ADR-0140 (v0.35.0+): Frontmatter project/board fields are OPTIONAL
+# Per-US fields are the PRIMARY source of truth
 
-  # Validate board exists under project
-  BOARDS_OUTPUT=$(specweave context boards --project="$PROJECT" 2>/dev/null || echo '{"boards": []}')
-  BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id == $board)' 2>/dev/null)
+# Validation based on structure level
+if [ "$STRUCTURE_LEVEL" = "2" ]; then
+  # 2-level: Frontmatter project/board are OPTIONAL (per-US fields are primary)
 
-  if [ -z "$BOARD_EXISTS" ]; then
-    # Try case-insensitive match
-    BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id | ascii_downcase == ($board | ascii_downcase))' 2>/dev/null)
+  # If project is provided in frontmatter, validate it exists
+  if [ -n "$PROJECT" ] && [ "$PROJECT" != "null" ]; then
+    PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id == $proj)' 2>/dev/null)
+    if [ -z "$PROJECT_EXISTS" ]; then
+      # Try case-insensitive match
+      PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id | ascii_downcase == ($proj | ascii_downcase))' 2>/dev/null)
+    fi
+
+    if [ -z "$PROJECT_EXISTS" ] && [ -n "$AVAILABLE_PROJECTS" ]; then
+      echo "{\"decision\": \"block\", \"reason\": \"Frontmatter project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nFix:\\n1. Remove project: field (recommended - use per-US **Project**: instead)\\n2. OR update to a valid project\\n3. OR set SPECWEAVE_FORCE_PROJECT=1 to bypass\"}"
+      exit 0
+    fi
   fi
 
-  AVAILABLE_BOARDS=$(echo "$BOARDS_OUTPUT" | jq -r '.boards[].id // empty' | tr '\n' ', ' | sed 's/,$//')
+  # If board is provided in frontmatter, validate it exists under project
+  if [ -n "$BOARD" ] && [ "$BOARD" != "null" ]; then
+    # Need project to validate board
+    if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
+      echo "{\"decision\": \"block\", \"reason\": \"Frontmatter has board: '${BOARD}' but no project: field.\\n\\nIf using board: you must also specify project:.\\n\\nRecommended: Remove both and use per-US **Project**: and **Board**: fields instead.\"}"
+      exit 0
+    fi
 
-  if [ -z "$BOARD_EXISTS" ] && [ -n "$AVAILABLE_BOARDS" ]; then
-    echo "{\"decision\": \"block\", \"reason\": \"Board '${BOARD}' not found under project '${PROJECT}'.\\n\\nAvailable boards: ${AVAILABLE_BOARDS}\\n\\nEither:\\n1. Update board: field to a valid board\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
-    exit 0
-  fi
+    BOARDS_OUTPUT=$(specweave context boards --project="$PROJECT" 2>/dev/null || echo '{"boards": []}')
+    BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id == $board)' 2>/dev/null)
 
-else
-  # 1-level: project is REQUIRED (not just recommended)
+    if [ -z "$BOARD_EXISTS" ]; then
+      # Try case-insensitive match
+      BOARD_EXISTS=$(echo "$BOARDS_OUTPUT" | jq --arg board "$BOARD" '.boards[] | select(.id | ascii_downcase == ($board | ascii_downcase))' 2>/dev/null)
+    fi
 
-  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
-    echo "{\"decision\": \"block\", \"reason\": \"spec.md missing required 'project:' field in YAML frontmatter.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS:-none detected}\\n\\nAdd 'project: <project_name>' to frontmatter.\\n\\nRun 'specweave context projects' to see all options.\"}"
-    exit 0
+    AVAILABLE_BOARDS=$(echo "$BOARDS_OUTPUT" | jq -r '.boards[].id // empty' | tr '\n' ', ' | sed 's/,$//')
+
+    if [ -z "$BOARD_EXISTS" ] && [ -n "$AVAILABLE_BOARDS" ]; then
+      echo "{\"decision\": \"block\", \"reason\": \"Frontmatter board '${BOARD}' not found under project '${PROJECT}'.\\n\\nAvailable boards: ${AVAILABLE_BOARDS}\\n\\nFix:\\n1. Remove board: field (recommended - use per-US **Board**: instead)\\n2. OR update to a valid board\\n3. OR set SPECWEAVE_FORCE_PROJECT=1 to bypass\"}"
+      exit 0
+    fi
   fi
 
-  # Validate project exists in configuration (if we have projects configured)
-  if [ -n "$AVAILABLE_PROJECTS" ]; then
+else
+  # 1-level multi-project: Frontmatter project is OPTIONAL (per-US fields are primary)
+
+  # If project is provided in frontmatter, validate it exists
+  if [ -n "$PROJECT" ] && [ "$PROJECT" != "null" ] && [ -n "$AVAILABLE_PROJECTS" ]; then
     PROJECT_EXISTS=$(echo "$CONTEXT_OUTPUT" | jq --arg proj "$PROJECT" '.projects[] | select(.id == $proj)' 2>/dev/null)
     if [ -z "$PROJECT_EXISTS" ]; then
       # Try case-insensitive match
@@ -178,7 +199,7 @@ else
     fi
 
     if [ -z "$PROJECT_EXISTS" ]; then
-      echo "{\"decision\": \"block\", \"reason\": \"Project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nEither:\\n1. Update project: field to a valid project\\n2. Set SPECWEAVE_FORCE_PROJECT=1 to bypass validation\"}"
+      echo "{\"decision\": \"block\", \"reason\": \"Frontmatter project '${PROJECT}' not found in configuration.\\n\\nAvailable projects: ${AVAILABLE_PROJECTS}\\n\\nFix:\\n1. Remove project: field (recommended - use per-US **Project**: instead)\\n2. OR update to a valid project\\n3. OR set SPECWEAVE_FORCE_PROJECT=1 to bypass\"}"
       exit 0
     fi
   fi

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

@@ -30,7 +30,7 @@ fi
 
 # CRITICAL: Exit immediately for non-SpecWeave prompts
 # This covers 90%+ of prompts with <5ms overhead
-if ! echo "$PROMPT" | grep -qE "(specweave|/specweave:|increment|add|create|implement|build|develop)"; then
+if ! echo "$PROMPT" | grep -qE "(specweave|/sw:|increment|add|create|implement|build|develop)"; then
   echo '{"decision":"approve"}'
   exit 0
 fi
@@ -61,9 +61,9 @@ escape_json() {
   echo "$input" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk '{printf "%s\\n", $0}' | sed 's/\\n$//'
 }
 
-# /specweave:jobs → Execute read-jobs.sh (pure bash, ~2ms)
-if echo "$PROMPT" | grep -qE "^/specweave:jobs($| )"; then
-  ARGS=$(echo "$PROMPT" | sed 's|^/specweave:jobs\s*||')
+# /sw:jobs → Execute read-jobs.sh (pure bash, ~2ms)
+if echo "$PROMPT" | grep -qE "^/sw:jobs($| )"; then
+  ARGS=$(echo "$PROMPT" | sed 's|^/sw:jobs\s*||')
   if [[ -f "$SCRIPTS_DIR/read-jobs.sh" ]]; then
     OUTPUT=$(cd "$(pwd)" && bash "$SCRIPTS_DIR/read-jobs.sh" $ARGS 2>&1)
   elif [[ -f "$SCRIPTS_DIR/jobs.js" ]] && command -v node >/dev/null 2>&1; then
@@ -76,9 +76,9 @@ if echo "$PROMPT" | grep -qE "^/specweave:jobs($| )"; then
   exit 0
 fi
 
-# /specweave:progress → Execute read-progress.sh (pure bash, ~30ms)
-if echo "$PROMPT" | grep -qE "^/specweave:progress($| )"; then
-  ARGS=$(echo "$PROMPT" | sed 's|^/specweave:progress\s*||')
+# /sw:progress → Execute read-progress.sh (pure bash, ~30ms)
+if echo "$PROMPT" | grep -qE "^/sw:progress($| )"; then
+  ARGS=$(echo "$PROMPT" | sed 's|^/sw:progress\s*||')
   if [[ -f "$SCRIPTS_DIR/read-progress.sh" ]]; then
     OUTPUT=$(cd "$(pwd)" && bash "$SCRIPTS_DIR/read-progress.sh" $ARGS 2>&1)
   elif [[ -f "$SCRIPTS_DIR/progress.js" ]] && command -v node >/dev/null 2>&1; then
@@ -91,9 +91,9 @@ if echo "$PROMPT" | grep -qE "^/specweave:progress($| )"; then
   exit 0
 fi
 
-# /specweave:status → Execute read-status.sh (pure bash, ~150ms)
-if echo "$PROMPT" | grep -qE "^/specweave:status($| )"; then
-  ARGS=$(echo "$PROMPT" | sed 's|^/specweave:status\s*||')
+# /sw:status → Execute read-status.sh (pure bash, ~150ms)
+if echo "$PROMPT" | grep -qE "^/sw:status($| )"; then
+  ARGS=$(echo "$PROMPT" | sed 's|^/sw:status\s*||')
   if [[ -f "$SCRIPTS_DIR/read-status.sh" ]]; then
     OUTPUT=$(cd "$(pwd)" && bash "$SCRIPTS_DIR/read-status.sh" $ARGS 2>&1)
   elif [[ -f "$SCRIPTS_DIR/status.js" ]] && command -v node >/dev/null 2>&1; then
@@ -106,9 +106,9 @@ if echo "$PROMPT" | grep -qE "^/specweave:status($| )"; then
   exit 0
 fi
 
-# /specweave:workflow → Execute read-workflow.sh (pure bash, ~100ms)
-if echo "$PROMPT" | grep -qE "^/specweave:workflow($| )"; then
-  ARGS=$(echo "$PROMPT" | sed 's|^/specweave:workflow\s*||')
+# /sw:workflow → Execute read-workflow.sh (pure bash, ~100ms)
+if echo "$PROMPT" | grep -qE "^/sw:workflow($| )"; then
+  ARGS=$(echo "$PROMPT" | sed 's|^/sw:workflow\s*||')
   if [[ -f "$SCRIPTS_DIR/read-workflow.sh" ]]; then
     OUTPUT=$(cd "$(pwd)" && bash "$SCRIPTS_DIR/read-workflow.sh" $ARGS 2>&1)
   else
@@ -119,9 +119,9 @@ if echo "$PROMPT" | grep -qE "^/specweave:workflow($| )"; then
   exit 0
 fi
 
-# /specweave:costs → Execute read-costs.sh (pure bash, ~50ms)
-if echo "$PROMPT" | grep -qE "^/specweave:costs($| )"; then
-  ARGS=$(echo "$PROMPT" | sed 's|^/specweave:costs\s*||')
+# /sw:costs → Execute read-costs.sh (pure bash, ~50ms)
+if echo "$PROMPT" | grep -qE "^/sw:costs($| )"; then
+  ARGS=$(echo "$PROMPT" | sed 's|^/sw:costs\s*||')
   if [[ -f "$SCRIPTS_DIR/read-costs.sh" ]]; then
     OUTPUT=$(cd "$(pwd)" && bash "$SCRIPTS_DIR/read-costs.sh" $ARGS 2>&1)
   else
@@ -133,12 +133,12 @@ if echo "$PROMPT" | grep -qE "^/specweave:costs($| )"; then
 fi
 
 # ==============================================================================
-# TASK COUNT GUARD: Block /specweave:do for oversized increments (v0.32.2+)
+# TASK COUNT GUARD: Block /sw:do for oversized increments (v0.32.2+)
 # ==============================================================================
 # >8 tasks = context explosion = CRASH (per CLAUDE.md)
 MAX_TASKS=8
 
-if echo "$PROMPT" | grep -qE "^/specweave:do($| )"; then
+if echo "$PROMPT" | grep -qE "^/sw:do($| )"; then
   # Extract increment ID from prompt
   DO_INCREMENT_ID=$(echo "$PROMPT" | grep -oE "[0-9]{4}[a-zA-Z0-9-]*" | head -1)
 
@@ -205,13 +205,13 @@ fi
 # ==============================================================================
 
 # ==============================================================================
-# PROJECT CONTEXT + WIP LIMITS FOR /specweave:increment (v0.34.0)
+# PROJECT CONTEXT + WIP LIMITS FOR /sw: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
+if echo "$PROMPT" | grep -qE "^/sw:increment"; then
   # Get project context (uses specweave CLI if available)
   PROJECT_CONTEXT=""
 
@@ -310,7 +310,7 @@ if echo "$PROMPT" | grep -qE "^/specweave:increment"; then
 
   # Above hard cap: strong warning but NOT a block (user decides!)
   if [[ "$ACTIVE_COUNT" -ge "$HARD_CAP" ]]; then
-    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."
+    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: /sw:done <id>\\n  2️⃣  Pause an increment: /sw: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"
@@ -322,7 +322,7 @@ if echo "$PROMPT" | grep -qE "^/specweave:increment"; then
 
   # At soft limit: mild warning, approve
   if [[ "$ACTIVE_COUNT" -ge "$SOFT_LIMIT" ]]; then
-    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"
+    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 (/sw: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"
@@ -380,7 +380,7 @@ if [[ -n "$ACTIVE_INCREMENT" ]] && echo "$PROMPT" | grep -qE "/(specweave:)?(syn
   if [[ -f "$SPEC_FILE" ]] && [[ -f "$PLAN_FILE" ]]; then
     # Check if spec is newer than plan (indicates spec changes need sync)
     if [[ -n $(find "$SPEC_FILE" -newer "$PLAN_FILE" 2>/dev/null) ]]; then
-      printf '{"decision":"approve","systemMessage":"⚠️ Spec changes detected in %s\\n\\nspec.md has been modified after plan.md.\\nConsider running /specweave:sync-docs to update living documentation."}\n' "$ACTIVE_INCREMENT"
+      printf '{"decision":"approve","systemMessage":"⚠️ Spec changes detected in %s\\n\\nspec.md has been modified after plan.md.\\nConsider running /sw:sync-docs to update living documentation."}\n' "$ACTIVE_INCREMENT"
       exit 0
     fi
   fi
@@ -437,14 +437,14 @@ fi
 # COMMAND SUGGESTIONS: Guide users to structured workflow
 # ==============================================================================
 
-if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "$PROMPT" | grep -q "/specweave:"; then
+if echo "$PROMPT" | grep -qiE "(add|create|implement|build|develop)" && ! echo "$PROMPT" | grep -q "/sw:"; then
   if [[ -n "$CONTEXT" ]]; then
     CONTEXT="$CONTEXT
 
 💡 TIP: Consider using SpecWeave commands for structured development:
-  - /specweave:increment \"feature name\"  # Plan new increment
-  - /specweave:do                         # Execute current tasks
-  - /specweave:progress                   # Check progress"
+  - /sw:increment \"feature name\"  # Plan new increment
+  - /sw:do                         # Execute current tasks
+  - /sw:progress                   # Check progress"
   fi
 fi
 

package/plugins/specweave/hooks/v2/guards/completion-guard.sh

@@ -2,7 +2,7 @@
 # completion-guard.sh - Block direct editing of metadata.json to "completed" status
 #
 # v0.28.63+: Prevents the auto-completion bug by blocking direct status changes to completed.
-# Status MUST go through ready_for_review first, and only /specweave:done can mark completed.
+# Status MUST go through ready_for_review first, and only /sw:done can mark completed.
 #
 # PreToolUse hook - can BLOCK the tool call by returning non-zero exit code
 #
@@ -57,7 +57,7 @@ if echo "$NEW_CONTENT" | grep -q '"status"[[:space:]]*:[[:space:]]*"completed"';
   echo ""
   echo "CORRECT WORKFLOW:"
   echo "1. All tasks completed -> status auto-transitions to \"ready_for_review\""
-  echo "2. Run /specweave:done <increment-id> with explicit user confirmation"
+  echo "2. Run /sw:done <increment-id> with explicit user confirmation"
   echo "3. Only then does status become \"completed\""
   echo ""
   echo "WHY THIS MATTERS:"

package/plugins/specweave/hooks/v2/guards/metadata-json-guard.sh

@@ -5,7 +5,7 @@
 # Pre-tool-use hook that ensures metadata.json exists BEFORE spec.md can be created.
 # This prevents increments from being created without proper metadata.
 #
-# ROOT CAUSE: When Claude creates increments via user prompt (not /specweave:increment),
+# ROOT CAUSE: When Claude creates increments via user prompt (not /sw:increment),
 # metadata.json may be forgotten, causing:
 # - Status tracking broken
 # - WIP limits don't work

package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh

@@ -38,7 +38,7 @@ if [[ -f "$THROTTLE_FILE" ]]; then
   fi
   if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
     REMAINING=$((THROTTLE_WINDOW - AGE))
-    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID (wait ${REMAINING}s, use /specweave:sync-progress to bypass)" >> "$THROTTLE_LOG" 2>/dev/null
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID (wait ${REMAINING}s, use /sw:sync-progress to bypass)" >> "$THROTTLE_LOG" 2>/dev/null
     exit 0
   fi
 fi