specweave 0.22.2 → 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

@@ -51,7 +51,94 @@ You are acting as the Product Manager to validate increment completion before cl
 🎯 Validating readiness for closure...
 ```
 
-### Step 2: PM Validation (3 Gates)
+### Step 2: Automated Completion Validation (Gate 0)
+
+**🔥 CRITICAL: Automated validation runs BEFORE PM validation to catch obvious issues!**
+
+**BEFORE** invoking the PM agent, run automated validation using `IncrementCompletionValidator`:
+
+```typescript
+import { IncrementCompletionValidator } from '../../../src/core/increment/completion-validator.js';
+
+// Validate increment is ready for completion
+const validation = await IncrementCompletionValidator.validateCompletion(incrementId);
+
+if (!validation.isValid) {
+  // BLOCK completion and show errors
+  console.error('❌ CANNOT CLOSE INCREMENT - Automated validation failed');
+  console.error('');
+  validation.errors.forEach(err => console.error(`  • ${err}`));
+  console.error('');
+  console.error('Fix these issues before running /specweave:done again');
+  process.exit(1);
+}
+```
+
+**Example validation output** (FAIL):
+```
+❌ CANNOT CLOSE INCREMENT - Automated validation failed
+
+  • 17 acceptance criteria still open
+  • 13 tasks still pending
+
+Fix these issues before running /specweave:done again
+```
+
+**Example validation output** (PASS):
+```
+✅ Automated validation passed
+  • All acceptance criteria completed
+  • All tasks completed
+
+Proceeding to PM validation...
+```
+
+**What Gate 0 validates**:
+- [ ] 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.
+
+---
+
+### Step 3: PM Validation (3 Gates)
 
 **🔥 CRITICAL: PM agent MUST validate all 3 gates before allowing closure!**
 
@@ -288,7 +375,7 @@ Recommendation: ❌ CANNOT close increment
   • Estimated effort: 1-2 hours
 ```
 
-### Step 3: PM Decision
+### Step 4: PM Decision
 
 **Based on 3-gate validation**:
 
@@ -326,7 +413,7 @@ Closing increment 0001-user-authentication...
 🎉 Increment 0001 closed successfully!
 ```
 
-### Step 4: Post-Closure Sync (AUTOMATIC)
+### Step 5: Post-Closure Sync (AUTOMATIC)
 
 **CRITICAL**: After increment closes, automatically perform these syncs:
 
@@ -651,7 +738,7 @@ Increment remains: in-progress
 Try again after fixing blockers: /specweave:done 0001
 ```
 
-### Step 4: Handle Incomplete Work
+### Step 6: Handle Incomplete Work
 
 **If increment cannot close due to scope creep**:
 

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

@@ -13,7 +13,10 @@ Reopen completed work when issues are discovered after completion.
 ## Quick Start
 
 ```bash
-# Reopen entire increment
+# Reopen entire increment (natural language - RECOMMENDED)
+/specweave:reopen 0043 Bug found in AC sync implementation
+
+# OR with explicit --reason flag
 /specweave:reopen 0031 --reason "GitHub sync failing"
 
 # Reopen specific task
@@ -23,6 +26,23 @@ Reopen completed work when issues are discovered after completion.
 /specweave:reopen 0031 --user-story US-001 --reason "Acceptance criteria not met"
 ```
 
+### Natural Language Syntax (NEW!)
+
+You can now use natural language without the `--reason` flag:
+
+```bash
+# ✅ WORKS: Natural language (everything after increment ID is the reason)
+/specweave:reopen 0043 Bug found in implementation, need to fix
+
+# ✅ WORKS: Traditional syntax with flag
+/specweave:reopen 0043 --reason "Bug found in implementation"
+
+# ✅ WORKS: With task ID
+/specweave:reopen 0043 --task T-005 Found edge case not covered
+```
+
+**How it works**: All text after the increment ID (and any flags) is treated as the reason. No quotes needed!
+
 ## Smart Detection First!
 
 **Before using this command manually**, try reporting your issue naturally:
@@ -119,11 +139,18 @@ Use `--force` to bypass WIP limit checks (use sparingly!).
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `<increment-id>` | Yes | Increment to reopen (e.g., `0031` or `0031-external-tool-status-sync`) |
-| `--reason <text>` | Yes | Why reopening (for audit trail) |
+| `--reason <text>` | Optional* | Why reopening (for audit trail). *Can use natural language instead! |
 | `--task <id>` | No | Reopen specific task (e.g., `T-003`) |
 | `--user-story <id>` | No | Reopen user story + related tasks (e.g., `US-001`) |
 | `--force` | No | Bypass WIP limit checks |
 
+**Natural Language**: If `--reason` is not provided, all remaining text is used as the reason.
+
+Examples:
+- `/specweave:reopen 0043 Bug found` → reason = "Bug found"
+- `/specweave:reopen 0043 --task T-005 Edge case` → reason = "Edge case"
+- `/specweave:reopen 0043 --reason "Formal reason"` → reason = "Formal reason" (explicit)
+
 ## WIP Limit Validation
 
 The command automatically checks WIP limits before reopening increments.