specweave 0.33.4 → 0.33.5

package/plugins/specweave/hooks/v2/guards/per-us-project-validator.test.sh

@@ -0,0 +1,406 @@
+#!/bin/bash
+# Comprehensive test suite for per-us-project-validator.sh
+# Tests that each User Story in spec.md has **Project**: (and **Board**: for 2-level)
+#
+# Usage: bash per-us-project-validator.test.sh
+#
+# v0.34.0 - Initial test suite with all US formats
+
+set -e
+
+GUARD="$(dirname "$0")/per-us-project-validator.sh"
+TEST_DIR=$(mktemp -d)
+PASS=0
+FAIL=0
+TOTAL=0
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+cleanup() {
+  rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+# Test helper: should block
+test_should_block() {
+  local name="$1"
+  local spec_content="$2"
+  TOTAL=$((TOTAL + 1))
+
+  local file_path="$TEST_DIR/.specweave/increments/0001-test/spec.md"
+  mkdir -p "$(dirname "$file_path")"
+
+  # Build JSON input for the guard
+  # Use printf + jq -Rs to properly escape newlines in the content
+  local json_input
+  json_input=$(printf '%s' "$spec_content" | jq -Rs \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: .}}')
+
+  result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q '"decision".*"block"'; then
+    echo -e "${GREEN}✓ BLOCKED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ NOT BLOCKED${NC}: $name"
+    echo "  Exit code: $exit_code"
+    echo "  Result: $(echo "$result" | head -3)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Test helper: should allow
+test_should_allow() {
+  local name="$1"
+  local spec_content="$2"
+  TOTAL=$((TOTAL + 1))
+
+  local file_path="$TEST_DIR/.specweave/increments/0001-test/spec.md"
+  mkdir -p "$(dirname "$file_path")"
+
+  # Build JSON input for the guard
+  # Use printf + jq -Rs to properly escape newlines in the content
+  local json_input
+  json_input=$(printf '%s' "$spec_content" | jq -Rs \
+    --arg tool_name "Write" \
+    --arg file_path "$file_path" \
+    '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: .}}')
+
+  result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+  exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+
+  if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q '"decision".*"allow"'; then
+    echo -e "${GREEN}✓ ALLOWED${NC}: $name"
+    PASS=$((PASS + 1))
+  else
+    echo -e "${RED}✗ WRONGLY BLOCKED${NC}: $name"
+    echo "  Exit code: $exit_code"
+    echo "  Result: $(echo "$result" | head -5)"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "========================================"
+echo "  PER-US PROJECT VALIDATOR - COMPREHENSIVE TESTS"
+echo "========================================"
+echo ""
+echo "Test directory: $TEST_DIR"
+echo ""
+
+echo -e "${YELLOW}=== SIMPLE US FORMAT (### US-001:) ===${NC}"
+
+test_should_allow "Simple US with Project field" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Login Form
+**Project**: frontend-app
+
+**As a** user
+**I want** to log in
+**So that** I can access the app
+
+**Acceptance Criteria**:
+- [ ] **AC-US1-01**: Form exists
+'
+
+test_should_block "Simple US WITHOUT Project field" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Login Form
+
+**As a** user
+**I want** to log in
+**So that** I can access the app
+'
+
+echo ""
+echo -e "${YELLOW}=== MULTI-PROJECT US FORMAT (#### US-FE-001:) ===${NC}"
+
+test_should_allow "Multi-project US-FE-001 with Project field" '---
+increment: 0001-test
+project: my-app
+multi_project: true
+---
+# Feature
+
+#### US-FE-001: Login Form UI
+**Project**: frontend-app
+
+**As a** user
+**I want** to see a login form
+
+#### US-BE-001: Auth API
+**Project**: backend-api
+
+**As a** frontend
+**I want** auth endpoints
+'
+
+test_should_block "Multi-project US-FE-001 WITHOUT Project field" '---
+increment: 0001-test
+project: my-app
+multi_project: true
+---
+# Feature
+
+#### US-FE-001: Login Form UI
+
+**As a** user
+**I want** to see a login form
+'
+
+echo ""
+echo -e "${YELLOW}=== MIXED FORMAT (### with prefixes) ===${NC}"
+
+test_should_allow "Mixed: ### US-FE-001 with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-FE-001: Frontend Story
+**Project**: frontend
+
+### US-BE-001: Backend Story
+**Project**: backend
+'
+
+test_should_block "Mixed: ### US-FE-001 without Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-FE-001: Frontend Story
+
+### US-BE-001: Backend Story
+**Project**: backend
+'
+
+echo ""
+echo -e "${YELLOW}=== SHARED PROJECT PREFIX ===${NC}"
+
+test_should_allow "US-SHARED-001 with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+#### US-SHARED-001: Shared Types
+**Project**: shared-lib
+
+**As a** developer
+**I want** shared types
+'
+
+test_should_block "US-SHARED-001 without Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+#### US-SHARED-001: Shared Types
+
+**As a** developer
+**I want** shared types
+'
+
+echo ""
+echo -e "${YELLOW}=== MULTIPLE PROJECTS (1:1 VIOLATION - COMMA SEPARATED) ===${NC}"
+
+test_should_block "Multiple projects (comma separated) - FORBIDDEN" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Cross-cutting Story
+**Project**: frontend-app, backend-api
+
+**As a** user
+**I want** everything
+'
+
+test_should_block "Multiple projects with spaces" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: Cross-cutting Story
+**Project**: frontend-app,backend-api,shared
+
+**As a** user
+**I want** everything
+'
+
+echo ""
+echo -e "${YELLOW}=== NO USER STORIES (should allow) ===${NC}"
+
+test_should_allow "Spec without any User Stories" '---
+increment: 0001-test
+project: my-app
+---
+# Feature Overview
+
+This is just an overview document.
+
+## Goals
+
+- Goal 1
+- Goal 2
+'
+
+test_should_allow "Tasks-only spec (no US headings)" '---
+increment: 0001-test
+project: my-app
+---
+# Implementation Tasks
+
+## T-001: Setup
+
+Do setup stuff.
+'
+
+echo ""
+echo -e "${YELLOW}=== ALL USER STORIES HAVE PROJECT ===${NC}"
+
+test_should_allow "Multiple US, all with Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: First Story
+**Project**: app-a
+
+### US-002: Second Story
+**Project**: app-b
+
+### US-003: Third Story
+**Project**: app-c
+'
+
+test_should_block "Multiple US, one missing Project" '---
+increment: 0001-test
+project: my-app
+---
+# Feature
+
+### US-001: First Story
+**Project**: app-a
+
+### US-002: Second Story
+
+### US-003: Third Story
+**Project**: app-c
+'
+
+echo ""
+echo -e "${YELLOW}=== NON-WRITE TOOLS ===${NC}"
+
+# Test with Edit tool (should allow - no full content)
+TOTAL=$((TOTAL + 1))
+json_input=$(jq -n \
+  --arg tool_name "Edit" \
+  --arg file_path "$TEST_DIR/.specweave/increments/0001-test/spec.md" \
+  '{tool_name: $tool_name, tool_input: {file_path: $file_path}}')
+
+result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]]; then
+  echo -e "${GREEN}✓ ALLOWED${NC}: Edit tool (no full content validation)"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Edit tool should be allowed"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo -e "${YELLOW}=== BYPASS MODES ===${NC}"
+
+# Test SPECWEAVE_FORCE_PROJECT bypass
+TOTAL=$((TOTAL + 1))
+spec_content='---
+increment: 0001-test
+---
+### US-001: No Project
+**As a** user
+**I want** something
+'
+json_input=$(jq -n \
+  --arg tool_name "Write" \
+  --arg file_path "$TEST_DIR/.specweave/increments/0001-test/spec.md" \
+  --arg content "$spec_content" \
+  '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+result=$(SPECWEAVE_FORCE_PROJECT=1 bash -c "echo '$json_input' | bash '$GUARD'" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q "bypassed"; then
+  echo -e "${GREEN}✓ ALLOWED (bypass)${NC}: SPECWEAVE_FORCE_PROJECT=1"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_FORCE_PROJECT=1"
+  FAIL=$((FAIL + 1))
+fi
+
+# Test SPECWEAVE_LEGACY_SPEC bypass
+TOTAL=$((TOTAL + 1))
+result=$(SPECWEAVE_LEGACY_SPEC=1 bash -c "echo '$json_input' | bash '$GUARD'" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q "legacy"; then
+  echo -e "${GREEN}✓ ALLOWED (bypass)${NC}: SPECWEAVE_LEGACY_SPEC=1"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ BYPASS FAILED${NC}: SPECWEAVE_LEGACY_SPEC=1"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo -e "${YELLOW}=== FILES OUTSIDE INCREMENTS ===${NC}"
+
+# Test file outside increments folder
+TOTAL=$((TOTAL + 1))
+json_input=$(jq -n \
+  --arg tool_name "Write" \
+  --arg file_path "$TEST_DIR/other/spec.md" \
+  --arg content "no project" \
+  '{tool_name: $tool_name, tool_input: {file_path: $file_path, content: $content}}')
+
+result=$(echo "$json_input" | bash "$GUARD" 2>&1; echo "EXIT:$?")
+exit_code=$(echo "$result" | grep -o 'EXIT:[0-9]*' | cut -d: -f2)
+if [[ "$exit_code" == "0" ]] && echo "$result" | grep -q '"decision".*"allow"'; then
+  echo -e "${GREEN}✓ ALLOWED${NC}: spec.md outside increments folder"
+  PASS=$((PASS + 1))
+else
+  echo -e "${RED}✗ FAILED${NC}: Files outside increments should be allowed"
+  FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "========================================"
+echo "  RESULTS"
+echo "========================================"
+echo -e "Total: $TOTAL"
+echo -e "${GREEN}Passed: $PASS${NC}"
+if [[ $FAIL -gt 0 ]]; then
+  echo -e "${RED}Failed: $FAIL${NC}"
+  exit 1
+else
+  echo -e "Failed: 0"
+  echo ""
+  echo -e "${GREEN}ALL TESTS PASSED!${NC}"
+fi

package/plugins/specweave/scripts/session-watchdog.sh

@@ -77,15 +77,21 @@ send_notification() {
     return
   fi
 
-  # macOS notification
+  # macOS notification - use "Submarine" for warnings (not alarming like "Basso")
+  # Per CLAUDE.md section 11: Basso = ONLY critical errors requiring IMMEDIATE action
+  # Zombie detection is recoverable - user can run cleanup script when convenient
   if command -v osascript &> /dev/null; then
-    osascript -e "display notification \"$message\" with title \"$title\" sound name \"Basso\""
+    osascript -e "display notification \"$message\" with title \"$title\" sound name \"Submarine\""
   fi
 
-  # Linux notification (if available)
+  # Linux notification (if available) - use "normal" urgency (not "critical")
+  # Critical urgency can bypass Do Not Disturb, which is too aggressive
   if command -v notify-send &> /dev/null; then
-    notify-send "$title" "$message" --urgency=critical
+    notify-send "$title" "$message" --urgency=normal
   fi
+
+  # Windows: notifications sent via PowerShell toast don't have urgency levels
+  # They're always non-alarming by design
 }
 
 get_file_age_seconds() {

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

@@ -243,7 +243,7 @@ For each US you will generate:
 
 ❌ FORBIDDEN: Skipping this step and generating spec.md directly
 ❌ FORBIDDEN: Inventing project names not in the API output
-❌ FORBIDDEN: Using folder names as project (e.g., "sw-olysense")
+❌ FORBIDDEN: Using folder names as project (e.g., "my-project-folder")
 ❌ FORBIDDEN: Using {{PROJECT_ID}} or {{BOARD_ID}} placeholders
 ❌ FORBIDDEN: Creating spec.md for 2-level without board: field
 ❌ FORBIDDEN: Generating spec.md without running context API first

package/plugins/specweave-docs/commands/build.md

@@ -52,7 +52,7 @@ if [ ! -d ".specweave/cache/docs-site/node_modules" ]; then
 fi
 ```
 
-If not set up, follow the same setup steps as `/specweave-docs:preview` (Step 3 in preview.md).
+If not set up, follow the same setup steps as `/specweave-docs:view` (Step 3 in view.md).
 
 ### Step 3: Run Build
 
@@ -131,8 +131,8 @@ git commit -m "docs: update documentation site"
 
 ### Build fails with broken links
 ```bash
-# Preview first to find errors
-/specweave-docs:preview
+# View docs first to find errors
+/specweave-docs:view
 # Fix broken links, then build
 /specweave-docs:build
 ```
@@ -155,6 +155,6 @@ rm -rf .specweave/cache/docs-site
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview docs locally with hot reload
+- `/specweave-docs:view` - View docs locally with hot reload
 - `/specweave-docs:organize` - Organize large folders with themed indexes
 - `/specweave-docs:health` - Documentation health report

package/plugins/specweave-docs/commands/generate.md

@@ -408,7 +408,7 @@ cat ./docs/api/index.md ./docs/specs/index.md > ./docs/complete-reference.md
 ## Related Commands
 
 - `/specweave-docs:init` - Initialize Docusaurus documentation site
-- `/specweave-docs:preview` - Preview generated documentation
+- `/specweave-docs:view` - View generated documentation
 - `/specweave-docs:build` - Build static site from generated docs
 
 ## Requirements

package/plugins/specweave-docs/commands/health.md

@@ -264,5 +264,5 @@ jobs:
 ## See Also
 
 - `/specweave-docs:organize` - Organize large folders with themed indexes
-- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:view` - View documentation with Docusaurus
 - `/specweave-docs:generate` - Generate docs from code

package/plugins/specweave-docs/commands/init.md

@@ -309,7 +309,7 @@ themeConfig: {
 ## Related Commands
 
 - `/specweave-docs:generate` - Generate docs from code/specs
-- `/specweave-docs:preview` - Launch documentation preview server
+- `/specweave-docs:view` - Launch documentation server
 - `/specweave-docs:build` - Build static documentation site
 
 ## Requirements

package/plugins/specweave-docs/commands/organize.md

@@ -161,7 +161,7 @@ Generated 9 index files:
 After running this command, use:
 
 ```bash
-/specweave-docs:preview
+/specweave-docs:view
 ```
 
 The generated indexes will appear in the sidebar:
@@ -179,6 +179,6 @@ The generated indexes will appear in the sidebar:
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:view` - View documentation with Docusaurus
 - `/specweave-docs:build` - Build static documentation site
 - `/specweave-docs:health` - Documentation health report

package/plugins/specweave-docs/commands/validate.md

@@ -245,6 +245,6 @@ onBrokenMarkdownLinks: 'warn',
 
 ## See Also
 
-- `/specweave-docs:preview` - Preview docs (runs validation first)
+- `/specweave-docs:view` - View docs (runs validation first)
 - `/specweave-docs:build` - Build docs (runs validation first)
 - `/specweave-docs:health` - Full documentation health report