specweave 1.0.38 → 1.0.39

package/CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- SW:META template="claude" version="1.0.34" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
+<!-- SW:META template="claude" version="1.0.38" sections="header,start,autodetect,metarule,rules,workflow,structure,taskformat,secrets,syncing,mapping,testing,limits,troubleshooting,principles,linking,docs" -->
 
-<!-- SW:SECTION:header version="1.0.34" -->
+<!-- SW:SECTION:header version="1.0.38" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
-<!-- SW:SECTION:start version="1.0.34" -->
+<!-- SW:SECTION:start version="1.0.38" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -14,7 +14,7 @@
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.34" -->
+<!-- SW:SECTION:autodetect version="1.0.38" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -24,7 +24,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.34" -->
+<!-- SW:SECTION:metarule version="1.0.38" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -35,7 +35,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.34" -->
+<!-- SW:SECTION:rules version="1.0.38" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
@@ -45,7 +45,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.34" -->
+<!-- SW:SECTION:workflow version="1.0.38" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -62,7 +62,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done`
 <!-- SW:END:workflow -->
 
-<!-- SW:SECTION:structure version="1.0.34" -->
+<!-- SW:SECTION:structure version="1.0.38" -->
 ## Structure
 
 ```
@@ -78,7 +78,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Multi-repo**: Clone to `/repositories`, not root → `repositories/backend/src/...`
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.34" -->
+<!-- SW:SECTION:taskformat version="1.0.38" -->
 ## Task Format
 
 ```markdown
@@ -88,7 +88,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.34" -->
+<!-- SW:SECTION:secrets version="1.0.38" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -99,7 +99,7 @@ gh auth status
 ```
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.34" -->
+<!-- SW:SECTION:syncing version="1.0.38" -->
 ## Auto-Sync (Hooks)
 
 Post-task: updates tasks.md → living docs → external trackers (if configured)
@@ -107,7 +107,7 @@ Post-task: updates tasks.md → living docs → external trackers (if configured
 Config: `.specweave/config.json` → `hooks.post_task_completion`
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:mapping version="1.0.34" -->
+<!-- SW:SECTION:mapping version="1.0.38" -->
 ## GitHub Mapping
 
 | SpecWeave | GitHub |
@@ -117,7 +117,7 @@ Config: `.specweave/config.json` → `hooks.post_task_completion`
 | Task T-XXX | Checkbox |
 <!-- SW:END:mapping -->
 
-<!-- SW:SECTION:testing version="1.0.34" -->
+<!-- SW:SECTION:testing version="1.0.38" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -129,13 +129,13 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:limits version="1.0.34" -->
+<!-- SW:SECTION:limits version="1.0.38" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.34" -->
+<!-- SW:SECTION:troubleshooting version="1.0.38" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -149,7 +149,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 | External not syncing | Check `config.json` → `external_tracker_sync: true` |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:principles version="1.0.34" -->
+<!-- SW:SECTION:principles version="1.0.38" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -159,7 +159,7 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 5. **Clean**: All files in increment folders
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.34" -->
+<!-- SW:SECTION:linking version="1.0.38" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -167,7 +167,7 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:docs version="1.0.34" -->
+<!-- SW:SECTION:docs version="1.0.38" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/hooks/lib/common-setup.sh

@@ -77,7 +77,8 @@ guard_allow() {
   exit 0
 }
 
-# Block the tool call with reason
+# Block the tool call with reason (DEPRECATED v1.0.37 - use guard_warn instead)
+# NOTE: Blocking is discouraged. Use guard_warn for most cases.
 guard_block() {
   local reason="$1"
   reason=$(echo "$reason" | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
@@ -85,6 +86,15 @@ guard_block() {
   exit 2
 }
 
+# Warn but ALLOW the tool call (v1.0.37+)
+# This is the PREFERRED approach - never block operations, always allow with warnings.
+guard_warn() {
+  local message="$1"
+  message=$(echo "$message" | sed 's/"/\\"/g' | sed ':a;N;$!ba;s/\n/\\n/g')
+  printf '{"decision":"allow","message":"%s"}\n' "$message"
+  exit 0
+}
+
 # ============================================================================
 # SIMPLE LOGGING (optional, writes to .specweave/logs/hooks.log)
 # ============================================================================

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

@@ -1,12 +1,16 @@
 #!/bin/bash
-# completion-guard.sh - Block direct editing of metadata.json to "completed" status
+# completion-guard.sh - WARN (not block) on 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 /sw:done can mark completed.
+# v0.28.63+: Detects the auto-completion bug by warning on direct status changes to completed.
+# Status SHOULD go through ready_for_review first, and /sw:done marks completed with validation.
 #
-# PreToolUse hook - can BLOCK the tool call by returning non-zero exit code
+# v1.0.37+: CRITICAL CHANGE - Now WARNS instead of BLOCKING!
+# User feedback: "you MUST NEVER block such operations... do at least warning"
+# Business logic and validation should be in scripts/agents, not hard blocks.
 #
-# IMPORTANT: This is a safety guard. Exit 0 allows, exit 2 blocks.
+# PreToolUse hook - WARNS but ALLOWS the tool call
+#
+# IMPORTANT: This is a safety guard. Exit 0 allows (with warning if needed).
 # All exit paths MUST output JSON for proper Claude Code handling.
 set +e
 
@@ -57,14 +61,14 @@ if echo "$NEW_CONTENT" | grep -q '"status"[[:space:]]*:[[:space:]]*"completed"';
     fi
   fi
 
-  # BLOCK - trying to set completed without going through ready_for_review
-  cat << 'BLOCK_EOF'
+  # WARN - trying to set completed without going through ready_for_review (v1.0.37)
+  cat << 'WARN_EOF'
 {
-  "decision": "block",
-  "reason": "🚫 BLOCKED: Direct status change to \"completed\" is not allowed (v0.28.63+)\n\nYou cannot directly set status to \"completed\" in metadata.json.\n\nCORRECT WORKFLOW:\n1. All tasks completed → status auto-transitions to \"ready_for_review\"\n2. Run /sw:done <increment-id> with explicit user confirmation\n3. Only then does status become \"completed\"\n\nWHY THIS MATTERS:\n• Ensures all ACs are checked in spec.md before closure\n• Requires explicit user approval\n• Maintains audit trail (approvedAt timestamp)\n\n🔧 If implementing closure logic, use:\n  MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED)"
+  "decision": "allow",
+  "message": "⚠️ WARNING: Direct status change to \"completed\" detected!\n\n🚨 RECOMMENDED WORKFLOW:\n1. All tasks completed → status auto-transitions to \"ready_for_review\"\n2. Run /sw:done <increment-id> with explicit user confirmation\n3. Only then does status become \"completed\"\n\nWHY THIS MATTERS:\n• Ensures all ACs are checked in spec.md before closure\n• Requires explicit user approval\n• Maintains audit trail (approvedAt timestamp)\n\n💡 If implementing closure logic, use:\n  MetadataManager.updateStatus(incrementId, IncrementStatus.COMPLETED)\n\nOperation ALLOWED - proceeding with status change."
 }
-BLOCK_EOF
-  exit 2  # Block the tool call
+WARN_EOF
+  exit 0  # ALLOW with warning (v1.0.37)
 fi
 
 # Allow other edits to metadata.json

package/plugins/specweave/hooks/v2/guards/increment-duplicate-guard.sh

@@ -1,16 +1,16 @@
 #!/bin/bash
-# increment-duplicate-guard.sh - Block creation of duplicate increment IDs
+# increment-duplicate-guard.sh - WARN (not block) on duplicate increment IDs
 #
-# v0.33.0+: Prevents duplicate increment numbers (0121 and 0121 both existing)
-# Also prevents 0001 and 0001E collisions (they share the same base number)
+# v0.33.0+: Detects duplicate increment numbers (0121 and 0121 both existing)
+# Also detects 0001 and 0001E collisions (they share the same base number)
 #
-# PreToolUse hook for Write tool - BLOCKS the tool call if duplicate detected
+# v1.0.37+: CRITICAL CHANGE - Now WARNS instead of BLOCKING!
+# User feedback: "you MUST NEVER block such operations... do at least warning"
+# Business logic and validation should be in scripts/agents, not hard blocks.
 #
-# CRITICAL: This guards against the BUG where two increments get the same ID:
-# - 0121-ado-jira-feature-parity-p2-p3
-# - 0121-intelligent-living-docs-content
+# PreToolUse hook for Write tool - WARNS but ALLOWS the tool call
 #
-# Exit 0 = allow (with JSON), Exit 2 = block (with JSON)
+# Exit 0 = allow (with JSON warning message if duplicate detected)
 set +e
 
 [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && echo '{"decision":"allow"}' && exit 0
@@ -32,6 +32,15 @@ if [[ "$FILE_PATH" != *.specweave/increments/* ]]; then
   exit 0  # Not an increment file - allow
 fi
 
+# CRITICAL FIX (v1.0.37): ALWAYS allow metadata.json writes!
+# metadata.json is the FIRST file created for any increment - it MUST succeed.
+# Duplicate detection only makes sense for the INCREMENT FOLDER, not individual files.
+# Once the folder exists, any file writes within it should be allowed.
+if [[ "$FILE_PATH" == *metadata.json ]]; then
+  echo '{"decision":"allow","message":"metadata.json write allowed (increment creation)"}'
+  exit 0
+fi
+
 # Extract the increment folder name from the path
 # Pattern: .specweave/increments/XXXX-name/file.md or .specweave/increments/XXXX-name/subfolder/file
 # We need to extract "XXXX-name" part
@@ -109,7 +118,7 @@ for DIR in "${DIRS_TO_CHECK[@]}"; do
   done < <(find "$DIR" -maxdepth 1 -type d -name "${INCREMENT_NUM}*" -print0 2>/dev/null)
 done
 
-# If duplicates found, BLOCK the operation and provide the correct number to use
+# If duplicates found, WARN but ALLOW the operation (v1.0.37+: no blocking!)
 if [[ ${#FOUND_DUPLICATES[@]} -gt 0 ]]; then
   # Format duplicates for JSON
   DUP_LIST=""
@@ -129,8 +138,10 @@ if [[ ${#FOUND_DUPLICATES[@]} -gt 0 ]]; then
   FOLDER_NAME_PART=$(echo "$INCREMENT_FOLDER" | sed 's/^[0-9]\{3,4\}E\?-//')
   SUGGESTED_FOLDER="${NEXT_NUM_PADDED}-${FOLDER_NAME_PART}"
 
-  printf '{"decision":"block","reason":"🚫 DUPLICATE INCREMENT ID - Use this instead:\\n\\n✅ CORRECT: %s\\n❌ ATTEMPTED: %s\\n\\nNumber %s already exists:%s\\n\\n🔧 IMMEDIATE FIX: Replace your file path with:\\n   .specweave/increments/%s/...\\n\\nThe guard calculated the next available number for you."}\n' "$SUGGESTED_FOLDER" "$INCREMENT_FOLDER" "$INCREMENT_NUM" "$DUP_LIST" "$SUGGESTED_FOLDER"
-  exit 2  # Block the tool call
+  # v1.0.37: ALLOW with WARNING instead of blocking
+  # User can still proceed - the warning provides guidance
+  printf '{"decision":"allow","message":"⚠️ DUPLICATE INCREMENT ID DETECTED\\n\\n✅ SUGGESTED: %s\\n⚠️ CURRENT: %s\\n\\nNumber %s already exists:%s\\n\\n💡 RECOMMENDATION: Consider using .specweave/increments/%s/ instead.\\n\\nOperation ALLOWED - proceeding with current path."}\n' "$SUGGESTED_FOLDER" "$INCREMENT_FOLDER" "$INCREMENT_NUM" "$DUP_LIST" "$SUGGESTED_FOLDER"
+  exit 0  # ALLOW with warning (v1.0.37: no blocking!)
 fi
 
 # No duplicates - allow

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

@@ -2,8 +2,8 @@
 #
 # metadata-json-guard.sh
 #
-# Pre-tool-use hook that ensures metadata.json exists BEFORE spec.md can be created.
-# This prevents increments from being created without proper metadata.
+# Pre-tool-use hook that WARNS (not blocks) if metadata.json is missing before spec.md creation.
+# This helps ensure proper increment creation workflow.
 #
 # ROOT CAUSE: When Claude creates increments via user prompt (not /sw:increment),
 # metadata.json may be forgotten, causing:
@@ -12,18 +12,23 @@
 # - External sync fails (GitHub/Jira/ADO)
 # - All increment commands fail
 #
-# SOLUTION: Block spec.md creation if metadata.json doesn't exist in same increment folder.
-# Claude MUST create metadata.json FIRST, then spec.md.
+# v1.0.37+: CRITICAL CHANGE - Now WARNS instead of BLOCKING!
+# User feedback: "you MUST NEVER block such operations... do at least warning"
+# Business logic and validation should be in scripts/agents, not hard blocks.
+#
+# SOLUTION: WARN if spec.md is created without metadata.json, but ALLOW the operation.
+# The warning prompts Claude to create metadata.json immediately after.
 #
 # Activation:
 # - tool_name: Write
 # - file_path matches: .specweave/increments/*/spec.md
 #
-# Returns exit code 2 (block) if metadata.json missing, 0 (allow) otherwise.
+# Returns exit 0 (allow) with warning message if metadata.json missing
 #
 # Bypass: Set SPECWEAVE_FORCE_METADATA=1 to skip validation
 #
 # v0.34.0 - Initial implementation based on user project bug analysis
+# v1.0.37 - Changed from BLOCK to WARN (allow with warning message)
 
 set +e  # CRITICAL: Never use set -e in hooks (causes cascading failures)
 
@@ -80,14 +85,14 @@ if [ -f "$METADATA_PATH" ]; then
   exit 0
 fi
 
-# metadata.json doesn't exist - BLOCK spec.md creation
+# metadata.json doesn't exist - WARN but ALLOW spec.md creation (v1.0.37)
 NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
-cat << BLOCK_EOF
+cat << WARN_EOF
 {
-  "decision": "block",
-  "reason": "🚫 BLOCKED: Cannot create spec.md without metadata.json\n\n⚠️ CRITICAL RULE: metadata.json MUST be created FIRST!\n\nWithout metadata.json:\n  - ❌ Status tracking broken\n  - ❌ WIP limits don't work\n  - ❌ External sync fails (GitHub/Jira/ADO)\n  - ❌ All increment commands fail\n\n📋 CORRECT WORKFLOW:\n1. Create metadata.json FIRST:\n   Write({\n     file_path: \"${METADATA_PATH}\",\n     content: {\n       \"id\": \"${INCREMENT_ID}\",\n       \"status\": \"planned\",\n       \"type\": \"feature\",\n       \"priority\": \"P1\",\n       \"created\": \"${NOW}\",\n       \"lastActivity\": \"${NOW}\",\n       \"testMode\": \"TDD\",\n       \"coverageTarget\": 95,\n       \"feature_id\": null,\n       \"epic_id\": null,\n       \"externalLinks\": {}\n     }\n   })\n\n2. THEN create spec.md\n\n📖 See: CLAUDE.md section '3. metadata.json is MANDATORY'\n\n💡 Bypass: Set SPECWEAVE_FORCE_METADATA=1 to skip this validation"
+  "decision": "allow",
+  "message": "⚠️ WARNING: metadata.json MISSING - Creating spec.md without it!\n\n🚨 IMMEDIATE ACTION REQUIRED:\nCreate metadata.json NOW for this increment to work properly.\n\nWithout metadata.json:\n  - ❌ Status tracking broken\n  - ❌ WIP limits don't work\n  - ❌ External sync fails (GitHub/Jira/ADO)\n  - ❌ All increment commands fail\n\n📋 CREATE metadata.json:\n   Write({\n     file_path: \"${METADATA_PATH}\",\n     content: {\n       \"id\": \"${INCREMENT_ID}\",\n       \"status\": \"planned\",\n       \"type\": \"feature\",\n       \"priority\": \"P1\",\n       \"created\": \"${NOW}\",\n       \"lastActivity\": \"${NOW}\",\n       \"testMode\": \"TDD\",\n       \"coverageTarget\": 95,\n       \"feature_id\": null,\n       \"epic_id\": null,\n       \"externalLinks\": {}\n     }\n   })\n\nOperation ALLOWED - proceeding with spec.md write."
 }
-BLOCK_EOF
+WARN_EOF
 
-exit 2
+exit 0

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

@@ -10,7 +10,11 @@
 # - 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)
+# v1.0.37+: CRITICAL CHANGE - All validations now WARN instead of BLOCK!
+# User feedback: "you MUST NEVER block such operations... do at least warning"
+# Business logic and validation should be in scripts/agents, not hard blocks.
+#
+# Exit 0 = allow (with JSON warning message if validation fails)
 #
 # Bypasses:
 # - SPECWEAVE_DISABLE_HOOKS=1 - Disable all hooks
@@ -53,11 +57,11 @@ fi
 # ============================================================================
 if [[ "$HOOK_FILE_PATH" =~ \.specweave/increments/[0-9]{3,4}E?-[^/]+/spec\.md$ ]]; then
 
-  # Check for unresolved {{...}} placeholders
+  # Check for unresolved {{...}} placeholders - WARN only (v1.0.37)
   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
+    printf '{"decision":"allow","message":"⚠️ UNRESOLVED PLACEHOLDERS DETECTED\\n\\nFound: %s\\n\\n🔧 FIX: Replace placeholders with actual values.\\nRun: specweave context projects\\nThen use values from the JSON output.\\n\\nOperation ALLOWED - proceeding anyway."}\n' "$PLACEHOLDERS"
+    exit 0
   fi
 
   # Check for **Project**: field in User Stories (soft validation - warn, don't block)
@@ -78,10 +82,10 @@ if [[ "$HOOK_FILE_PATH" =~ \.specweave/increments/[0-9]{3,4}E?-[^/]+/spec\.md$ ]
     exit 0
   fi
 
-  # Check for comma-separated projects (forbidden - 1:1 mapping required)
+  # Check for comma-separated projects (1:1 mapping required) - WARN only (v1.0.37)
   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
+    printf '{"decision":"allow","message":"⚠️ MULTIPLE PROJECTS IN ONE US DETECTED\\n\\nEach User Story should map to exactly ONE project.\\n\\n💡 RECOMMENDATION: 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\\nOperation ALLOWED - proceeding anyway."}\n'
+    exit 0
   fi
 
   # Check structure level to validate **Board**: fields
@@ -131,19 +135,19 @@ if [[ "$HOOK_FILE_PATH" =~ \.specweave/docs/internal/specs/([^/]+)/ ]]; then
   [[ "$PROJECT_NAME" == "_features" ]] && echo '{"decision":"allow"}' && exit 0
   [[ "$PROJECT_NAME" == "_archive" ]] && echo '{"decision":"allow"}' && exit 0
 
-  # Check for template placeholders
+  # Check for template placeholders - WARN only (v1.0.37)
   if [[ "$PROJECT_NAME" =~ \{\{.*\}\} ]]; then
-    printf '{"decision":"block","reason":"🚫 UNRESOLVED PLACEHOLDER: %s\\n\\n🔧 FIX: Replace {{...}} with actual project name"}\n' "$PROJECT_NAME"
-    exit 2
+    printf '{"decision":"allow","message":"⚠️ UNRESOLVED PLACEHOLDER: %s\\n\\n🔧 FIX: Replace {{...}} with actual project name\\n\\nOperation ALLOWED - proceeding anyway."}\n' "$PROJECT_NAME"
+    exit 0
   fi
 
-  # Check for comma-separated (invalid)
+  # Check for comma-separated (invalid) - WARN only (v1.0.37)
   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
+    printf '{"decision":"allow","message":"⚠️ COMMA-SEPARATED PROJECTS: %s\\n\\nEach User Story should have ONE project folder.\\n\\n💡 RECOMMENDATION: Split into separate specs\\n\\nOperation ALLOWED - proceeding anyway."}\n' "$PROJECT_NAME"
+    exit 0
   fi
 
-  # Check for common example/placeholder names
+  # Check for common example/placeholder names - WARN only (v1.0.37)
   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
@@ -156,8 +160,8 @@ if [[ "$HOOK_FILE_PATH" =~ \.specweave/docs/internal/specs/([^/]+)/ ]]; then
 
       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
+        printf '{"decision":"allow","message":"⚠️ EXAMPLE PROJECT NAME DETECTED: %s\\n\\nThis looks like a placeholder/example name from documentation.\\n\\nConfigured projects: %s\\n\\n💡 RECOMMENDATION: Edit spec.md and use a real project name\\n\\nOperation ALLOWED - proceeding anyway."}\n' "$PROJECT_NAME" "$VALID_PROJECTS"
+        exit 0
       fi
     fi
   fi