specweave 0.21.1 → 0.21.3

package/plugins/specweave/lib/hooks/update-tasks-md.ts

@@ -146,20 +146,162 @@ function parseTaskStatus(lines: string[]): TaskMatch[] {
 }
 
 /**
- * Detect which tasks are completed (heuristic-based for now)
- * TODO: In future, hook will pass completed task IDs via env var
+ * Detect which tasks are completed (STRICT VALIDATION)
+ *
+ * Detection strategies (ALL must be true):
+ * 1. Task header has "✅ COMPLETE" marker AND
+ *    all implementation checkboxes are marked [x]
+ * 2. OR: Task header has "Status: [x] Completed" (legacy format)
+ *
+ * This prevents inconsistencies where header says COMPLETE but checkboxes
+ * are unchecked. Both must match for a task to be considered complete.
+ *
+ * @see .specweave/increments/0037/reports/ULTRATHINK-COMPLETE-MARKER-VS-CHECKBOXES.md
  */
 function detectCompletedTasks(lines: string[]): string[] {
-  // For now, this is a placeholder - we'll mark tasks as complete
-  // if they have implementation sections or "COMPLETE" markers
   const completedTasks: string[] = [];
+  const warnings: string[] = [];
+  const taskPattern = /^###\s+(T-\d+[-A-Z]*):?\s+(.+)/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const taskMatch = line.match(taskPattern);
+
+    if (!taskMatch) continue;
+
+    const taskId = taskMatch[1];
+    const taskTitle = taskMatch[2];
+    const hasCompleteMarker = taskTitle.includes('✅ COMPLETE');
 
-  // This function will be enhanced in future versions
-  // For MVP, we'll rely on manual marking in tasks.md
+    // Get implementation section
+    const taskEndIndex = findNextTaskStart(lines, i + 1);
+    const implementationSection = findImplementationSection(lines, i, taskEndIndex);
+
+    let allCheckboxesComplete = false;
+    if (implementationSection) {
+      allCheckboxesComplete = checkAllCheckboxesComplete(implementationSection);
+    }
+
+    // STRICT VALIDATION: Require BOTH header AND checkboxes to match
+    if (hasCompleteMarker && implementationSection) {
+      if (allCheckboxesComplete) {
+        // ✅ CONSISTENT: Header says COMPLETE and all checkboxes checked
+        if (!completedTasks.includes(taskId)) {
+          completedTasks.push(taskId);
+        }
+      } else {
+        // ⚠️  INCONSISTENT: Header says COMPLETE but checkboxes incomplete
+        warnings.push(`${taskId}: Header has ✅ COMPLETE but not all checkboxes checked`);
+      }
+      continue;
+    }
+
+    // If no implementation section, trust the header marker
+    if (hasCompleteMarker && !implementationSection) {
+      if (!completedTasks.includes(taskId)) {
+        completedTasks.push(taskId);
+      }
+      continue;
+    }
+
+    // Warn if checkboxes all complete but header missing marker
+    if (!hasCompleteMarker && implementationSection && allCheckboxesComplete) {
+      warnings.push(`${taskId}: All checkboxes checked but header missing ✅ COMPLETE`);
+      // Still count as complete (checkboxes are source of truth for work done)
+      if (!completedTasks.includes(taskId)) {
+        completedTasks.push(taskId);
+      }
+      continue;
+    }
+
+    // Strategy 2: Check for "Status: [x] Completed" (legacy format)
+    for (let j = i + 1; j < Math.min(i + 10, taskEndIndex); j++) {
+      const statusLine = lines[j];
+      if (statusLine.includes('**Status**:') && statusLine.includes('[x] Completed')) {
+        if (!completedTasks.includes(taskId)) {
+          completedTasks.push(taskId);
+        }
+        break;
+      }
+    }
+  }
+
+  // Report warnings if any
+  if (warnings.length > 0) {
+    console.warn('\n⚠️  Task Consistency Warnings:');
+    warnings.forEach(w => console.warn(`   ${w}`));
+    console.warn('');
+  }
 
   return completedTasks;
 }
 
+/**
+ * Find the next task header start index
+ */
+function findNextTaskStart(lines: string[], startIndex: number): number {
+  const taskPattern = /^###\s+T-\d+/;
+
+  for (let i = startIndex; i < lines.length; i++) {
+    if (taskPattern.test(lines[i])) {
+      return i;
+    }
+  }
+
+  return lines.length;
+}
+
+/**
+ * Find the Implementation section within a task
+ */
+function findImplementationSection(lines: string[], taskStartIndex: number, taskEndIndex: number): string[] | null {
+  let inImplementation = false;
+  const implementationLines: string[] = [];
+
+  for (let i = taskStartIndex; i < taskEndIndex; i++) {
+    const line = lines[i];
+
+    if (line.includes('**Implementation**:')) {
+      inImplementation = true;
+      continue;
+    }
+
+    if (inImplementation) {
+      // Stop at next section header (**, ---, or ###)
+      if (line.trim().startsWith('**') && !line.startsWith('- [')) {
+        break;
+      }
+      if (line.trim().startsWith('---')) {
+        break;
+      }
+      if (line.trim().startsWith('###')) {
+        break;
+      }
+
+      implementationLines.push(line);
+    }
+  }
+
+  return implementationLines.length > 0 ? implementationLines : null;
+}
+
+/**
+ * Check if all checkboxes in implementation section are complete
+ */
+function checkAllCheckboxesComplete(implementationLines: string[]): boolean {
+  const checkboxes = implementationLines.filter(line => line.includes('- ['));
+
+  if (checkboxes.length === 0) {
+    return false; // No checkboxes = can't determine completion
+  }
+
+  // All checkboxes must be [x], none can be [ ]
+  const allComplete = checkboxes.every(line => line.includes('- [x]'));
+  const noneIncomplete = checkboxes.every(line => !line.includes('- [ ]'));
+
+  return allComplete && noneIncomplete;
+}
+
 /**
  * Mark a specific task as complete
  */
@@ -195,22 +337,52 @@ function countTotalTasks(lines: string[]): number {
 
 /**
  * Count completed tasks
+ *
+ * Recognizes multiple completion indicators:
+ * 1. "✅ COMPLETE" marker in task header
+ * 2. "**Status**: [x] Completed" line
+ * 3. All implementation checkboxes marked [x]
  */
 function countCompletedTasks(lines: string[]): number {
   let count = 0;
-  const taskPattern = /^###\s+(T-?\d+[-A-Z]*):?\s+/;
+  const taskPattern = /^###\s+(T-?\d+[-A-Z]*):?\s+(.+)/;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
-    if (taskPattern.test(line)) {
-      // Look ahead for status line
-      for (let j = i + 1; j < Math.min(i + 5, lines.length); j++) {
+    const taskMatch = line.match(taskPattern);
+
+    if (taskMatch) {
+      const taskTitle = taskMatch[2];
+
+      // Strategy 1: Check for ✅ COMPLETE marker in header
+      if (taskTitle.includes('✅ COMPLETE')) {
+        count++;
+        continue;
+      }
+
+      // Strategy 2: Check for Status: [x] Completed
+      let found = false;
+      for (let j = i + 1; j < Math.min(i + 10, lines.length); j++) {
         const nextLine = lines[j];
         if (nextLine.includes('**Status**:') && nextLine.includes('[x] Completed')) {
           count++;
+          found = true;
           break;
         }
       }
+
+      if (found) continue;
+
+      // Strategy 3: Check if all implementation checkboxes are [x]
+      const taskEndIndex = findNextTaskStart(lines, i + 1);
+      const implementationSection = findImplementationSection(lines, i, taskEndIndex);
+
+      if (implementationSection) {
+        const allCheckboxesComplete = checkAllCheckboxesComplete(implementationSection);
+        if (allCheckboxesComplete) {
+          count++;
+        }
+      }
     }
   }
 

package/plugins/specweave/lib/utils/validate-dev-setup.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+# Lightweight Developer Setup Validator for Hooks
+#
+# This script is sourced by hooks to validate that the marketplace symlink
+# is correctly configured for local development, preventing hook errors.
+#
+# Usage in hooks:
+#   source "$(dirname "$0")/../lib/utils/validate-dev-setup.sh"
+#   validate_marketplace_setup_quiet || exit 0  # Skip hook if setup invalid
+
+# Global variables set by validation
+MARKETPLACE_SETUP_VALID=0
+MARKETPLACE_SETUP_ERROR=""
+
+# Validate marketplace setup (quiet mode - for hooks)
+# Returns: 0 if valid, 1 if invalid
+# Sets: MARKETPLACE_SETUP_VALID, MARKETPLACE_SETUP_ERROR
+validate_marketplace_setup_quiet() {
+  # Only validate in development mode
+  if [[ ! -f "$(git rev-parse --show-toplevel 2>/dev/null)/package.json" ]]; then
+    MARKETPLACE_SETUP_VALID=1
+    return 0  # Not in a repo, assume valid
+  fi
+
+  # Check if we're in the SpecWeave repository
+  local repo_root
+  repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
+    MARKETPLACE_SETUP_VALID=1
+    return 0  # Not in git repo, assume valid
+  }
+
+  if [[ ! -f "$repo_root/package.json" ]]; then
+    MARKETPLACE_SETUP_VALID=1
+    return 0
+  fi
+
+  # Check if this is the SpecWeave repository
+  if ! grep -q '"name": "specweave"' "$repo_root/package.json" 2>/dev/null; then
+    MARKETPLACE_SETUP_VALID=1
+    return 0  # Not SpecWeave repo, assume valid (user project)
+  fi
+
+  # This IS the SpecWeave repository - validate marketplace setup
+  local marketplace_path="$HOME/.claude/plugins/marketplaces/specweave"
+
+  # Check if marketplace exists
+  if [[ ! -e "$marketplace_path" ]]; then
+    MARKETPLACE_SETUP_VALID=0
+    MARKETPLACE_SETUP_ERROR="Marketplace directory does not exist"
+    return 1
+  fi
+
+  # Check if it's a symlink
+  if [[ ! -L "$marketplace_path" ]]; then
+    MARKETPLACE_SETUP_VALID=0
+    MARKETPLACE_SETUP_ERROR="Marketplace is a regular directory, not a symlink"
+    return 1
+  fi
+
+  # Check if symlink points to this repository
+  local symlink_target
+  symlink_target="$(readlink "$marketplace_path")"
+
+  if [[ "$symlink_target" != "$repo_root" ]]; then
+    # Try resolving to absolute path in case symlink is relative
+    local resolved_target
+    resolved_target="$(cd "$(dirname "$marketplace_path")" && cd "$symlink_target" && pwd)" || {
+      MARKETPLACE_SETUP_VALID=0
+      MARKETPLACE_SETUP_ERROR="Symlink target cannot be resolved"
+      return 1
+    }
+
+    if [[ "$resolved_target" != "$repo_root" ]]; then
+      MARKETPLACE_SETUP_VALID=0
+      MARKETPLACE_SETUP_ERROR="Symlink points to wrong repository"
+      return 1
+    fi
+  fi
+
+  # All checks passed
+  MARKETPLACE_SETUP_VALID=1
+  return 0
+}
+
+# Validate marketplace setup (verbose mode - for scripts)
+# Prints detailed error messages
+# Returns: 0 if valid, 1 if invalid
+validate_marketplace_setup_verbose() {
+  if validate_marketplace_setup_quiet; then
+    return 0
+  fi
+
+  # Print error
+  echo "❌ Invalid marketplace setup: $MARKETPLACE_SETUP_ERROR" >&2
+  echo "" >&2
+  echo "Fix by running:" >&2
+  echo "  ./scripts/setup-dev-plugins.sh" >&2
+  echo "" >&2
+  echo "Or manually:" >&2
+  echo "  rm -rf ~/.claude/plugins/marketplaces/specweave" >&2
+  echo "  ln -s \$(pwd) ~/.claude/plugins/marketplaces/specweave" >&2
+  echo "" >&2
+
+  return 1
+}
+
+# Quick check for hooks - returns true if running in user project
+is_user_project() {
+  local repo_root
+  repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 0
+
+  if [[ ! -f "$repo_root/package.json" ]]; then
+    return 0  # No package.json, assume user project
+  fi
+
+  # Check if this is NOT the SpecWeave repository
+  if ! grep -q '"name": "specweave"' "$repo_root/package.json" 2>/dev/null; then
+    return 0  # User project
+  fi
+
+  return 1  # SpecWeave repository
+}
+
+# Print warning about marketplace setup (for hooks)
+warn_marketplace_setup() {
+  if [[ "${SPECWEAVE_SUPPRESS_WARNINGS:-}" == "true" ]]; then
+    return 0
+  fi
+
+  echo "⚠️  Warning: Marketplace setup issue detected" >&2
+  echo "   Run: ./scripts/validate-local-dev-setup.sh" >&2
+  echo "" >&2
+}

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

@@ -230,7 +230,9 @@ const teamPath = projectManager.getTeamPath();  // team/{activeProject.id}/
 **In PM Agent Instructions**:
 - DO NOT hardcode `.specweave/docs/internal/specs/`
 - USE ProjectManager to get correct path for active project
-- Specs go to: `{projectManager.getSpecsPath()}/spec-{number}-{name}.md`
+- Living docs are created via `/specweave:sync-docs update` (not manually):
+  - Feature overviews: `.specweave/docs/internal/specs/_features/FS-{number}/FEATURE.md`
+  - User stories: `.specweave/docs/internal/specs/{project}/FS-{number}/us-{id}-{slug}.md`
 
 ---
 
@@ -271,9 +273,10 @@ Task(
   You MUST create living Spec (living docs - source of truth) AND optionally create increment spec.md:
 
   1. Spec (living docs - SOURCE OF TRUTH, permanent):
-     - IMPORTANT: Use ProjectManager to get correct path for active project
-     - Create at: {projectManager.getSpecsPath()}/spec-{number}-{name}.md
-       (This resolves to specs/{activeProject}/ with FLATTENED structure v0.16.11+)
+     - IMPORTANT: Living docs are created via `/specweave:sync-docs update` (not manually)
+     - Structure (v0.18.0+ - three-layer architecture):
+       * Feature overview: `.specweave/docs/internal/specs/_features/FS-{number}/FEATURE.md`
+       * User stories: `.specweave/docs/internal/specs/{project}/FS-{number}/us-*.md`
      - This is the COMPLETE, PERMANENT source of truth
      - Include ALL of:
        * User stories (US-001, US-002, etc.) with full details
@@ -300,7 +303,7 @@ Task(
   3. Increment spec.md (optional, can duplicate living spec):
      - Create .specweave/increments/{number}-{name}/spec.md
      - This CAN duplicate content from living spec.md (temporary reference - that's OK!)
-     - OR it can just reference the spec: \"See SPEC-{number}-{name} for complete requirements\"
+     - OR it can just reference the spec: \"See [FS-{number}](../../docs/internal/specs/_features/FS-{number}/FEATURE.md) for complete requirements\"
      - Increment spec.md may be deleted after increment completes
      - Living spec.md persists as permanent documentation
 
@@ -379,7 +382,7 @@ Task(
 Wait for test-aware-planner agent to complete!
     ↓
 STEP 6: Validate Living Docs and Increment Files
-├─ Check .specweave/docs/internal/specs/spec-{number}-{name}/spec.md exists (SOURCE OF TRUTH)
+├─ Check `.specweave/docs/internal/specs/_features/FS-{number}/FEATURE.md` exists (SOURCE OF TRUTH)
 ├─ Check living spec.md contains ALL user stories, requirements, AC-IDs (with AC-IDs)
 ├─ Check .specweave/docs/internal/architecture/adr/ has ≥3 ADRs
 ├─ Check strategy docs (if created) are high-level only (no detailed user stories)
@@ -395,19 +398,26 @@ STEP 6: Validate Living Docs and Increment Files
 
 #### Living Spec (Living Docs - Source of Truth) ✅
 ```
-.specweave/docs/internal/specs/{project-id}/  # ← FLATTENED structure (v0.16.11+)
-└── spec-{number}-{name}.md          # ← PM Agent (MANDATORY)
+.specweave/docs/internal/specs/
+├── _features/                       # ← Cross-project feature overviews (v0.18.0+)
+│   └── FS-{number}/
+│       └── FEATURE.md               # ← Feature summary (created via sync-docs)
+└── {project-id}/                    # ← Project-specific user stories
+    └── FS-{number}/
+        ├── README.md                # ← Project context
+        └── us-*.md                  # ← User story details (created via sync-docs)
                                      # COMPLETE user stories, AC, requirements
                                      # This is the PERMANENT source of truth
                                      # Can be linked to Jira/ADO/GitHub Issues
                                      # Persists after increment completes
 
-# Examples (v0.16.11+ Flattened):
-# Single project: specs/default/spec-001-user-auth.md
-# Multi-project: specs/web-app/spec-001-user-auth.md
-#                specs/mobile/spec-001-push-notifications.md
-# Parent repo:   specs/_parent/spec-002-system-architecture.md
+# Examples (v0.18.0+ Three-Layer):
+# Feature overview: specs/_features/FS-001/FEATURE.md
+# User stories: specs/specweave/FS-001/us-001-user-auth.md, us-002-password-reset.md
+#               specs/mobile/FS-002/us-001-push-notifications.md
+#               specs/backend/FS-003/us-001-api-auth.md
 
+# OLD (v0.17.x): specs/{project}/spec-{number}-{name}.md ← DEPRECATED
 # OLD (v0.8.0-v0.16.10): projects/default/specs/... ← DEPRECATED
 ```
 
@@ -465,7 +475,7 @@ STEP 6: Validate Living Docs and Increment Files
 Before completing feature planning, verify:
 
 **Living Spec (Living Docs - Source of Truth, Mandatory)**:
-- [ ] `.specweave/docs/internal/specs/spec-{number}-{name}/spec.md` exists
+- [ ] `.specweave/docs/internal/specs/_features/FS-{number}/FEATURE.md` exists (created via sync-docs)
 - [ ] Living spec.md contains ALL user stories (US-001, US-002, etc.) with full details
 - [ ] Living spec.md contains ALL acceptance criteria (AC-US1-01, etc.)
 - [ ] Living spec.md contains ALL requirements (FR-001, NFR-001, etc.)
@@ -485,7 +495,7 @@ Before completing feature planning, verify:
 - [ ] Diagrams created for module (system-context, system-container)
 
 **Increment spec.md (Optional - can duplicate living spec)**:
-- [ ] `spec.md` either duplicates living spec.md OR references it ("See SPEC-{number}-{name}")
+- [ ] `spec.md` either duplicates living spec.md OR references it ("See [FS-{number}](../../docs/internal/specs/_features/FS-{number}/FEATURE.md)")
 - [ ] If duplicated, content matches living spec.md
 
 **Increment plan.md (Mandatory)**: