specweave 0.30.16 → 0.30.17

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

@@ -0,0 +1,111 @@
+#!/bin/bash
+#
+# spec-project-validator.sh
+#
+# Pre-tool-use hook that validates spec.md has required project/board fields
+# 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
+#
+# Returns exit code 1 (block) if validation fails, 0 (allow) otherwise.
+
+set -e
+
+# Read tool input from stdin
+INPUT=$(cat)
+
+# Extract tool name
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only validate Write tool calls
+if [ "$TOOL_NAME" != "Write" ]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract file path
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only validate spec.md files in increments folder
+if [[ ! "$FILE_PATH" =~ \.specweave/increments/[0-9]{4}-[^/]+/spec\.md$ ]]; then
+  echo '{"decision": "allow"}'
+  exit 0
+fi
+
+# Extract file content
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // ""')
+
+# Check if content has YAML frontmatter
+if [[ ! "$CONTENT" =~ ^---$'\n' ]]; then
+  echo '{"decision": "block", "reason": "spec.md must have YAML frontmatter (starting with ---)"}'
+  exit 0
+fi
+
+# Extract YAML frontmatter
+FRONTMATTER=$(echo "$CONTENT" | sed -n '/^---$/,/^---$/p' | tail -n +2 | head -n -1)
+
+# Check for unresolved project placeholder
+if echo "$FRONTMATTER" | grep -q 'project:\s*{{PROJECT_ID}}'; then
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{PROJECT_ID}}. Run STEP 0B to select project before creating spec.md."}'
+  exit 0
+fi
+
+# Check for unresolved board placeholder
+if echo "$FRONTMATTER" | grep -q 'board:\s*{{BOARD_ID}}'; then
+  echo '{"decision": "block", "reason": "spec.md has unresolved placeholder {{BOARD_ID}}. Run STEP 0B to select board before creating spec.md."}'
+  exit 0
+fi
+
+# Check for project field
+PROJECT=$(echo "$FRONTMATTER" | grep -E '^project:\s*' | sed 's/^project:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
+
+# Detect structure level by checking config
+PROJECT_ROOT="${FILE_PATH%%/.specweave/*}"
+CONFIG_PATH="$PROJECT_ROOT/.specweave/config.json"
+
+IS_2_LEVEL=false
+
+if [ -f "$CONFIG_PATH" ]; then
+  # Check for ADO area path mapping (indicates 2-level)
+  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping.mappings | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
+    IS_2_LEVEL=true
+  fi
+
+  # Check for ADO areaPaths (indicates 2-level)
+  if jq -e '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPaths | length > 0' "$CONFIG_PATH" >/dev/null 2>&1; then
+    IS_2_LEVEL=true
+  fi
+fi
+
+# Validation based on structure level
+if [ "$IS_2_LEVEL" = true ]; then
+  # 2-level: BOTH project AND board required
+  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
+    echo '{"decision": "block", "reason": "spec.md missing required '\''project:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''project: <project_name>'\'' to frontmatter."}'
+    exit 0
+  fi
+
+  BOARD=$(echo "$FRONTMATTER" | grep -E '^board:\s*' | sed 's/^board:\s*//' | tr -d '"'"'" | tr -d '[:space:]')
+
+  if [ -z "$BOARD" ] || [ "$BOARD" = "null" ]; then
+    echo '{"decision": "block", "reason": "spec.md missing required '\''board:'\'' field in YAML frontmatter. This is a 2-level structure - add '\''board: <board_name>'\'' to frontmatter."}'
+    exit 0
+  fi
+else
+  # 1-level: project is strongly recommended (warning, not block)
+  if [ -z "$PROJECT" ] || [ "$PROJECT" = "null" ]; then
+    # For 1-level, we warn but don't block (backward compatibility)
+    echo '{"decision": "allow", "message": "⚠️  spec.md should have '\''project:'\'' field in YAML frontmatter for explicit sync target."}'
+    exit 0
+  fi
+fi
+
+# All validations passed
+echo '{"decision": "allow"}'
+exit 0

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

@@ -176,6 +176,81 @@ echo "Using coverageTarget: $coverageTarget"
 
 **Store these values for use in STEP 4 and STEP 7!**
 
+### STEP 0B: Detect Structure Level & Select Project/Board (MANDATORY!)
+
+**⚠️ CRITICAL: Before generating spec.md, you MUST know the target project (and board for 2-level structures)!**
+
+**Structure Levels:**
+- **1-Level**: `internal/specs/{project}/FS-XXX/` - requires `project` in spec.md
+- **2-Level**: `internal/specs/{project}/{board}/FS-XXX/` - requires BOTH `project` AND `board`
+
+**Detection Logic** (use `src/utils/structure-level-detector.ts`):
+
+```typescript
+import { detectStructureLevel, getRequiredSpecFields } from './utils/structure-level-detector.js';
+
+const structureConfig = detectStructureLevel(projectRoot);
+console.log(`Structure level: ${structureConfig.level}`);
+console.log(`Detection reason: ${structureConfig.detectionReason}`);
+console.log(`Available projects: ${structureConfig.projects.map(p => p.id).join(', ')}`);
+
+if (structureConfig.level === 2 && structureConfig.boardsByProject) {
+  console.log('Available boards by project:');
+  for (const [projectId, boards] of Object.entries(structureConfig.boardsByProject)) {
+    console.log(`  ${projectId}: ${boards.map(b => b.id).join(', ')}`);
+  }
+}
+```
+
+**Manual Detection:**
+```bash
+# Check if 2-level (ADO area paths or JIRA boards)
+jq '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping' .specweave/config.json
+
+# Check existing folder structure
+ls -la .specweave/docs/internal/specs/*/  # If sub-folders exist (not FS-XXX) → 2-level
+```
+
+**Project/Board Selection (MANDATORY BEFORE STEP 4!):**
+
+1. **For 1-level structure:**
+   - ASK user: "Which project should this increment sync to?"
+   - Options: List from `structureConfig.projects`
+   - Store selected `PROJECT_ID`
+
+2. **For 2-level structure:**
+   - ASK user: "Which project should this increment sync to?"
+   - Then ASK: "Which board/area path within {project}?"
+   - Options: List from `structureConfig.boardsByProject[selectedProject]`
+   - Store BOTH `PROJECT_ID` and `BOARD_ID`
+
+**VALIDATION RULE:**
+```
+❌ FORBIDDEN: Creating spec.md without PROJECT_ID set
+❌ FORBIDDEN: Creating spec.md for 2-level without BOARD_ID set
+❌ FORBIDDEN: Vague increments like "show last git commits" without project context
+✅ REQUIRED: Always know WHERE this increment will sync BEFORE creating spec.md
+```
+
+**Example User Interaction:**
+
+```
+🔍 Detected 2-level structure (ADO area path mapping)
+   Available projects: acme-corp
+
+   📁 Project: acme-corp
+      Boards: clinical-insights, platform-engineering, digital-operations
+
+Which board should this increment sync to?
+> digital-operations
+
+✅ Increment will sync to: internal/specs/acme-corp/digital-operations/FS-XXX/
+```
+
+**Store PROJECT_ID and BOARD_ID for use in STEP 4!**
+
+---
+
 ### STEP 1: Get Next Increment Number
 
 Use helper script:
@@ -207,26 +282,50 @@ mkdir -p .specweave/increments/0021-feature-name
 
 Create `.specweave/increments/0021-feature-name/spec.md`:
 
+**⚠️ CRITICAL: You MUST have PROJECT_ID (and BOARD_ID for 2-level) from STEP 0B before proceeding!**
+
 **⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
 
-#### 4A: Single-Project Template (umbrella.enabled: false)
+#### 4A: Single-Project Template (1-level structure)
 
 **Template File**: `templates/spec-single-project.md`
 
-Replace placeholders: `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`, `{{TEST_MODE}}`, `{{COVERAGE_TARGET}}`
+Replace placeholders:
+- `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`
+- `{{TEST_MODE}}`, `{{COVERAGE_TARGET}}`
+- **`{{PROJECT_ID}}`** ← MANDATORY (from STEP 0B)
 
-#### 4B: Multi-Project Template (umbrella.enabled: true) - USE THIS!
+#### 4B: Multi-Project Template (2-level structure) - USE THIS!
 
 **Template File**: `templates/spec-multi-project.md`
 
-Replace placeholders: `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{PROJECT_FE_ID}}`, `{{PROJECT_BE_ID}}`, `{{PROJECT_SHARED_ID}}`, etc.
+Replace placeholders:
+- `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`
+- **`{{PROJECT_ID}}`** ← MANDATORY (from STEP 0B)
+- **`{{BOARD_ID}}`** ← MANDATORY for 2-level (from STEP 0B)
+- `{{PROJECT_FE_ID}}`, `{{PROJECT_BE_ID}}`, `{{PROJECT_SHARED_ID}}` (for multi-repo)
+
+**Key Rules for spec.md:**
+1. **`project:` field MUST be set in YAML frontmatter** (1-level and 2-level)
+2. **`board:` field MUST be set in YAML frontmatter** (2-level only)
+3. **User stories grouped by project** if multi-project (Frontend, Backend, Shared, etc.)
+4. **User story IDs have project prefix**: `US-FE-001`, `US-BE-001` (multi-project)
+5. **AC-IDs have project prefix**: `AC-FE-US1-01`, `AC-BE-US1-01` (multi-project)
+
+**VALIDATION (spec.md frontmatter):**
+```yaml
+# 1-level structure (REQUIRED):
+project: digital-operations    # ← MUST be set
+
+# 2-level structure (BOTH REQUIRED):
+project: acme-corp             # ← MUST be set
+board: digital-operations      # ← MUST be set
+```
 
-**Key Rules for Multi-Project spec.md:**
-1. **User stories MUST be grouped by project** (Frontend, Backend, Shared, etc.)
-2. **User story IDs MUST have project prefix**: `US-FE-001`, `US-BE-001`, `US-SHARED-001`
-3. **AC-IDs MUST have project prefix**: `AC-FE-US1-01`, `AC-BE-US1-01`
-4. **Each user story MUST have `Related Repo` field**
-5. **Frontmatter MUST include `multi_project: true` and `projects` list**
+**⚠️ FORBIDDEN:**
+- Creating spec.md with `project: {{PROJECT_ID}}` (unresolved placeholder)
+- Creating spec.md for 2-level with `board: {{BOARD_ID}}` (unresolved placeholder)
+- Leaving project/board fields empty or undefined
 
 ### STEP 5: Create plan.md Template
 

package/plugins/specweave/skills/increment-planner/templates/spec-multi-project.md

@@ -8,6 +8,8 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
+project: {{PROJECT_ID}}
+board: {{BOARD_ID}}
 multi_project: true
 projects:
   - id: {{PROJECT_FE_ID}}

package/plugins/specweave/skills/increment-planner/templates/spec-single-project.md

@@ -8,6 +8,7 @@ created: {{DATE}}
 structure: user-stories
 test_mode: {{TEST_MODE}}
 coverage_target: {{COVERAGE_TARGET}}
+project: {{PROJECT_ID}}
 ---
 
 # Feature: {{FEATURE_TITLE}}

package/plugins/specweave/skills/multi-project-spec-mapper/SKILL.md

@@ -95,8 +95,31 @@ US-005: Cross-Platform Data Sync (Mobile)
     └── README.md
 ```
 
+**spec.md YAML Frontmatter (v0.31.0+ MANDATORY)**:
+
+```yaml
+# For 1-level structure (projects only)
+---
+increment: 0001-fitness-tracker-web
+project: FE                      # REQUIRED
+title: "Fitness Tracker Web UI"
+status: planned
+---
+
+# For 2-level structure (projects + boards)
+---
+increment: 0001-fitness-tracker-web
+project: acme-corp               # REQUIRED
+board: digital-operations        # REQUIRED for 2-level
+title: "Fitness Tracker Web UI"
+status: planned
+---
+```
+
+**Detection**: Use `detectStructureLevel()` from `src/utils/structure-level-detector.ts`
+
 **Each spec contains**:
-- Frontmatter with `project: FE` tag
+- YAML frontmatter with `project:` (and `board:` for 2-level) fields - MANDATORY
 - User stories mapped to that project
 - Project-specific acceptance criteria
 - Links to shared infrastructure/requirements

package/plugins/specweave/skills/spec-generator/SKILL.md

@@ -27,6 +27,24 @@ description: Generates comprehensive specifications (spec.md, plan.md, tasks.md
 - **Bug Fix**: Problem statement, root cause, solution, impact analysis
 - **Refactoring**: Current state, proposed changes, benefits, migration plan
 
+**YAML Frontmatter** (v0.31.0+ MANDATORY):
+```yaml
+---
+increment: 0001-feature-name
+title: "Feature Title"
+type: feature
+priority: P1
+status: planned
+created: 2025-12-04
+project: my-project          # REQUIRED - target project for living docs sync
+board: my-board              # REQUIRED for 2-level structures (ADO area paths, JIRA boards)
+---
+```
+
+**Detect Structure Level First** (see `src/utils/structure-level-detector.ts`):
+- 1-level: `project:` field REQUIRED
+- 2-level: `project:` AND `board:` fields REQUIRED
+
 **Core Sections** (Always Present):
 ```markdown
 # Product Specification: [Increment Name]

package/plugins/specweave/skills/specweave-framework/SKILL.md

@@ -30,6 +30,31 @@ An **increment** = a complete feature with:
 
 > **When to skip plan.md**: Bug fixes, simple migrations, hotfixes, and straightforward tasks where spec.md already describes the approach.
 
+### spec.md Mandatory Fields (v0.31.0+)
+
+**CRITICAL**: spec.md YAML frontmatter MUST include project (and board for 2-level structures):
+
+```yaml
+# 1-level structure (single-project or multiProject):
+---
+increment: 0001-feature-name
+project: my-project          # REQUIRED
+---
+
+# 2-level structure (ADO area paths, JIRA boards, umbrella teams):
+---
+increment: 0001-feature-name
+project: acme-corp           # REQUIRED
+board: digital-operations    # REQUIRED for 2-level
+---
+```
+
+**Why?** Ensures increment syncs to correct location in living docs. Without explicit project/board, sync-specs may fail or place specs in wrong folder.
+
+**Detection**: Use `src/utils/structure-level-detector.ts` to determine if 1-level or 2-level structure is needed.
+
+**See**: [ADR-0190](/internal/architecture/adr/0190-spec-project-board-requirement.md)
+
 ### Increment Naming Convention (v0.6.0+)
 
 **CRITICAL RULE**: All increments MUST use descriptive names, not just numbers!

package/plugins/specweave-github/hooks/.specweave/logs/hooks-debug.log

@@ -280,3 +280,17 @@
 [Wed Dec  3 02:07:36 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
 [Wed Dec  3 02:07:36 EST 2025] [GitHub] 🔗 GitHub sync hook fired
 [Wed Dec  3 02:07:36 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:45 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:45 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:45 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:45 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:46 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:46 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:46 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:46 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
+[Thu Dec  4 17:45:55 EST 2025] [GitHub] ⚠️  sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync

package/plugins/specweave-release/hooks/.specweave/logs/dora-tracking.log

@@ -421,3 +421,24 @@
 [2025-12-03 02:07:36] 🎯 Post-Increment-Completion Hook Triggered
 [2025-12-03 02:07:36] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
 [2025-12-03 02:07:36]    Run: npm run build
+[2025-12-04 17:45:45] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:45] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:45]    Run: npm run build
+[2025-12-04 17:45:45] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:45] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:45]    Run: npm run build
+[2025-12-04 17:45:46] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:46] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:46]    Run: npm run build
+[2025-12-04 17:45:46] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:46] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:46]    Run: npm run build
+[2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:55] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:55]    Run: npm run build
+[2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:55] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:55]    Run: npm run build
+[2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
+[2025-12-04 17:45:55] ⚠️  DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
+[2025-12-04 17:45:55]    Run: npm run build