specweave 0.22.3 → 0.22.4

package/plugins/specweave/agents/test-aware-planner/templates/task-non-testable.md.template

@@ -6,6 +6,18 @@
 **Estimate**: {estimate} hours
 **Status**: [ ] pending
 
+**⚠️  SOURCE OF TRUTH REMINDER** (for AI agents):
+```
+When you complete this task:
+1. ✅ Update internal TODO: TodoWrite([{task: "T-{task_number}", status: "completed"}])
+2. ⚠️  IMMEDIATELY update this line: **Status**: [ ] pending → **Status**: [x] completed
+3. ⚠️  IMMEDIATELY update spec.md: - [ ] **AC-{ac_ids}** → - [x] **AC-{ac_ids}**
+4. ✅ Verify both files before moving to next task
+
+NEVER mark internal TODO as complete without updating these source files!
+See CLAUDE.md Rule #7 for details.
+```
+
 **Test Plan**: N/A ({task_type} task)
 
 **Validation**:

package/plugins/specweave/agents/test-aware-planner/templates/task-testable.md.template

@@ -6,6 +6,18 @@
 **Estimate**: {estimate} hours
 **Status**: [ ] pending
 
+**⚠️  SOURCE OF TRUTH REMINDER** (for AI agents):
+```
+When you complete this task:
+1. ✅ Update internal TODO: TodoWrite([{task: "T-{task_number}", status: "completed"}])
+2. ⚠️  IMMEDIATELY update this line: **Status**: [ ] pending → **Status**: [x] completed
+3. ⚠️  IMMEDIATELY update spec.md: - [ ] **AC-{ac_ids}** → - [x] **AC-{ac_ids}**
+4. ✅ Verify both files before moving to next task
+
+NEVER mark internal TODO as complete without updating these source files!
+See CLAUDE.md Rule #7 for details.
+```
+
 **Test Plan**:
 - **Given** {given_condition}
 - **When** {when_action}

package/plugins/specweave/commands/specweave-analyze-standards.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# ---
+# name: specweave-analyze-standards
+# description: Analyze and document coding standards from codebase. Detects naming conventions, import patterns, type usage, and anti-patterns. Generates evidence-based standards documentation with confidence levels. Supports full analysis, drift detection, and standards updates.
+# usage: /specweave:analyze-standards [--drift] [--update] [--verbose]
+# ---
+
+set -e
+
+# Detect project root (where .specweave/ is located)
+PROJECT_ROOT="$(pwd)"
+while [[ ! -d "$PROJECT_ROOT/.specweave" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
+  PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+if [[ ! -d "$PROJECT_ROOT/.specweave" ]]; then
+  echo "❌ Error: Not in a SpecWeave project (no .specweave/ directory found)"
+  exit 1
+fi
+
+cd "$PROJECT_ROOT"
+
+# Parse arguments
+MODE="full"
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --drift)
+      MODE="drift"
+      shift
+      ;;
+    --update)
+      MODE="update"
+      shift
+      ;;
+    --verbose)
+      VERBOSE=true
+      shift
+      ;;
+    *)
+      echo "❌ Unknown option: $1"
+      echo "Usage: /specweave:analyze-standards [--drift] [--update] [--verbose]"
+      exit 1
+      ;;
+  esac
+done
+
+# Ensure governance directory exists
+GOVERNANCE_DIR="$PROJECT_ROOT/.specweave/docs/internal/governance"
+mkdir -p "$GOVERNANCE_DIR"
+
+# Display banner
+echo "🔍 Code Standards Analysis"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+case $MODE in
+  full)
+    echo "Mode: Full Analysis"
+    echo "Output: $GOVERNANCE_DIR/coding-standards-analysis.md"
+    echo ""
+    echo "📊 Analyzing codebase..."
+    echo ""
+
+    # Launch code-standards-detective agent
+    cat <<'AGENT_PROMPT'
+You are the code-standards-detective agent. Perform a complete coding standards analysis:
+
+## Your Mission
+
+Analyze this codebase and generate comprehensive coding standards documentation.
+
+## Steps
+
+### Phase 1: Explicit Standards (5 seconds)
+1. Check for existing `.specweave/docs/internal/governance/coding-standards.md`
+2. Parse ESLint config (`.eslintrc.json`, `.eslintrc.js`)
+3. Parse Prettier config (`.prettierrc`, `.prettierrc.json`)
+4. Parse TypeScript config (`tsconfig.json`)
+5. Extract standards from `CLAUDE.md`, `CONTRIBUTING.md`
+
+### Phase 2: Implicit Standards (30 seconds)
+1. Find all source files: `src/**/*.{ts,js,tsx,jsx}`
+2. Analyze naming conventions (variables, functions, classes, constants)
+3. Detect import patterns (extensions, ordering)
+4. Measure function characteristics (length, style)
+5. Assess type usage (any, interfaces vs types)
+6. Identify error handling patterns
+
+### Phase 3: Anti-Pattern Detection (15 seconds)
+1. Detect console.* usage in src/
+2. Find hardcoded secrets (API keys, passwords)
+3. Identify large files (>500 lines)
+4. Find long functions (>100 lines)
+5. Check error handling coverage
+6. Detect N+1 query patterns
+
+### Phase 4: Documentation Generation (10 seconds)
+1. Merge explicit + implicit standards
+2. Calculate confidence levels
+3. Extract real code examples
+4. Highlight inconsistencies
+5. Provide recommendations
+
+## Output
+
+Write comprehensive analysis to:
+`.specweave/docs/internal/governance/coding-standards-analysis.md`
+
+Include:
+- Summary with confidence levels
+- Naming conventions with examples
+- Import patterns
+- Function guidelines
+- Type safety assessment
+- Error handling analysis
+- Anti-patterns and security issues
+- Actionable recommendations
+
+## Console Summary
+
+Print summary to stdout:
+```
+✅ Analysis complete!
+
+📊 Summary:
+- Files: X
+- LOC: Y
+- Confidence: Z%
+
+✅ Strengths: [list]
+⚠️ Issues: [list]
+
+📄 Full report: .specweave/docs/internal/governance/coding-standards-analysis.md
+```
+
+Execute the analysis now.
+AGENT_PROMPT
+    ;;
+
+  drift)
+    echo "Mode: Drift Detection"
+    echo ""
+
+    # Check if standards exist
+    if [[ ! -f "$GOVERNANCE_DIR/coding-standards.md" ]]; then
+      echo "❌ Error: No coding standards found at:"
+      echo "   $GOVERNANCE_DIR/coding-standards.md"
+      echo ""
+      echo "💡 Tip: Run /specweave:analyze-standards first to generate baseline standards"
+      exit 1
+    fi
+
+    echo "📊 Comparing declared standards vs actual code..."
+    echo ""
+
+    # Launch agent in drift-detection mode
+    cat <<'AGENT_PROMPT'
+You are the code-standards-detective agent in DRIFT DETECTION mode.
+
+## Your Mission
+
+Compare declared coding standards against actual codebase to detect drift.
+
+## Steps
+
+1. Read existing standards:
+   `.specweave/docs/internal/governance/coding-standards.md`
+
+2. Analyze current codebase (same as Phase 2-3 in full analysis)
+
+3. Compare declared vs actual:
+   - For each declared standard, check compliance percentage
+   - Identify violations
+   - Calculate drift score
+
+4. Report findings:
+   - Standards with high compliance (90%+) ✅
+   - Standards with drift (70-89%) ⚠️
+   - Standards violated (<70%) 🔴
+
+## Output Format
+
+```markdown
+# Standards Drift Report
+
+**Date**: {timestamp}
+**Overall Compliance**: {percentage}%
+
+## ✅ Compliant Standards (90%+)
+- Naming conventions: 98% compliant
+- Import extensions: 100% compliant
+
+## ⚠️ Drift Detected (70-89%)
+- Constant naming: 85% compliant (15% use camelCase instead of UPPER_SNAKE_CASE)
+  - Recommendation: Update 8 files or relax standard
+
+## 🔴 Violations (<70%)
+- Function length: 65% compliant (35% have functions >100 lines)
+  - Critical: src/core/orchestrator.ts:processIncrement() - 156 lines
+  - Recommendation: Refactor large functions or update standard
+
+## New Patterns Detected
+- Pattern: Using Zod for validation (34% of files)
+  - Not documented in standards
+  - Recommendation: Add to official standards
+```
+
+Write to: `.specweave/docs/internal/governance/coding-standards-drift.md`
+
+Print summary to stdout.
+
+Execute drift detection now.
+AGENT_PROMPT
+    ;;
+
+  update)
+    echo "Mode: Update Standards"
+    echo ""
+
+    # Check if analysis exists
+    if [[ ! -f "$GOVERNANCE_DIR/coding-standards-analysis.md" ]]; then
+      echo "⚠️  No analysis found. Running full analysis first..."
+      echo ""
+      MODE="full"
+      # Re-run in full mode (recursive call avoided by changing MODE)
+    fi
+
+    echo "📊 Generating updated standards..."
+    echo ""
+
+    # Launch agent in update mode
+    cat <<'AGENT_PROMPT'
+You are the code-standards-detective agent in UPDATE mode.
+
+## Your Mission
+
+Update official coding standards based on latest analysis.
+
+## Steps
+
+1. Read existing standards (if exist):
+   `.specweave/docs/internal/governance/coding-standards.md`
+
+2. Read latest analysis:
+   `.specweave/docs/internal/governance/coding-standards-analysis.md`
+
+3. Merge intelligently:
+   - Keep manually curated sections
+   - Update statistics from analysis
+   - Add new patterns if high confidence (>90%)
+   - Flag conflicts for human review
+
+4. Generate updated standards document
+
+## Important Rules
+
+- NEVER remove manually written content without asking
+- Mark auto-generated sections clearly
+- Add "Last Updated" timestamp
+- Preserve human rationale/explanations
+- Flag breaking changes
+
+## Output
+
+Write to: `.specweave/docs/internal/governance/coding-standards.md`
+
+Also write summary to: `.specweave/docs/internal/governance/coding-standards-history.md`
+- Append entry with timestamp
+- List what changed
+- Explain why
+
+Execute update now.
+AGENT_PROMPT
+    ;;
+esac
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ Code standards analysis complete!"
+echo ""
+echo "📂 Files generated:"
+case $MODE in
+  full)
+    echo "   - $GOVERNANCE_DIR/coding-standards-analysis.md"
+    ;;
+  drift)
+    echo "   - $GOVERNANCE_DIR/coding-standards-drift.md"
+    ;;
+  update)
+    echo "   - $GOVERNANCE_DIR/coding-standards.md (updated)"
+    echo "   - $GOVERNANCE_DIR/coding-standards-history.md (appended)"
+    ;;
+esac
+echo ""
+echo "🎯 Next steps:"
+case $MODE in
+  full)
+    echo "   1. Review the analysis report"
+    echo "   2. Fix critical issues (hardcoded secrets, etc.)"
+    echo "   3. Run /specweave:analyze-standards --update to formalize"
+    ;;
+  drift)
+    echo "   1. Review drift report"
+    echo "   2. Fix violations or update standards"
+    echo "   3. Re-run analysis to verify"
+    ;;
+  update)
+    echo "   1. Review updated standards"
+    echo "   2. Commit to git if satisfied"
+    echo "   3. Share with team"
+    ;;
+esac
+echo ""

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

@@ -94,14 +94,45 @@ Proceeding to PM validation...
 ```
 
 **What Gate 0 validates**:
-- [ ] All acceptance criteria are checked (`- [x] **AC-...`)
-- [ ] All tasks are completed (`**Status**: [x] completed`)
+- [ ] All acceptance criteria are checked in **spec.md** (`- [x] **AC-...`)
+- [ ] All tasks are completed in **tasks.md** (`**Status**: [x] completed`)
 - [ ] Required files exist (`spec.md`, `tasks.md`)
+- [ ] **NEW**: Tasks count in frontmatter matches checked tasks (source of truth validation)
+
+**⚠️  SOURCE OF TRUTH ENFORCEMENT (CRITICAL)**:
+
+Gate 0 now validates that `tasks.md` and `spec.md` are the ACTUAL source of truth, not internal TODO lists:
+
+```typescript
+// 1. Count completed tasks in tasks.md (ACTUAL source of truth)
+const tasksInFile = await countCompletedTasks(tasksPath);
+
+// 2. Compare with frontmatter
+const { total_tasks } = readTasksFrontmatter(tasksPath);
+
+// 3. BLOCK if mismatch
+if (tasksInFile < total_tasks) {
+  throw new ValidationError(
+    `CRITICAL: Source of truth violation!\n` +
+    `tasks.md shows ${tasksInFile}/${total_tasks} tasks completed.\n` +
+    `Internal TODO lists are NOT the source of truth.\n` +
+    `You MUST update tasks.md checkboxes before closing.\n` +
+    `See CLAUDE.md Rule #7 for details.`
+  );
+}
+```
+
+**This prevents**:
+- ❌ Closing increments with `[ ] pending` tasks in tasks.md
+- ❌ Relying on internal TODO lists instead of source files
+- ❌ Marking work "done" without updating acceptance criteria
+- ❌ The critical violation from increment 0044 (2025-11-19)
 
 **Why Gate 0 matters**:
 - **Prevents false completion**: Can't mark increment "completed" with open work
 - **Fast feedback**: Fails immediately (< 1s) vs waiting for PM agent (30s+)
 - **Data integrity**: Ensures status matches reality (no spec.md desync)
+- **Source of truth discipline**: Enforces tasks.md and spec.md as the ONLY source of truth
 
 **CRITICAL**: Gate 0 is MANDATORY and CANNOT be bypassed. If validation fails, increment stays "in-progress" and command exits.
 

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

@@ -17,34 +17,60 @@ Arguments provided: [user's arguments]
 
 **Parse the input**:
 - Check for explicit mode: `review`, `update`, or none (auto-detect)
-- Check for increment ID: `0001`, `0002`, etc., or none (find current)
+- Check for increment ID: `0001`, `0002`, etc., or none (sync all - NEW DEFAULT)
+- Check for `--all` flag (explicit sync all)
+
+**NEW DEFAULT BEHAVIOR (v0.23.0+)**:
+- **No arguments** → Sync all increments with spec.md (batch mode)
+- **Specific increment ID** → Sync that increment only
+- **`--all` flag** → Sync all increments (explicit)
 
 **Auto-detect logic**:
 
-1. **If increment ID provided**:
+1. **If no increment ID provided (NEW DEFAULT)**:
    ```bash
-   # Read the increment's spec.md to check status
-   INCREMENT_PATH=".specweave/increments/{increment_id}"
-   STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')
+   # Sync ALL increments with spec.md
+   echo "🔄 Syncing all increments..."
+   npx specweave sync-specs
+   # This will sync all non-archived increments
    ```
 
-2. **If no increment ID provided**:
+2. **If increment ID provided**:
    ```bash
-   # Find the most recent increment
-   LATEST=$(ls -1 .specweave/increments/ | grep -E '^[0-9]{4}' | sort -r | head -1)
+   # Read the increment's spec.md to check status
+   INCREMENT_PATH=".specweave/increments/{increment_id}"
+   STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')
    ```
 
 3. **Determine mode**:
    ```
-   If status = "planned" → REVIEW MODE
-   If status = "in-progress" → UPDATE MODE
-   If status = "completed" → UPDATE MODE
-   If status = "closed" → UPDATE MODE
+   If no increment ID → BATCH SYNC MODE (sync all)
+
+   If increment ID provided:
+     If status = "planned" → REVIEW MODE
+     If status = "in-progress" → UPDATE MODE
+     If status = "completed" → UPDATE MODE
+     If status = "closed" → UPDATE MODE
 
    If explicit mode provided → Use that mode
    ```
 
-**Output**:
+**Output (Batch Mode)**:
+```
+🔄 Syncing all increments...
+
+📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
+   ✅ Synced 3 tasks to US-001
+✅ Synced 0040 → FS-040
+
+📚 Syncing 0041-living-docs-test-fixes → FS-041...
+   ✅ Synced 2 tasks to US-001
+✅ Synced 0041 → FS-041
+
+✅ Sync complete: 15 increments synced, 0 failed
+```
+
+**Output (Single Mode)**:
 ```
 🔍 Detected increment: {increment_id}
 📊 Status: {status}
@@ -679,20 +705,42 @@ Usage: /specweave:sync-docs [review|update] [increment_id]
 
 ## EXAMPLES
 
-### Example 1: Auto-detect mode for current increment
+### Example 1: Sync all increments (NEW DEFAULT)
 ```
 User: /specweave:sync-docs
 
 Output:
-🔍 Detected increment: 0002
+🔄 Syncing all increments...
+
+📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
+   ✅ Synced 3 tasks to US-001
+✅ Synced 0040 → FS-040
+
+📚 Syncing 0041-living-docs-test-fixes → FS-041...
+   ✅ Synced 2 tasks to US-001
+✅ Synced 0041 → FS-041
+
+📚 Syncing 0042-test-infrastructure-cleanup → FS-042...
+   ✅ Synced 5 tasks to US-002
+✅ Synced 0042 → FS-042
+
+✅ Sync complete: 15 increments synced, 0 failed
+```
+
+### Example 2: Sync specific increment
+```
+User: /specweave:sync-docs 0042
+
+Output:
+🔍 Detected increment: 0042
 📊 Status: completed
 🎯 Mode: UPDATE
 
 Proceeding with UPDATE mode...
-{... executes update mode}
+{... executes update mode for 0042 only}
 ```
 
-### Example 2: Explicit review mode
+### Example 3: Explicit review mode
 ```
 User: /specweave:sync-docs review 0003
 
@@ -704,7 +752,7 @@ Output:
 {... shows strategic documentation summary}
 ```
 
-### Example 3: Explicit update mode with increment
+### Example 4: Explicit update mode with increment
 ```
 User: /specweave:sync-docs update 0002
 

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

@@ -106,8 +106,11 @@ 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 - use most reliable single marker (**Completed**: format)
-    COMPLETED_TASKS=$(grep -c '\*\*Completed\*\*:' "$TASKS_FILE" 2>/dev/null || echo 0)
+    # Count completed tasks - recognize all three completion marker formats:
+    # 1. **Completed**: <date> (preferred format)
+    # 2. **Status**: [x] (legacy format)
+    # 3. [x] at line start (legacy checkbox format)
+    COMPLETED_TASKS=$(grep -cE '(\*\*Completed\*\*:|\*\*Status\*\*:\s*\[x\]|^\[x\])' "$TASKS_FILE" 2>/dev/null || echo 0)
     COMPLETED_TASKS=$(echo "$COMPLETED_TASKS" | tr -d '\n\r ' || echo 0)
 
     # Calculate percentage

package/plugins/specweave/skills/brownfield-analyzer/SKILL.md

@@ -20,9 +20,10 @@ description: Analyzes existing brownfield projects to map documentation structur
 3. **Classify Documents** - Identify PRD, HLD, ADR, Spec, Runbook candidates
 4. **Detect External Tools** - Find Jira, ADO, GitHub project references
 5. **Analyze Diagrams** - Identify architecture diagrams (PNG, SVG, drawio)
-6. **Generate Migration Plan** - Create actionable migration plan with effort estimate
-7. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
-8. **Support Two Paths** - Quick Start (incremental) OR Comprehensive (upfront) 🆕
+6. **Discover Coding Standards** - Auto-detect naming conventions, patterns, linting rules 🆕
+7. **Generate Migration Plan** - Create actionable migration plan with effort estimate
+8. **Suggest Increment Mapping** - Map Jira Epics/ADO Features to SpecWeave Increments
+9. **Support Two Paths** - Quick Start (incremental) OR Comprehensive (upfront) 🆕
 
 ---
 
@@ -336,6 +337,42 @@ build/**
 - PNG/DrawIO → Suggest Mermaid conversion
 - Estimate: 15-30 minutes per diagram
 
+### Step 4.5: Coding Standards Discovery 🆕
+
+**Auto-detect coding standards from codebase** using code-standards-detective agent.
+
+**Execution**:
+```bash
+# Run during brownfield analysis (automatic)
+# Or manually: /specweave:analyze-standards
+```
+
+**What it discovers**:
+1. **Explicit Standards** - Parse ESLint, Prettier, TypeScript, EditorConfig
+2. **Implicit Standards** - Analyze naming conventions (98% camelCase?), import patterns, function styles
+3. **Anti-Patterns** - Detect console.* usage, hardcoded secrets, large files (>500 lines)
+4. **Type Safety** - Count `any` usage, interface vs type preference
+5. **Error Handling** - Analyze try/catch patterns, custom error classes
+
+**Statistical Analysis**:
+- Confidence levels (HIGH 90%+, MEDIUM 70-89%, LOW 50-69%)
+- Real code examples from codebase
+- Inconsistency warnings
+
+**Output**:
+```
+.specweave/docs/internal/governance/coding-standards-analysis.md
+```
+
+**Benefits**:
+- ✅ New contributors understand project conventions immediately
+- ✅ Documents "tribal knowledge" that only exists in code
+- ✅ Detects security issues (hardcoded secrets, missing validation)
+- ✅ Provides baseline for code quality improvements
+- ✅ Identifies technical debt (large functions, missing error handling)
+
+**Integration**: This step runs automatically during brownfield analysis, providing coding standards context alongside documentation structure.
+
 ### Step 5: Effort Estimation
 
 **Calculate total effort**: