specweave 0.21.2 → 0.22.0

package/plugins/specweave/commands/specweave-sync-acs.md

@@ -0,0 +1,342 @@
+---
+name: specweave:sync-acs
+description: Manually synchronize acceptance criteria (AC) checkbox status in spec.md based on task completion
+---
+
+# Sync Acceptance Criteria Status
+
+**Purpose**: Manually trigger AC checkbox synchronization to ensure spec.md acceptance criteria accurately reflect task completion status.
+
+**Use When**:
+- AC checkboxes in spec.md are out of sync with completed tasks
+- After manually completing tasks without running the hook
+- To verify AC status before closing an increment
+- To resolve conflicts between manual AC edits and task completion
+
+---
+
+## How It Works
+
+1. **Detect Active Increment**
+   - Find increment in-progress
+   - Check if spec.md and tasks.md exist
+
+2. **Parse Task Completion**
+   - Extract all tasks from tasks.md
+   - Map AC-IDs to completion status
+   - Calculate percentage complete per AC (# complete tasks / # total tasks)
+
+3. **Parse AC Definitions**
+   - Extract all ACs from spec.md
+   - Track current checkbox state ([ ] or [x])
+   - Map line numbers for atomic updates
+
+4. **Intelligent Sync Logic**
+   - **100% Complete**: Update [ ] → [x]
+   - **< 100% Complete**: Keep [ ] (partial work)
+   - **Conflict Detection**: AC is [x] but tasks incomplete → WARN
+   - **Orphaned ACs**: AC has no implementing tasks → WARN
+
+5. **Atomic File Update**
+   - Update spec.md only if changes needed
+   - Preserve manual overrides (conflicts)
+   - Log all changes to metadata.json
+
+---
+
+## Usage
+
+```bash
+# Auto-detect and sync active increment
+/specweave:sync-acs
+
+# Sync specific increment
+/specweave:sync-acs 0039
+
+# Show what would change (dry run)
+/specweave:sync-acs --dry-run
+
+# Force sync (ignore conflicts)
+/specweave:sync-acs --force
+
+# Validate only (check for mismatches)
+/specweave:sync-acs --validate
+```
+
+---
+
+## Implementation
+
+The command uses **ACStatusManager** for sophisticated synchronization:
+
+```typescript
+import { ACStatusManager } from '../../../../../src/core/increment/ac-status-manager';
+
+const manager = new ACStatusManager(process.cwd());
+const result = await manager.syncACStatus(incrementId);
+
+// result.synced: true if sync was performed
+// result.updated: string[] - AC-IDs updated to [x]
+// result.conflicts: string[] - Conflicts detected
+// result.warnings: string[] - Orphaned ACs, missing files
+// result.changes: string[] - Human-readable diff
+```
+
+### Step 1: Find Active Increment
+
+```bash
+# Auto-detect active increment
+ACTIVE_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog\|_archive" | head -1)
+
+if [[ -z "$ACTIVE_INCREMENT" ]]; then
+    echo "❌ No active increment found"
+    exit 1
+fi
+
+echo "🔄 Syncing AC status for $ACTIVE_INCREMENT..."
+```
+
+### Step 2: Call ACStatusManager
+
+```bash
+# Use the update-ac-status.js hook script (already integrated)
+node plugins/specweave/lib/hooks/update-ac-status.js "$ACTIVE_INCREMENT"
+```
+
+Or invoke directly:
+
+```typescript
+const result = await manager.syncACStatus(incrementId);
+```
+
+### Step 3: Display Results
+
+```bash
+# Updated ACs
+if [[ -n "${result.updated}" ]]; then
+    echo "✅ Updated AC checkboxes:"
+    for acId in "${result.updated[@]}"; do
+        echo "   $acId → [x]"
+    done
+fi
+
+# Conflicts
+if [[ -n "${result.conflicts}" ]]; then
+    echo "⚠️  Conflicts detected:"
+    for conflict in "${result.conflicts[@]}"; do
+        echo "   $conflict"
+    done
+fi
+
+# Warnings
+if [[ -n "${result.warnings}" ]]; then
+    echo "⚠️  Warnings:"
+    for warning in "${result.warnings[@]}"; do
+        echo "   $warning"
+    done
+fi
+```
+
+---
+
+## Example Scenarios
+
+### Scenario 1: Normal Sync (100% Complete AC)
+
+**Before**:
+```markdown
+# spec.md
+- [ ] AC-US1-01: User can login
+- [ ] AC-US1-02: Session persists
+
+# tasks.md
+#### T-001: Implement login API
+**AC**: AC-US1-01
+**Status**: [x] (100% - Completed)
+
+#### T-002: Add session storage
+**AC**: AC-US1-01
+**Status**: [x] (100% - Completed)
+```
+
+**After**:
+```markdown
+# spec.md
+- [x] AC-US1-01: User can login  ✓ UPDATED
+- [ ] AC-US1-02: Session persists
+```
+
+**Output**:
+```
+🔄 Syncing AC status for increment 0039...
+
+✅ Updated AC checkboxes:
+   AC-US1-01 → [x]
+
+📝 Changes:
+   AC-US1-01: [ ] → [x] (2/2 tasks complete - 100%)
+```
+
+---
+
+### Scenario 2: Partial Completion (No Update)
+
+**Before**:
+```markdown
+# spec.md
+- [ ] AC-US1-02: Session persists
+
+# tasks.md
+#### T-003: Add Redis session store
+**AC**: AC-US1-02
+**Status**: [x] (100% - Completed)
+
+#### T-004: Test session expiry
+**AC**: AC-US1-02
+**Status**: [ ] (0% - Not started)
+```
+
+**After**:
+```markdown
+# spec.md
+- [ ] AC-US1-02: Session persists  (NO CHANGE - 50% complete)
+```
+
+**Output**:
+```
+🔄 Syncing AC status for increment 0039...
+
+ℹ️  No AC updates needed
+
+📊 Completion Status:
+   AC-US1-02: 1/2 tasks complete (50%) - threshold not met
+```
+
+---
+
+### Scenario 3: Conflict Detection
+
+**Before**:
+```markdown
+# spec.md
+- [x] AC-US1-03: Data validated (manually checked)
+
+# tasks.md
+#### T-005: Add validation rules
+**AC**: AC-US1-03
+**Status**: [x] (100% - Completed)
+
+#### T-006: Add error handling
+**AC**: AC-US1-03
+**Status**: [ ] (0% - Not started)
+```
+
+**After**:
+```markdown
+# spec.md
+- [x] AC-US1-03: Data validated (PRESERVED - conflict detected)
+```
+
+**Output**:
+```
+🔄 Syncing AC status for increment 0039...
+
+⚠️  Conflicts detected:
+   AC-US1-03: Marked [x] but only 1/2 tasks complete (50%)
+   → Manual override preserved (no change made)
+
+💡 Tip: Review tasks for AC-US1-03 or uncheck manually if premature
+```
+
+---
+
+### Scenario 4: Orphaned AC Warning
+
+**Before**:
+```markdown
+# spec.md
+- [ ] AC-US1-04: Performance optimized
+- [ ] AC-US1-05: Security hardened
+
+# tasks.md
+#### T-007: Implement caching
+**AC**: AC-US1-04
+**Status**: [x] (100% - Completed)
+
+(No tasks reference AC-US1-05)
+```
+
+**Output**:
+```
+🔄 Syncing AC status for increment 0039...
+
+✅ Updated AC checkboxes:
+   AC-US1-04 → [x]
+
+⚠️  Warnings:
+   AC-US1-05: No implementing tasks found (orphaned AC)
+   → Add tasks or remove AC from spec.md
+```
+
+---
+
+## Integration with Hooks
+
+### Automatic Sync (Post-Task-Completion Hook)
+
+The hook automatically calls `ACStatusManager.syncACStatus()` after every task completion:
+
+```bash
+# plugins/specweave/hooks/post-task-completion.sh (lines 232-269)
+if [ -n "$CURRENT_INCREMENT" ]; then
+    node plugins/specweave/lib/hooks/update-ac-status.js "$CURRENT_INCREMENT"
+fi
+```
+
+**Disable automatic sync**:
+```bash
+export SKIP_AC_SYNC=true
+# Now hooks won't sync ACs (useful for batch work)
+```
+
+---
+
+## Integration with Other Commands
+
+### /specweave:validate
+```bash
+# Validate ACs before closing increment
+/specweave:sync-acs --validate
+# Warns if ACs out of sync
+```
+
+### /specweave:done
+```bash
+# Auto-sync ACs before closing
+/specweave:sync-acs
+# Then proceed with increment closure
+```
+
+### /specweave:progress
+```bash
+# Show AC completion alongside task progress
+/specweave:sync-acs --status
+# Display: 8/10 ACs complete (80%)
+```
+
+---
+
+## Success Criteria
+
+- ✅ Syncs AC checkboxes based on task completion (100% threshold)
+- ✅ Detects and preserves manual overrides (conflicts)
+- ✅ Warns about orphaned ACs (no implementing tasks)
+- ✅ Shows clear diff of changes before/after
+- ✅ Atomic file writes (no corruption risk)
+- ✅ Integrates with post-task-completion hook
+- ✅ Supports dry-run mode
+- ✅ Logs all changes to metadata.json
+
+---
+
+**This command ensures acceptance criteria accurately reflect implementation progress!**

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

@@ -57,25 +57,49 @@ Usage: /specweave:validate-increment <id> [--quality] [--export] [--fix] [--alwa
 
 ### Step 2: Run Rule-Based Validation (Always)
 
-Run 120 validation rules across 4 categories:
-
-1. **Consistency Rules (47 checks)**:
+Run 130+ validation rules across 6 categories:
+
+**CRITICAL: Always run structure validation FIRST to prevent duplicate task files**
+
+1. **Structure Rules (5 checks)** - v0.18.4:
+   - Only ONE tasks.md file exists (no tasks-detailed.md, tasks-final.md)
+   - Only allowed root files present (spec.md, plan.md, tasks.md, metadata.json, README.md)
+   - Unknown files moved to subdirectories (reports/, scripts/, logs/)
+   - No root-level pollution (analysis.md, summary.md moved to reports/)
+   - Metadata.json structure valid
+
+2. **Three-File Canonical Structure (10 checks)** - ADR-0047 (v0.21.3):
+   - **tasks.md validations (CRITICAL)**:
+     - ❌ Does NOT contain "**Acceptance Criteria**:" sections
+     - ✅ MUST have "**Implementation**:" sections for each task
+     - ✅ MUST have "**Test Plan (BDD)**" sections
+     - ✅ MUST have **AC-IDs** references linking to spec.md
+     - ❌ Does NOT contain "As a user..." user story language
+   - **spec.md validations**:
+     - ❌ Does NOT contain task IDs (T-001, T-002, etc.)
+     - ❌ Does NOT contain technical class/file names
+     - ✅ MUST have "## Acceptance Criteria" section
+   - **plan.md validations**:
+     - ❌ Does NOT contain "Acceptance Criteria" sections
+     - ❌ Does NOT contain task checkboxes
+
+3. **Consistency Rules (47 checks)**:
    - User stories in spec.md → sections in plan.md
    - Components in plan.md → tasks in tasks.md
    - Test cases (TC-0001) in spec.md → tests.md coverage
    - Cross-document consistency (IDs, priorities, dependencies)
 
-2. **Completeness Rules (23 checks)**:
+4. **Completeness Rules (23 checks)**:
    - spec.md: Frontmatter, problem statement, user stories, acceptance criteria
    - plan.md: Architecture, components, data model, API contracts, security
    - tasks.md: Task IDs, descriptions, priorities, estimates
 
-3. **Quality Rules (31 checks)**:
+5. **Quality Rules (31 checks)**:
    - spec.md: Technology-agnostic, testable acceptance criteria
    - plan.md: Technical details, ADRs exist, security addressed
    - tasks.md: Actionable, reasonable estimates (<1 day)
 
-4. **Traceability Rules (19 checks)**:
+6. **Traceability Rules (19 checks)**:
    - TC-0001 format, sequential numbering
    - ADR references exist
    - Diagram references valid
@@ -86,7 +110,9 @@ Run 120 validation rules across 4 categories:
 VALIDATION RESULTS: Increment 0001-authentication
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-✅ Rule-Based Validation: PASSED (120/120 checks)
+✅ Rule-Based Validation: PASSED (135/135 checks)
+   ✓ Structure (5/5)
+   ✓ Three-File Canonical (10/10) [ADR-0047]
    ✓ Consistency (47/47)
    ✓ Completeness (23/23)
    ✓ Quality (31/31)
@@ -103,12 +129,30 @@ Files validated:
 
 **If errors found**:
 ```
-❌ Rule-Based Validation: FAILED (115/120 checks)
+❌ Rule-Based Validation: FAILED (122/135 checks)
+   ❌ Structure (3/5) - 2 CRITICAL ERRORS
+   ❌ Three-File Canonical (7/10) - 3 CRITICAL ERRORS [ADR-0047]
    ✓ Consistency (45/47) - 2 errors
    ✓ Completeness (23/23)
    ⚠️  Quality (28/31) - 3 warnings
    ✓ Traceability (19/19)
 
+CRITICAL STRUCTURE ERRORS (MUST FIX FIRST):
+  ❌ Duplicate task files detected: tasks.md, tasks-detailed.md
+     → Only ONE tasks.md allowed per increment
+     → Move tasks-detailed.md to reports/tasks-detailed.md
+  ❌ Unknown root-level file: analysis.md
+     → Move to reports/ directory
+
+CRITICAL THREE-FILE VIOLATIONS (ADR-0047):
+  🚨 tasks.md:45 - Contains "**Acceptance Criteria**:" section
+     → ACs belong in spec.md ONLY
+     → Replace with "**Implementation**:" and add AC-ID references
+  🚨 tasks.md:78 - Task T-003 missing "**Implementation**:" section
+     → Add checkable implementation steps
+  🚨 spec.md:102 - Contains task ID reference "T-001"
+     → Tasks belong in tasks.md, use AC-IDs to link instead
+
 ERRORS (2):
   🔴 spec.md:45 - Missing acceptance criteria for US-003
   🔴 Inconsistency: spec.md mentions "real-time updates" but plan.md doesn't address it
@@ -119,9 +163,14 @@ WARNINGS (3):
   🟡 ADR-0005 referenced but doesn't exist (plan.md:89)
 
 Action required:
-1. Fix missing acceptance criteria for US-003
-2. Address "real-time updates" in plan.md or remove from spec.md
-3. Consider breaking down T012 into smaller tasks
+1. ❗ FIX STRUCTURE ERRORS FIRST (single source of truth violation)
+2. 🚨 FIX THREE-FILE VIOLATIONS (ADR-0047 compliance):
+   - Run refactoring script: .specweave/increments/XXXX/scripts/refactor-tasks-ac-to-implementation.sh
+   - Or manually replace "**Acceptance Criteria**:" with "**Implementation**:"
+   - Add "**AC-IDs**: AC-US-XX-YY" references to link tasks to spec.md
+3. Fix missing acceptance criteria for US-003
+4. Address "real-time updates" in plan.md or remove from spec.md
+5. Consider breaking down T012 into smaller tasks
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -89,16 +89,20 @@ if [[ -f "$TASKS_FILE" ]]; then
   TOTAL_TASKS=$(grep -cE '^##+ T-' "$TASKS_FILE" 2>/dev/null || echo 0)
   TOTAL_TASKS=$(echo "$TOTAL_TASKS" | tr -d '\n\r ' || echo 0)
 
-  # Count completed tasks (both checkbox formats)
-  # Format 1: [x] at line start
+  # Count completed tasks (multiple formats)
+  # Format 1: [x] at line start (legacy)
   COMPLETED_STANDARD=$(grep -c '^\[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
   COMPLETED_STANDARD=$(echo "$COMPLETED_STANDARD" | tr -d '\n\r ' || echo 0)
 
-  # Format 2: **Status**: [x] inline
+  # Format 2: **Status**: [x] inline (legacy)
   COMPLETED_INLINE=$(grep -c '\*\*Status\*\*: \[x\]' "$TASKS_FILE" 2>/dev/null || echo 0)
   COMPLETED_INLINE=$(echo "$COMPLETED_INLINE" | tr -d '\n\r ' || echo 0)
 
-  COMPLETED_TASKS=$((COMPLETED_STANDARD + COMPLETED_INLINE))
+  # Format 3: **Completed**: <date> (current format)
+  COMPLETED_DATE=$(grep -c '\*\*Completed\*\*:' "$TASKS_FILE" 2>/dev/null || echo 0)
+  COMPLETED_DATE=$(echo "$COMPLETED_DATE" | tr -d '\n\r ' || echo 0)
+
+  COMPLETED_TASKS=$((COMPLETED_STANDARD + COMPLETED_INLINE + COMPLETED_DATE))
 
   # Calculate percentage
   if [[ $TOTAL_TASKS -gt 0 ]]; then

package/plugins/specweave/hooks/post-increment-change.sh

@@ -90,5 +90,9 @@ node dist/plugins/specweave-github/lib/github-sync-increment-changes.js "$INCREM
 
 echo "[$(date)] ✅ Post-increment-change hook complete" >> "$DEBUG_LOG" 2>/dev/null || true
 
+# Update status line cache (increment changed)
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
 # Return success (non-blocking)
 exit 0

package/plugins/specweave/hooks/post-increment-completion.sh

@@ -37,7 +37,9 @@ fi
 ISSUE_NUMBER=$(jq -r '.github.issue // empty' "$METADATA_FILE" 2>/dev/null)
 
 if [ -z "$ISSUE_NUMBER" ] || [ "$ISSUE_NUMBER" = "null" ]; then
-  # No GitHub issue linked - skip
+  # No GitHub issue linked - skip GitHub closure but still update status line
+  HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
   exit 0
 fi
 
@@ -80,4 +82,8 @@ gh issue close "$ISSUE_NUMBER" --comment "$COMPLETION_COMMENT" 2>/dev/null || {
 
 echo "✅ GitHub issue #$ISSUE_NUMBER closed successfully"
 
+# Update status line cache (increment no longer open)
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
 exit 0

package/plugins/specweave/hooks/post-increment-planning.sh

@@ -896,5 +896,9 @@ EOF
 # Run main function
 main
 
+# Update status line cache (new increment created)
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
 # Always return success (non-blocking hook)
 exit 0

package/plugins/specweave/hooks/post-increment-status-change.sh

@@ -139,5 +139,9 @@ echo "$COMMENT" | gh issue comment "$GITHUB_ISSUE" --body-file - 2>&1 | tee -a "
 
 echo "[$(date)] ✅ Status change synced to GitHub" >> "$DEBUG_LOG" 2>/dev/null || true
 
+# Update status line cache (status changed - may affect which increment is "current")
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$HOOK_DIR/lib/update-status-line.sh" 2>/dev/null || true
+
 # Return success (non-blocking)
 exit 0

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

@@ -197,6 +197,84 @@ if echo "$PROMPT" | grep -qE "/(specweave:)?(done|validate|progress|do)"; then
   fi
 fi
 
+# ==============================================================================
+# SPEC SYNC CHECK: Detect spec.md changes and warn about sync needed
+# ==============================================================================
+
+# Check if spec.md was modified after plan.md (requires sync)
+if [[ -d ".specweave/increments" ]]; then
+  # Find active increment
+  ACTIVE_INCREMENT_FOR_SYNC=$(find .specweave/increments -mindepth 1 -maxdepth 1 -type d | while read increment_dir; do
+    metadata="$increment_dir/metadata.json"
+    if [[ -f "$metadata" ]]; then
+      status=$(node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync('$metadata', 'utf-8'));
+          if (data.status === 'active') {
+            console.log('$(basename "$increment_dir")');
+          }
+        } catch (e) {}
+      " 2>/dev/null)
+
+      if [[ -n "$status" ]]; then
+        echo "$status"
+        break
+      fi
+    fi
+  done)
+
+  if [[ -n "$ACTIVE_INCREMENT_FOR_SYNC" ]]; then
+    # Check if SpecSyncManager detects changes
+    if command -v node >/dev/null 2>&1 && [[ -f "dist/src/core/increment/spec-sync-manager.js" ]]; then
+      SYNC_CHECK=$(node -e "
+        try {
+          const { SpecSyncManager } = require('./dist/src/core/increment/spec-sync-manager.js');
+          const manager = new SpecSyncManager(process.cwd());
+          const detection = manager.detectSpecChange('$ACTIVE_INCREMENT_FOR_SYNC');
+
+          if (detection.specChanged) {
+            const message = manager.formatSyncMessage(detection);
+            console.log(JSON.stringify({ needsSync: true, message }));
+          } else {
+            console.log(JSON.stringify({ needsSync: false }));
+          }
+        } catch (e) {
+          console.log(JSON.stringify({ needsSync: false, error: e.message }));
+        }
+      " 2>/dev/null || echo '{"needsSync":false}')
+
+      NEEDS_SYNC=$(echo "$SYNC_CHECK" | node -e "
+        try {
+          const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+          console.log(data.needsSync || false);
+        } catch (e) {
+          console.log(false);
+        }
+      ")
+
+      if [[ "$NEEDS_SYNC" == "true" ]]; then
+        SYNC_MESSAGE=$(echo "$SYNC_CHECK" | node -e "
+          try {
+            const data = JSON.parse(require('fs').readFileSync(0, 'utf-8'));
+            console.log(data.message || '');
+          } catch (e) {
+            console.log('');
+          }
+        ")
+
+        # Show sync warning (don't block, just warn)
+        cat <<EOF
+{
+  "decision": "approve",
+  "systemMessage": "$SYNC_MESSAGE"
+}
+EOF
+        exit 0
+      fi
+    fi
+  fi
+fi
+
 # ==============================================================================
 # CONTEXT INJECTION: Add current increment status
 # ==============================================================================