specweave 1.0.256 → 1.0.259

package/plugins/specweave/skills/do/SKILL.md

@@ -19,1157 +19,117 @@ hooks:
 
 !`s="do"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
 
-**Implementation Execution**: Following spec.md and plan.md to execute the increment work.
+## Project Context
 
-You are helping the user implement a SpecWeave increment by executing tasks from tasks.md with automatic documentation updates after EVERY task completion.
+!`.specweave/scripts/skill-context.sh do 2>/dev/null; true`
 
-## Usage
-
-```bash
-# Auto-resumes from last incomplete task
-/sw:do <increment-id>
+Execute a SpecWeave increment by running tasks from tasks.md with automatic AC-sync after every task completion.
 
-# Or let it find active increment automatically
-/sw:do
+## Usage
 
-# Override model selection for all tasks (advanced)
-/sw:do <increment-id> --model haiku
-/sw:do <increment-id> --model sonnet
-/sw:do <increment-id> --model opus
 ```
-
-## Arguments
-
-- `<increment-id>`: Optional. Increment ID (e.g., "001", "0001", "1", "0042")
-  - If omitted, **MUST auto-select best candidate** (see Step 0.5 below)
-  - **Smart resume**: Automatically starts from next incomplete task
-
-- `--model <tier>`: Optional. Override model selection for all tasks
-  - `haiku`: Fast, cheap execution (simple mechanical tasks)
-  - `sonnet`: Legacy option (rarely needed)
-  - `opus`: Maximum quality (default for all complex tasks)
-  - If omitted, uses model hints from tasks.md (recommended)
-
----
-
-## Workflow
-
-### Step 0.5: Smart Increment Auto-Selection (MANDATORY when no ID provided)
-
-**🎯 CRITICAL: When user runs `/sw:do` without increment ID, you MUST auto-select the best candidate.**
-
-**DO NOT** ask the user for an increment ID. **DO NOT** fail with "increment ID required". Instead:
-
-1. **Scan for candidates** in this priority order:
-
-   ```bash
-   # Priority 1: in-progress (resume work)
-   IN_PROGRESS=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "in-progress"' {} \; 2>/dev/null | head -1)
-
-   # Priority 2: planned (start next work)
-   PLANNED=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "planned"' {} \; 2>/dev/null | head -1)
-
-   # Priority 3: ready_for_review with incomplete tasks (needs finishing)
-   READY=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "ready_for_review"' {} \; 2>/dev/null)
-
-   # Priority 4: backlog with tasks (can start)
-   BACKLOG=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"status": "backlog"' {} \; 2>/dev/null)
-   ```
-
-2. **For each candidate**, check if it has incomplete tasks:
-
-   ```bash
-   # Count incomplete tasks in tasks.md (supports multiple formats)
-   # Format 1: List items "- [ ] Task"
-   INCOMPLETE=$(grep -c '^\- \[ \]' "$INCREMENT_PATH/tasks.md" 2>/dev/null || echo "0")
-   # Format 2: Status field "**Status**: [ ] pending"
-   INCOMPLETE_STATUS=$(grep -c '\*\*Status\*\*: \[ \]' "$INCREMENT_PATH/tasks.md" 2>/dev/null || echo "0")
-   # Total incomplete = sum of all formats
-   TOTAL_INCOMPLETE=$((INCOMPLETE + INCOMPLETE_STATUS))
-   ```
-
-3. **Select the best candidate**:
-   - If `in-progress` increment exists → use it
-   - Else if `planned` increment exists → use it
-   - Else if `ready_for_review` with incomplete tasks → use it
-   - Else if `backlog` increment exists with incomplete tasks → use it (and change status to in-progress)
-
-4. **If candidate found, display selection and continue**:
-
-   ```
-   🎯 Auto-selected increment: 0162-lsp-skill-integration
-
-   Status: backlog → in-progress (auto-promoted)
-   Tasks: 0/28 completed (0%)
-   Priority: P1
-   Type: refactor
-
-   Proceeding with execution...
-   ```
-
-5. **If NO candidates found (all done), show insights and ask user**:
-
-   ```
-   ✅ All increments completed!
-
-   📊 Quick Status:
-   ┌─────────────────────────────────────────────────────────────┐
-   │  Active: 0 | Backlog: 0 | Completed: 47 | Archived: 125    │
-   │  Last completed: 0167-comprehensive-code-review (2 days ago) │
-   └─────────────────────────────────────────────────────────────┘
-
-   🔮 Recent completions:
-      • 0175-plugin-session-restart-warning (completed 1 day ago)
-      • 0174-router-brain-orchestrator (ready_for_review)
-      • 0167-comprehensive-code-review (ready_for_review)
-
-   💡 What would you like to do?
-
-   Options:
-     A) Create new increment: /sw:increment "feature name"
-     B) Close ready_for_review: /sw:done 0174
-     C) Resume from backlog: /sw:resume 0162
-     D) View full status: /sw:status
-
-   Your choice? [A/B/C/D or type feature name]: _
-   ```
-
-**Why This Matters**:
-- Users shouldn't need to remember increment IDs
-- `/sw:do` should "just work" like `/sw:auto`
-- Smart selection saves context switches
-
----
-
-### Step 0: Self-Awareness Check
-
-**🎯 OPTIONAL BUT RECOMMENDED**: Check if running in SpecWeave repository itself.
-
-This step is particularly useful when implementing SpecWeave features vs user projects, as it provides context for:
-- Understanding if changes affect the framework
-- Being careful with breaking changes
-- Considering backward compatibility
-
-```typescript
-import { detectSpecWeaveRepository } from './src/utils/repository-detector.js';
-
-const repoInfo = detectSpecWeaveRepository(process.cwd());
-
-if (repoInfo.isSpecWeaveRepo) {
-  console.log('ℹ️  Working on SpecWeave framework increment');
-  console.log(`   Confidence: ${repoInfo.confidence}`);
-  console.log('');
-  console.log('   💡 Reminders:');
-  console.log('      • Test changes don\'t break existing user projects');
-  console.log('      • Consider backward compatibility');
-  console.log('      • Update CLAUDE.md if workflow changes');
-  console.log('');
-}
+/sw:do <increment-id>    # Execute specific increment
+/sw:do                   # Auto-select best candidate
+/sw:do <id> --model haiku|sonnet|opus  # Override model for all tasks
 ```
 
-**When to Show This**:
-- On first task execution for the increment
-- Skip on subsequent tasks (user already knows context)
-
-**Why This Helps**:
-Contributors working on SpecWeave itself need different mindset than users building apps:
-- Framework changes affect ALL users
-- Breaking changes need deprecation warnings
-- Documentation updates are critical
+- `<increment-id>`: Optional. Supports "001", "0001", "1", "0042", or "0153-feature-name" formats.
+- `--model <tier>`: Optional. Overrides per-task model hints.
 
 ---
 
-### Step 1: Load Context
-
-**Prerequisite**: Increment ID is now available (either from user input or auto-selected in Step 0.5).
-
-1. **Find increment directory**:
-   - **Normalize increment ID**:
-     - If ID contains dash (e.g., "0153-feature-name"), extract numeric portion before first dash → "0153"
-     - Convert to 4-digit format (e.g., "1" → "0001", "153" → "0153")
-     - Both formats work: `/sw:do 0153` or `/sw:do 0153-feature-name`
-   - Find matching directory: `.specweave/increments/0001-*/` (matches by prefix)
-   - Verify increment exists
-
-2. **Load specification and plan**:
-   - Read `spec.md` - Understand WHAT and WHY
-   - Read `plan.md` - Understand HOW
-   - Read `tasks.md` - Understand implementation steps
-   - Read `tests.md` - Understand test strategy
-
-3. **🔄 Load Living Docs Context**:
-
-   **Optional but recommended**: Load relevant living documentation context.
-
-   ```bash
-   # Extract topic keywords from spec.md title/user stories
-   TOPIC=$(grep -m1 "^#" spec.md | sed 's/# //' | tr '[:upper:]' '[:lower:]')
-
-   # Check if related living docs exist
-   LIVING_DOCS_ROOT=".specweave/docs/internal"
-   RELATED_DOCS=$(find "$LIVING_DOCS_ROOT" -name "*${TOPIC}*" -o -name "*${KEYWORD}*" 2>/dev/null)
-   ```
-
-   **If related living docs found**:
-   - Read relevant ADRs from `.specweave/docs/internal/architecture/adr/`
-   - Read relevant specs from `.specweave/docs/internal/specs/`
-   - Read relevant architecture docs from `.specweave/docs/internal/architecture/`
-
-   **Why This Helps**:
-   - Ensures implementation follows established patterns
-   - Avoids contradicting existing ADRs
-   - Provides historical context for design decisions
-   - References related features for consistency
-
-   **Example output**:
-   ```
-   📚 Living Docs Context Loaded:
-      • ADR-0023: Database Connection Pooling (relevant)
-      • spec-005: User Management (related feature)
-      • architecture/auth-flow.md (pattern to follow)
-   ```
-
-   **Skip if**: Living docs don't exist or no relevant docs found
-
-4. **Verify readiness**:
-   - Check status is "planned" (not already in-progress or completed)
-   - Check no blocking dependencies
-   - Check tasks.md has tasks to execute
-
-5. **🚨 CRITICAL: Task Count Validation (CRASH PREVENTION!)**:
-
-   **MANDATORY**: Count tasks in tasks.md before proceeding.
-
-   ```bash
-   TASK_COUNT=$(grep -c "^### T-" .specweave/increments/<id>/tasks.md)
-   ```
-
-   **If TASK_COUNT > 25**:
-   ```
-   ⚠️ TASK COUNT EXCEEDS SOFT LIMIT
-
-   This increment has X tasks (soft limit: 25)
-
-   >25 tasks = consider splitting for maintainability (per CLAUDE.md rules)
-
-   💡 RECOMMENDED: Split this increment OR execute phase-by-phase:
-
-   Option A - Split into separate increments:
-   Pattern: 0116-feature/ → Split into:
-     • 0116-feature-phase1/ (T-001 to T-008)
-     • 0117-feature-phase2/ (T-009 to T-016)
-     • 0118-feature-phase3/ (T-017 to T-025)
-
-   Option B - Phase-by-phase execution (recommended for 15-25 tasks):
-     Execute Phase 1 → validate → continue to Phase 2 → ...
+## Workflow
 
-   User choice required to proceed.
-   ```
+### Step 1: Smart Increment Auto-Selection
 
-   **If TASK_COUNT <= 25**: Proceed to next step
+When no ID provided, auto-select (NEVER ask user for ID):
 
-6. **🚨 CRITICAL: Validate AC Presence**:
+1. Scan by priority: `in-progress` > `planned` > `ready_for_review` (with incomplete tasks) > `backlog` (with incomplete tasks)
+2. For each candidate, count incomplete tasks: `grep -c '^\- \[ \]'` + `grep -c '\*\*Status\*\*: \[ \]'` in tasks.md
+3. Select best candidate and auto-promote to in-progress if needed
+4. If no candidates, show status summary and offer: create new, close ready_for_review, resume backlog, or view status
 
-   **MANDATORY**: Run pre-increment-start validation hook to verify spec.md contains ACs.
+### Step 2: Load Context
 
-   Use the Bash tool to run:
+1. **Find increment directory**: Normalize ID to 4-digit format, match `.specweave/increments/NNNN-*/`
+2. **Load files**: Read `spec.md`, `plan.md`, `tasks.md`, `tests.md`
+3. **Load living docs**: Check ADRs and specs in `.specweave/docs/internal/` for related context
+4. **Verify readiness**: Status is planned/in-progress, no blocking deps, tasks exist
+5. **Task count validation**: If >25 tasks, warn and offer to split or phase execution
+6. **Validate AC presence** (MANDATORY):
    ```bash
    bash plugins/specweave/hooks/pre-increment-start.sh <increment-path>
-   # Example: bash plugins/specweave/hooks/pre-increment-start.sh .specweave/increments/0050-feature-name
    ```
+   If fails: run `/sw:embed-acs`, then retry. Do NOT proceed without ACs in spec.md.
 
-   **Expected Output (Success)**:
-   ```
-   ✅ AC Presence Validation PASSED
-      • spec.md contains 39 ACs
-      • Matches metadata.json (39 expected)
-      • Ready to start implementation
-   ```
-
-   **Expected Output (Failure)**:
-   ```
-   ❌ AC Presence Validation FAILED
-      • spec.md contains 0 ACs (expected 39)
-      • ACs are REQUIRED for task-AC sync to work
-
-   💡 Fix: Run /sw:embed-acs <increment-id>
-   ```
-
-   **What to Do After Validation**:
-   - ✅ **If validation passes**: Proceed to Step 2
-   - ❌ **If validation fails**: Show error, run `/sw:embed-acs`, then retry
-   - **DO NOT PROCEED** without ACs in spec.md (hooks will fail!)
-
-   **Why This Matters** (ADR-0064):
-   - The AC sync hook requires ACs in spec.md to update completion status
-   - Without inline ACs, you get 0% AC completion and broken status line
-   - Even with external living docs, ACs MUST be embedded in spec.md
-
-**Example output**:
-```
-📂 Loading increment 0001-user-authentication...
-
-✅ Loaded context:
-   • spec.md (6 user stories, 15 requirements)
-   • plan.md (Architecture: JWT + PostgreSQL)
-   • tasks.md (42 tasks, estimated 3-4 weeks)
-   • tests.md (12 test cases, 85% coverage)
-
-🎯 Ready to execute!
-```
-
-### Step 1.5: Check TDD Mode
-
-**Read testMode from metadata.json:**
+### Step 3: TDD Setup
 
+Read `testMode` from metadata.json:
 ```bash
-INCREMENT_PATH=".specweave/increments/<id>"
 TEST_MODE=$(cat "$INCREMENT_PATH/metadata.json" | jq -r '.testMode // "test-after"')
 ```
 
-**If TEST_MODE == "TDD", display TDD reminder banner:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  🔴 TDD MODE ACTIVE                                          │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  This increment uses Test-Driven Development.               │
-│                                                             │
-│  WORKFLOW:                                                  │
-│  1. [RED]      Write failing test FIRST                     │
-│  2. [GREEN]    Minimal code to make test pass               │
-│  3. [REFACTOR] Improve code, keep tests green               │
-│                                                             │
-│  ⚠️  GREEN tasks depend on their RED counterpart!           │
-│  💡 Tip: Use /sw:tdd-cycle for guided workflow              │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**When executing tasks, detect and display current phase:**
-
-```bash
-CURRENT_TASK_TITLE="T-001: [RED] Write failing test for login"
-
-if [[ "$CURRENT_TASK_TITLE" == *"[RED]"* ]]; then
-  PHASE="🔴 RED - Writing failing test"
-elif [[ "$CURRENT_TASK_TITLE" == *"[GREEN]"* ]]; then
-  PHASE="🟢 GREEN - Making test pass"
-elif [[ "$CURRENT_TASK_TITLE" == *"[REFACTOR]"* ]]; then
-  PHASE="🔵 REFACTOR - Improving code quality"
-else
-  PHASE=""  # Not a TDD task
-fi
-
-if [ -n "$PHASE" ]; then
-  echo "Current Phase: $PHASE"
-fi
-```
-
-**Skip TDD banner if**:
-- `testMode` is not "TDD"
-- Already showed banner in current session
-
-### Step 1.5.5: TDD Marker Validation (CRITICAL when TDD mode is enabled)
-
-**🚨 CRITICAL: When TDD mode is active, verify tasks.md has TDD markers!**
-
-This step MUST run BEFORE Step 1.6 enforcement to catch the case where TDD is enabled but tasks were NOT generated with `/sw:increment`.
-
-**Check for TDD markers in tasks.md:**
-
-```bash
-INCREMENT_PATH=".specweave/increments/<id>"
-TASKS_FILE="$INCREMENT_PATH/tasks.md"
-
-# Count TDD markers
-RED_COUNT=$(grep -c '\[RED\]' "$TASKS_FILE" 2>/dev/null || echo "0")
-GREEN_COUNT=$(grep -c '\[GREEN\]' "$TASKS_FILE" 2>/dev/null || echo "0")
-REFACTOR_COUNT=$(grep -c '\[REFACTOR\]' "$TASKS_FILE" 2>/dev/null || echo "0")
-TOTAL_MARKERS=$((RED_COUNT + GREEN_COUNT + REFACTOR_COUNT))
-
-echo "TDD Markers found: RED=$RED_COUNT, GREEN=$GREEN_COUNT, REFACTOR=$REFACTOR_COUNT"
-```
-
-**If TDD mode is enabled BUT no markers found (TOTAL_MARKERS == 0):**
-
-```typescript
-function validateTDDMarkers(tasksContent: string, tddMode: string, tddEnforcement: string): void {
-  if (tddMode !== 'TDD') return; // Not TDD mode, skip
-
-  const hasRedMarkers = tasksContent.includes('[RED]');
-  const hasGreenMarkers = tasksContent.includes('[GREEN]');
-  const hasRefactorMarkers = tasksContent.includes('[REFACTOR]');
-
-  if (!hasRedMarkers && !hasGreenMarkers && !hasRefactorMarkers) {
-    // TDD mode enabled but NO markers in tasks.md!
-    const message = `
-⚠️  TDD MODE ENABLED BUT TASKS LACK TDD MARKERS
-
-Your config has TDD mode enabled:
-  testing.defaultTestMode: "TDD"
-
-But tasks.md has NO [RED], [GREEN], [REFACTOR] markers.
-
-This means TDD enforcement CANNOT work because:
-  • /sw:do checks task markers to enforce order
-  • Without markers, enforcement is silently bypassed
-
-CAUSE: Tasks were likely created manually or before TDD was enabled.
-
-FIX OPTIONS:
-  1. (Recommended) Regenerate tasks with /sw:increment
-     This will create proper RED→GREEN→REFACTOR triplets
-
-  2. Add markers manually to existing tasks:
-     ### T-001: [RED] Write failing test for feature X
-     ### T-002: [GREEN] Implement feature X to pass test
-     ### T-003: [REFACTOR] Clean up feature X code
-
-  3. Disable TDD mode:
-     Set testing.defaultTestMode: "test-after" in config.json
-`;
-
-    if (tddEnforcement === 'strict') {
-      console.error(message);
-      console.error('❌ BLOCKED: Cannot proceed without TDD markers in strict mode.');
-      console.error('   Fix tasks.md or change tddEnforcement to "warn".');
-      throw new Error('TDD_MARKERS_MISSING');
-    } else if (tddEnforcement === 'warn') {
-      console.warn(message);
-      console.warn('⚠️  Proceeding without TDD enforcement (warn mode)...');
-    }
-    // If tddEnforcement === 'off', silently continue
-  }
-}
-```
-
-**Enforcement behavior:**
-
-| tddEnforcement | TDD Enabled + No Markers | Behavior |
-|----------------|--------------------------|----------|
-| `strict` | **BLOCK** | ❌ "Cannot proceed without TDD markers. Run /sw:increment or add markers manually." |
-| `warn` (default) | **WARN but allow** | ⚠️ "TDD markers missing. Enforcement bypassed. Consider regenerating tasks." |
-| `off` | **No check** | Silent pass |
-
-**Example output (strict mode, no markers):**
-
-```
-❌ TDD MARKER VALIDATION FAILED
-
-TDD mode is enabled (testing.defaultTestMode: "TDD")
-But tasks.md has 0 TDD markers:
-  • [RED] markers: 0
-  • [GREEN] markers: 0
-  • [REFACTOR] markers: 0
-
-This means TDD discipline CANNOT be enforced!
-
-💡 To fix, choose one:
-   1. /sw:increment "feature-name"  ← Regenerate with TDD tasks
-   2. Add [RED]/[GREEN]/[REFACTOR] markers to task titles
-   3. Set tddEnforcement: "warn" to proceed anyway
-
-Blocked in strict mode. Fix markers or change enforcement level.
-```
-
-**Example output (warn mode, no markers):**
-
-```
-⚠️  TDD MARKERS MISSING
-
-TDD mode is enabled but tasks.md lacks [RED]/[GREEN]/[REFACTOR] markers.
-TDD enforcement is effectively DISABLED for this increment.
-
-💡 For proper TDD discipline, regenerate tasks: /sw:increment "feature"
-
-Proceeding without enforcement (warn mode)...
-```
-
-**When this validation passes:**
-- TDD mode not enabled → Skip (no validation needed)
-- TDD mode enabled + markers found → Pass (proceed to Step 1.6)
-- TDD mode enabled + no markers + strict → Block (user must fix)
-- TDD mode enabled + no markers + warn → Warn and proceed
-- TDD mode enabled + no markers + off → Silent pass
-
-### Step 1.6: TDD Enforcement (MANDATORY when TDD mode is enabled)
-
-**🚨 CRITICAL: When TDD mode is active, enforce RED→GREEN→REFACTOR order!**
-
-**Read enforcement level from config.json:**
-
-```bash
-CONFIG_PATH=".specweave/config.json"
-TDD_ENFORCEMENT=$(cat "$CONFIG_PATH" | jq -r '.testing.tddEnforcement // "warn"')
-# Values: "strict" (blocks), "warn" (allows but warns), "off" (no checks)
-```
-
-**Before marking ANY task as complete, check TDD discipline:**
-
-```typescript
-function checkTDDViolation(currentTask: Task, allTasks: Task[]): TDDViolation | null {
-  // Only check if task has TDD phase marker
-  const phase = extractPhase(currentTask.title); // [RED], [GREEN], [REFACTOR]
-  if (!phase) return null;
-
-  // Find related tasks in the same triplet (e.g., T-001, T-002, T-003)
-  const tripletBase = Math.floor((currentTask.number - 1) / 3) * 3 + 1;
-
-  if (phase === 'GREEN') {
-    // GREEN requires RED to be completed first
-    const redTask = allTasks.find(t =>
-      t.number === tripletBase && t.title.includes('[RED]')
-    );
-    if (redTask && redTask.status !== 'completed') {
-      return {
-        type: 'GREEN_BEFORE_RED',
-        message: `Cannot complete GREEN task (${currentTask.id}) before RED task (${redTask.id})`,
-        redTaskId: redTask.id,
-      };
-    }
-  }
-
-  if (phase === 'REFACTOR') {
-    // REFACTOR requires GREEN to be completed first
-    const greenTask = allTasks.find(t =>
-      t.number === tripletBase + 1 && t.title.includes('[GREEN]')
-    );
-    if (greenTask && greenTask.status !== 'completed') {
-      return {
-        type: 'REFACTOR_BEFORE_GREEN',
-        message: `Cannot complete REFACTOR task (${currentTask.id}) before GREEN task (${greenTask.id})`,
-        greenTaskId: greenTask.id,
-      };
-    }
-  }
-
-  return null; // No violation
-}
-```
-
-**Enforcement behavior based on level:**
-
-| Level | On Violation | Behavior |
-|-------|--------------|----------|
-| `strict` | **BLOCK** | ❌ "TDD VIOLATION: Cannot complete GREEN before RED. Complete T-001 [RED] first." |
-| `warn` (default) | **WARN but allow** | ⚠️ "TDD Warning: Completing GREEN before RED violates TDD discipline." |
-| `off` | **No check** | Silent pass |
-
-**Example output (strict mode):**
-
-```
-❌ TDD ENFORCEMENT BLOCKED
-
-You attempted to complete: T-002: [GREEN] Implement login handler
-But its RED counterpart is not done: T-001: [RED] Write login test
-
-TDD DISCIPLINE REQUIRES:
-  1. 🔴 RED - Write failing test FIRST
-  2. 🟢 GREEN - Then implement to pass
-  3. 🔵 REFACTOR - Then improve code
-
-💡 Complete T-001 first, then come back to T-002.
-   Or disable strict enforcement: Set tddEnforcement: "warn" in config.json
-```
-
-**Example output (warn mode):**
+If TDD mode active:
+- Show TDD reminder banner (RED > GREEN > REFACTOR)
+- Detect phase from task title markers: `[RED]`, `[GREEN]`, `[REFACTOR]`
+- **Validate TDD markers exist** in tasks.md. If missing:
+  - `strict` enforcement: BLOCK, require regeneration via `/sw:increment`
+  - `warn` (default): warn and proceed
+  - `off`: silent pass
+- **Enforce order**: GREEN requires RED complete; REFACTOR requires GREEN complete
+  - Read enforcement: `jq -r '.testing.tddEnforcement // "warn"' .specweave/config.json`
+  - `strict`: block violations; `warn`: warn but allow; `off`: no check
 
-```
-⚠️  TDD DISCIPLINE WARNING
+### Step 4: Smart Resume
 
-Completing T-002 [GREEN] before T-001 [RED] violates TDD discipline.
+1. Parse tasks.md, find first incomplete task (`[ ]`)
+2. Extract model hints per task (haiku/sonnet/opus)
+3. Show resume context with completion percentage
 
-TDD works best when you:
-  1. Write the failing test first (RED)
-  2. Then implement just enough to pass (GREEN)
+### Step 5: Update Status
 
-Proceeding anyway... (set tddEnforcement: "strict" to block)
-```
+If status is "planned", update to "in-progress" with start date in spec.md frontmatter.
 
-**When to check:**
-- ✅ Before marking any [GREEN] or [REFACTOR] task complete
-- ❌ Skip check for [RED] tasks (they can be completed freely)
-- ❌ Skip check for non-TDD tasks (no phase marker)
+### Step 6: Execute Tasks Sequentially
 
-### Step 2: Smart Resume - Find Next Incomplete Task
+For each task:
 
-**🎯 CRITICAL: Auto-resume functionality** - no need to remember which task you were on!
+1. **Read task details**: ID, model hint, description, ACs, file paths
+2. **Select model**: Use task hint or `--model` override
+3. **Execute**: Follow plan.md architecture, implement, write clean code
+4. **Mark complete**: Change `[ ]` to `[x]` in tasks.md
 
-1. **Parse tasks.md**:
-   - Scan all tasks in order
-   - Check completion status (`[x]` = complete, `[ ]` = incomplete)
-   - **Extract model hints** (⚡ haiku, 🧠 sonnet, 💎 opus)
-   - Find first incomplete task
+**After EVERY task completion** (CRITICAL):
 
-2. **Determine starting point**:
-   - If all tasks complete → Show completion message
-   - If tasks incomplete → Resume from first incomplete task
-   - If no tasks started → Start from T001
+- **AC-sync hook fires automatically** (via PostToolUse on Edit/Write) updating spec.md ACs
+- **Update docs inline**: CLAUDE.md (new commands/config/skills), README.md (user-facing changes), CHANGELOG.md (API/breaking changes), openapi.yaml (if API task + apiDocs.enabled)
+- **GitHub sync** (if plugin enabled): close task issue, check off in epic, post completion comment
+- Continue to next incomplete task
 
-3. **Show resume context with model optimization**:
-   ```
-   📊 Resume Context:
+### Step 7: Handle Blockers
 
-   Completed: 3/12 tasks (25%)
-   ├─ [✅] T001: ⚡ haiku - Setup auth module (P1) [saved $0.14]
-   ├─ [✅] T002: ⚡ haiku - Create user model (P1) [saved $0.14]
-   ├─ [✅] T003: 💎 opus - Implement JWT tokens (P1)
-   └─ [⏳] T004: ⚡ haiku - Add password hashing (P1) ← RESUMING HERE
+If task blocked: document in tasks.md, present options to user, skip or pause depending on severity.
 
-   Remaining: 9 tasks (estimated 2 weeks)
-   Cost savings so far: $0.28 (67% cheaper than all-Opus)
-   ```
+### Step 8: Run Tests
 
-**Why smart resume?**
-- ✅ No manual tracking needed
-- ✅ Seamlessly continue after breaks
-- ✅ Prevents duplicate work
-- ✅ Shows progress at a glance
-- ✅ **Cost optimization through smart model selection**
+After testable tasks: run relevant tests, fix failures immediately, only continue when green.
 
-### Step 3: Update Status to In-Progress (if needed)
+### Step 9: Completion
 
-If status is "planned", update `spec.md` frontmatter:
+When all tasks done:
+1. Run `/sw:sync-docs update` to sync living docs
+2. Suggest: `npm test` then `/sw:validate <id> --quality` then `/sw:done <id>`
 
-```yaml
 ---
-increment: 0001-user-authentication
-status: in-progress      # ← Changed from "planned"
-started: 2025-10-28      # ← Start date
----
-```
-
-If already "in-progress", keep existing metadata.
-
-### Step 4: Execute Tasks Sequentially
-
-**For each task in tasks.md**:
-
-1. **Read task details**:
-   - Task ID (T001, T002, etc.)
-   - **Model hint** (⚡ haiku, 🧠 sonnet, 💎 opus)
-   - Description
-   - Acceptance criteria
-   - File paths affected
-   - Implementation notes
-
-2. **Select execution model**:
-   - **Use model from task hint** (recommended, optimizes cost/speed)
-   - OR use `--model` override if specified by user
-   - Show selected model and reasoning
-
-3. **Execute task**:
-   - Follow plan.md architecture
-   - Implement using detected tech stack
-   - Write clean, maintainable code
-   - Add inline documentation
-   - **Track cost savings** when using Haiku
-
-3. **Mark task complete** in tasks.md:
-   - Change `[ ]` → `[x]`
-   - Add completion timestamp
-   - Note any deviations from plan
-
-4. **🔥 CRITICAL: After EVERY task completion**:
-
-   **Step A: Hook executes automatically (via .claude/hooks.json)**:
-   - 🔊 Plays completion sound (Glass.aiff on macOS)
-   - 📝 Shows reminder message
-   - ✅ This happens automatically when you mark task complete
 
-   **Step B: Update GitHub Issue (if GitHub plugin enabled)**:
-   - Close task GitHub issue (#43, #44, etc.)
-   - Check off task in epic issue
-   - Post completion comment with stats:
-     - Files modified (+lines/-lines)
-     - Tests passing
-     - Actual vs estimated duration
-     - Brief summary of changes
-     - Next task
-   - Update epic progress (X/Y tasks completed, Z%)
-   - Add 'in-progress' label to epic (if first task)
-
-   **Example GitHub sync**:
-   ```
-   🔗 Syncing to GitHub...
-      ✓ Closed task issue #43
-      ✓ Checked off [T-001] in epic #42
-      ✓ Posted completion comment
-      ✓ Updated epic progress: 7/48 tasks (15%)
-   ```
-
-   **Step C: Update project documentation inline**:
-   - Update CLAUDE.md if task added:
-     - New commands or CLI flags
-     - New file structure
-     - New configuration options
-     - New skills or agents
-   - Update README.md if task added:
-     - User-facing features
-     - Installation steps
-     - Usage examples
-     - API changes
-   - Update CHANGELOG.md if task added:
-     - Public API changes
-     - Breaking changes
-     - New features
-   - **Update API docs if task is API-related** (only if `apiDocs.enabled` in config):
-     - New endpoint → Update openapi.yaml (or regenerate from decorators)
-     - On increment close → Generate postman-collection.json from OpenAPI
-
-   **Step D: Continue to next task**:
-   - Do NOT call `/sw:sync-docs` yet (wait until all tasks complete)
-   - Move to next incomplete task
-
-**Example task execution**:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-TASK T001: Create User model (PostgreSQL)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-📋 Task details:
-   • File: src/models/User.ts
-   • Model: ⚡ haiku (clear instructions, specific file path)
-   • Description: Create User model with Prisma
-   • Acceptance: Model has id, email, passwordHash, createdAt fields
-
-⚡ Executing with Haiku (3x faster, ~$0.0025 vs $0.15 Opus)...
-   ✓ Created src/models/User.ts
-   ✓ Added Prisma schema definition
-   ✓ Generated migration file
-   ✓ Added inline documentation
-
-✅ Task T001 completed
-💰 Cost savings: $0.1475 (98% cheaper than Opus)
-
-🔊 [Glass.aiff plays automatically via hook]
-🔔 Task completed! Remember to update documentation...
-
-🔗 Syncing to GitHub (if enabled):
-   ✓ Closed task issue #43
-   ✓ Checked off [T-001] in epic #42
-   ✓ Posted completion comment to #43
-   ✓ Updated epic #42 progress: 1/42 tasks (2%)
-
-📝 Updating project documentation:
-   ✓ Updated CLAUDE.md (added User model to schema reference)
-   ✓ Updated README.md (added database section with example)
-   ✓ No CHANGELOG.md update needed (internal model)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Progress: 1/42 tasks (2%) | Cost savings so far: $0.05 | Estimated remaining: 3.9 weeks
-
-Moving to next task...
-```
-
-### Step 4: Handle Blockers
-
-If a task cannot be completed:
-
-1. **Document blocker**:
-   - Add to tasks.md as note
-   - Explain reason (missing dependency, unclear requirement, etc.)
-
-2. **Ask user for clarification**:
-   - Present blocker clearly
-   - Offer solutions or alternatives
-   - Wait for user decision
-
-3. **Continue or pause**:
-   - Skip to next task if blocker is non-blocking
-   - Pause if blocker is critical
-
-**Example blocker**:
-```
-⚠️ Blocker on Task T012: "Add email verification"
-
-Issue: Email service provider not specified in plan.md
-
-Options:
-  A) Use SendGrid (recommended, $15/month)
-  B) Use AWS SES (cheaper, $1/1000 emails)
-  C) Use SMTP (self-hosted, free but complex)
-  D) Skip for now, add as new task later
-
-Your choice? [A/B/C/D]: _
-```
-
-### Step 5: Run Tests Continuously
-
-**After completing tasks that affect testable functionality**:
-
-1. **Run relevant tests**:
-   - Unit tests for the module
-   - Integration tests if applicable
-   - Show pass/fail status
-
-2. **If tests fail**:
-   - Show error details
-   - Fix immediately
-   - Re-run tests
-   - Continue only when tests pass
-
-**Example test run**:
-```
-🧪 Running tests for auth module...
-
-  ✓ User model validation
-  ✓ Password hashing
-  ✗ JWT token generation (FAILED)
-    Expected token to expire in 24h, got 1h
-
-🔧 Fixing test failure...
-   • Updated JWT expiry config in plan.md
-   • Fixed token generation in src/auth/jwt.ts
-
-Re-running tests...
-
-  ✓ JWT token generation
-
-✅ All tests passing (3/3)
-```
-
-### Step 6: Progress Tracking
-
-**Show progress regularly**:
-
-```
-📊 Increment Progress: 0001-user-authentication
-
-Tasks completed: 15/42 (36%)
-Time elapsed: 1.2 weeks
-Estimated remaining: 2.1 weeks
-On track: ✅ Yes
-
-Current phase: Backend Implementation
-Next phase: Frontend Integration
-
-Recent completions:
-  ✓ T012: Add email verification (2h ago)
-  ✓ T013: Implement password reset (1h ago)
-  ✓ T014: Add rate limiting (30m ago)
-
-Up next:
-  [ ] T015: Create login API endpoint
-  [ ] T016: Add JWT middleware
-```
-
-### Step 7: Completion Check
-
-**When all tasks marked complete**:
-
-```
-🎉 All tasks completed!
-
-✅ Tasks: 42/42 (100%)
-⏱️  Time taken: 3.2 weeks (vs estimated 3-4 weeks)
-
-🔊 [Playing celebration sound...]
-
-📝 Now syncing implementation learnings to living docs...
-```
-
-**CRITICAL: Now run `/sw:sync-docs update` to sync to living docs**:
-
-```bash
-/sw:sync-docs update
-```
-
-This will:
-- Update ADRs with implementation details (Proposed → Accepted)
-- Update API documentation with actual endpoints
-- Update architecture diagrams with actual system
-- Update feature lists with completed features
-- May prompt for conflict resolution if needed
-
-**After `/sw:sync-docs update` completes**:
-
-```
-✅ Living documentation synchronized!
-
-Next steps:
-1. Run full test suite: npm test
-2. Validate increment: /sw:validate 0001 --quality
-3. Close increment: /sw:done 0001 (PM validates before closing)
-```
-
----
-
-## Hook Integration (CRITICAL!)
-
-**Post-Task Completion Hook** runs after EVERY task via `.claude/hooks.json`:
-
-### Configuration
-
-**File**: `.claude/hooks.json`
-
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "TodoWrite",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash .claude/hooks/post-task-completion.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-**Hook Script**: `.claude/hooks/post-task-completion.sh`
+## Credentials Auto-Execute
 
+Before deployment tasks, check credentials (NEVER display values):
 ```bash
-#!/bin/bash
-# Plays completion sound and outputs reminder JSON
-# Output: {"continue": true, "systemMessage": "Task completed! Update docs..."}
+grep -qE "SUPABASE|DATABASE_URL|CF_|AWS_|HETZNER" .env 2>/dev/null && echo "Credentials found"
 ```
-
-### Hook Behavior
-
-**After EVERY task completion (via TodoWrite)**:
-
-1. **Play sound synchronously**:
-   - macOS: Glass.aiff via `afplay`
-   - Linux: complete.oga via `paplay`
-   - Windows: chimes.wav via PowerShell
-   - Sound plays BEFORE Claude continues
-
-2. **Show reminder**:
-   - JSON systemMessage displayed to user
-   - Reminds to update CLAUDE.md, README.md inline
-
-3. **Log completion**:
-   - Appends to `.specweave/logs/tasks.log`
-
-### Documentation Updates (Manual)
-
-After each task, Claude should manually update:
-
-- **CLAUDE.md**: New commands, file structure, config options, skills, agents
-- **README.md**: User-facing features, installation, usage, API changes
-- **CHANGELOG.md**: Public API changes, breaking changes, new features
-
-**Living docs sync** (via `/sw:sync-docs update`):
-- Only after ALL tasks complete
-- Updates `.specweave/docs/` with implementation learnings
-- Updates ADRs from Proposed → Accepted
-- Updates architecture diagrams with actual system
+If found: execute directly. If missing: ask user for credential.
 
 ---
 
-## Examples
-
-### Example 1: Execute Complete Increment
-
-```bash
-/sw:do 0001
-```
-
-**Output**:
-```
-📂 Loading increment 0001-user-authentication...
-
-✅ Context loaded (spec.md, plan.md, tasks.md, tests.md)
-
-🔨 Starting execution (42 tasks)...
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Task T001: Create User model
-✅ Completed | 🪝 Docs updated
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-[... continues for all 42 tasks ...]
-
-🎉 All tasks completed (42/42)
-
-Next: /sw:validate 0001 --quality
-```
-
-### Example 2: Execute with Blocker
-
-```bash
-/sw:do 0002
-```
-
-**Output**:
-```
-📂 Loading increment 0002-payment-processing...
-
-🔨 Executing tasks...
-
-Task T005: Integrate Stripe payment
-⚠️ Blocker: Stripe API key not in .env
-
-Options:
-  A) Add API key now (provide test key)
-  B) Skip for now, add as separate task
-  C) Use mock payment provider
-
-Your choice? [A/B/C]: _
-```
-
-### Example 3: Execute with Test Failure
-
-```bash
-/sw:do 0003
-```
-
-**Output**:
-```
-📂 Loading increment 0003-reporting-dashboard...
-
-Task T008: Add CSV export
-✅ Completed
-
-🧪 Running tests...
-  ✗ CSV export test failed
-    Expected: 1000 rows
-    Got: 999 rows (off-by-one error)
-
-🔧 Fixing test failure...
-   • Fixed loop boundary in src/reports/csv.ts
-
-✅ Tests now passing (12/12)
-
-🪝 Docs updated
-
-Next task: T009
-```
-
----
-
-## Error Handling
-
-### Increment Not Found
-```
-❌ Error: Increment 0001 not found
-
-Available increments:
-  • 0002-core-enhancements (planned)
-  • 0003-payment-processing (in-progress)
-
-Usage: /sw:do <increment-id>
-```
-
-### Increment Not Planned
-```
-❌ Error: Cannot execute increment 0001 (status: backlog)
-
-Increment must be "planned" before execution.
-
-Run: /sw:increment "User authentication" to plan this increment first.
-```
-
-### No Tasks to Execute
-```
-⚠️ Warning: No tasks found in tasks.md
-
-This usually means:
-  1. Tasks weren't auto-generated from plan.md
-  2. Tasks.md is empty or missing
-
-Options:
-  1. Re-plan increment: /sw:increment 0001 (regenerate tasks)
-  2. Add tasks manually: Edit .specweave/increments/0001-name/tasks.md
-```
-
----
-
-## Related Commands
-
-- `/increment`: Plan increment (creates spec.md, plan.md, tasks.md)
-- `/validate`: Validate quality before executing
-- `/specweave done`: Close increment (PM validates completion)
-- `/list-increments`: List all increments with status
-
----
-
-## Related Skills
-
-- `context-loader`: Loads relevant context (70% token reduction)
-- `nodejs-backend`: Node.js implementation knowledge
-- `python-backend`: Python implementation knowledge
-- `nextjs`: Next.js implementation knowledge
-- `frontend`: React/Vue/Angular implementation knowledge
-
----
-
----
-
-## 🔐 Auto-Execute with Credentials (MANDATORY)
-
-**When executing deployment tasks, ALWAYS follow auto-execute rules:**
-
-### The Golden Rule
-
-```
-❌ FORBIDDEN: "Next Steps: Run wrangler deploy"
-❌ FORBIDDEN: "Execute the schema in Supabase SQL Editor"
-❌ FORBIDDEN: "Set secret via: wrangler secret put..."
-
-✅ REQUIRED: Execute commands DIRECTLY using available credentials
-```
-
-### Before Any Deployment Task
-
-```bash
-# Always check for credentials FIRST (presence only - never display values!):
-grep -qE "SUPABASE|DATABASE_URL|CF_|AWS_|HETZNER" .env 2>/dev/null && echo "Credentials found in .env"
-wrangler whoami 2>/dev/null
-aws sts get-caller-identity 2>/dev/null
-gh auth status 2>/dev/null
-```
-
-### Auto-Execute Decision
-
-| Credentials Found? | Action |
-|-------------------|--------|
-| ✅ Found | Execute command directly, show success message |
-| ❌ Not found | ASK for credential (don't show manual steps) |
-
-### Example: Supabase Migration Task
-
-**If DATABASE_URL exists in .env:**
-```bash
-source .env
-psql "$DATABASE_URL" -f src/db/schema.sql
-echo "✅ Schema applied successfully"
-```
-
-**If DATABASE_URL missing:**
-```markdown
-🔐 **Credential Required**
-
-I need your Supabase database URL to execute the migration.
-
-**Please paste your DATABASE_URL:**
-[I will save to .env and execute automatically]
-```
-
----
-
-## Why "/do" instead of "/do"?
-
-**Universal applicability**: SpecWeave isn't just for software engineering!
-
-- Software projects: Writing code, tests, documentation
-- Writing projects: Chapters, articles, research papers
-- Design projects: Mockups, prototypes, design systems
-- Business projects: Reports, analyses, presentations
-- Creative projects: Scripts, storyboards, content
-
-"/do" works for any domain - it's about **executing the planned work**, whatever that work may be.
-
----
-
-**Important**: This command is designed for continuous execution. It's normal to run `/sw:do` and let it execute multiple tasks sequentially with documentation updates after each one.
-
-**Best Practice**: Always run `/sw:validate 0001 --quality` after execution to ensure quality before closing with `/sw:done`.
+Run `/sw:validate` after execution to ensure quality before closing with `/sw:done`.