specweave 1.0.76 → 1.0.78

package/CLAUDE.md

@@ -157,7 +157,7 @@ brew install omnisharp  # or: dotnet tool install -g omnisharp
 - Combine with Explore agent for comprehensive understanding
 <!-- SW:END:lsp -->
 
-<!-- SW:SECTION:structure version="1.0.60" -->
+<!-- SW:SECTION:structure version="1.0.61" -->
 ## Structure
 
 ```
@@ -170,6 +170,47 @@ brew install omnisharp  # or: dotnet tool install -g omnisharp
 └── config.json
 ```
 
+### ⚠️ CRITICAL: Increment Folder Organization (MANDATORY)
+
+**ONLY these files allowed at increment ROOT:**
+```
+.specweave/increments/####-name/
+├── metadata.json    # Increment state
+├── spec.md          # Specification
+├── plan.md          # Implementation plan
+└── tasks.md         # Task list
+```
+
+**ALL other files MUST go in subfolders:**
+```
+.specweave/increments/####-name/
+├── reports/         # Validation reports, QA reports, completion summaries
+│   └── *.md         # PM-VALIDATION-REPORT.md, qa-post-closure.md, etc.
+├── logs/            # Debug logs, execution traces, session logs
+│   └── {YYYY-MM-DD}/ # Daily logs with assets/
+├── scripts/         # Helper scripts, automation tools
+├── docs/            # Additional documentation, domain knowledge
+│   └── domain/      # Domain models for brownfield analysis
+└── backups/         # Backup files
+```
+
+**File Routing Rules:**
+| File Type | Folder | Examples |
+|-----------|--------|----------|
+| Validation reports | `reports/` | `PM-VALIDATION-REPORT.md`, `validation-report.md` |
+| QA assessments | `reports/` | `qa-post-closure.md`, `COMPLETION-SUMMARY.md` |
+| Session logs | `logs/{date}/` | `session.md`, `assets/` |
+| Domain analysis | `docs/domain/` | `appointments/domain-model.md` |
+| Helper scripts | `scripts/` | `migrate.sh`, `validate.js` |
+
+**FORBIDDEN - Files that pollute increment root:**
+```
+❌ .specweave/increments/0001/PM-VALIDATION-REPORT.md    # → reports/
+❌ .specweave/increments/0001/completion-report.md       # → reports/
+❌ .specweave/increments/0001/domain-model.md            # → docs/domain/
+❌ .specweave/increments/0001/helper.sh                  # → scripts/
+```
+
 ### ⚠️ CRITICAL: Multi-Repo Project Paths (MANDATORY)
 
 **ALL multi-project repositories MUST be created in `repositories/` folder - NEVER in project root!**
@@ -976,6 +1017,8 @@ For **contributors to SpecWeave itself** (not users).
 
 ## Marketplace Installation (CRITICAL)
 
+### For SpecWeave Contributors (Development)
+
 **ALWAYS use GitHub marketplace mode. NEVER use local symlinks or directory mode.**
 
 ```bash
@@ -996,6 +1039,32 @@ bash scripts/refresh-marketplace.sh --github
 bash scripts/refresh-marketplace.sh  # Defaults to --github
 ```
 
+### For End Users (Production)
+
+**Users install SpecWeave globally and use CLI commands:**
+
+```bash
+# Install SpecWeave globally
+npm install -g specweave
+
+# Initialize project (first time)
+specweave init .
+
+# Update marketplace plugins (gets latest from GitHub)
+specweave refresh-marketplace
+
+# Update instruction files (CLAUDE.md, AGENTS.md)
+specweave update-instructions
+```
+
+**After marketplace updates**: Restart Claude Code for changes to take effect.
+
+**Verify installation**:
+```bash
+specweave --version              # Check SpecWeave version
+/plugin list --installed         # In Claude Code - check plugins loaded
+```
+
 ---
 
 ## Critical Safety Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.76",
+  "version": "1.0.78",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/plugins/specweave/agents/pm/AGENT.md

@@ -155,18 +155,22 @@ Before you finish ANY response, mentally verify:
 **MANDATORY subfolder organization**:
 ```
 .specweave/increments/####-name/
+├── metadata.json        # ✅ Core file (auto-managed)
 ├── spec.md              # ✅ ONLY core file 1
 ├── plan.md              # ✅ ONLY core file 2
 ├── tasks.md             # ✅ ONLY core file 3
 ├── reports/             # ✅ ALL reports here
 │   ├── PM-VALIDATION-REPORT.md
 │   ├── COMPLETION-SUMMARY.md
-│   ├── SESSION-NOTES.md
-│   └── ANALYSIS-*.md
+│   ├── qa-post-closure.md
+│   └── validation-report.md
 ├── scripts/             # ✅ ALL scripts here
 │   └── helper-*.sh
-└── logs/                # ✅ ALL logs here
-    └── execution.log
+├── logs/                # ✅ ALL logs here
+│   └── {YYYY-MM-DD}/session.md
+├── docs/                # ✅ Additional documentation
+│   └── domain/          # Domain models (brownfield)
+└── backups/             # ✅ Backup files
 ```
 
 **When writing ANY file**:
@@ -174,6 +178,7 @@ Before you finish ANY response, mentally verify:
 - ✅ **ALWAYS** write reports to `reports/` subfolder
 - ✅ **ALWAYS** write scripts to `scripts/` subfolder
 - ✅ **ALWAYS** write logs to `logs/` subfolder
+- ✅ **ALWAYS** write additional docs to `docs/` subfolder
 
 **Example correct paths**:
 - ✅ `.specweave/increments/0001-auth/reports/PM-VALIDATION-REPORT.md`

package/plugins/specweave/commands/auto.md

@@ -354,6 +354,28 @@ Pure Ralph Wiggum behavior:
 - **Max Iterations**: Prevents runaway loops (2500 default)
 - **Max Hours**: Time boxing (600 hours / 25 days default)
 - **stop_hook_active**: Prevents infinite continuation loops
+- **Sound Notifications** (v2.6): Audible alerts when Claude stops working
+
+## 🔔 Sound Notifications (NEW in v2.6!)
+
+**Auto mode plays a satisfying sound when work completes successfully!**
+
+### When Sound Plays
+
+| Event | Sound | Platforms | Meaning |
+|-------|-------|-----------|---------|
+| **Session Complete (Success)** ✅ | Glass.aiff (macOS)<br>complete.oga (Linux)<br>Windows Notify (Windows) | All | All tasks done, tests passing - work finished! |
+
+**Sound plays ONLY on complete success** - when all tasks are done AND all tests pass. This way you know when to check back without being interrupted during ongoing work.
+
+### Cross-Platform Support
+
+The sound notification works automatically on:
+- **macOS**: Glass.aiff (satisfying chime)
+- **Linux**: PulseAudio/ALSA/speaker-test fallbacks
+- **Windows**: PowerShell beeps
+
+Sounds fail gracefully on systems without audio support.
 
 ## 🔧 v2.3 Per-Agent Stop Hook Behavior (NEW!)
 

package/plugins/specweave/commands/save.md

@@ -44,19 +44,116 @@ The `/sw:save` command uses a **three-tier detection strategy**:
    - Works for microservices architectures without explicit configuration
 3. **Parent Project** - Always includes the root project if it has `.git`
 
+#### Git-Scan Algorithm (CRITICAL for Microservices)
+
+**MANDATORY: When no umbrella config exists, ALWAYS scan for nested repos:**
+
+```bash
+# Step 1: Find all nested .git directories (excluding .git itself and node_modules)
+find . -maxdepth 4 -type d -name ".git" \
+  -not -path "./.git" \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.specweave/*" \
+  2>/dev/null
+
+# Step 2: For each .git found, the parent directory is a repo
+# Example output:
+#   ./repositories/frontend/.git    → repositories/frontend is a repo
+#   ./repositories/backend/.git     → repositories/backend is a repo
+#   ./packages/shared/.git          → packages/shared is a repo
+```
+
+**Priority scan paths** (check these first for performance):
+1. `repositories/*/`  - Standard SpecWeave multi-repo layout
+2. `packages/*/`      - Monorepo packages
+3. `services/*/`      - Microservices
+4. `apps/*/`          - App directories
+5. `libs/*/`          - Library directories
+
+**Full discovery example:**
+
+```bash
+# Discovery script that /sw:save internally executes
+REPOS=()
+
+# 1. Check umbrella config first
+if [ -f ".specweave/config.json" ]; then
+  UMBRELLA_REPOS=$(jq -r '.umbrella.childRepos[]?.path // empty' .specweave/config.json 2>/dev/null)
+  if [ -n "$UMBRELLA_REPOS" ]; then
+    while IFS= read -r repo; do
+      [ -d "$repo/.git" ] && REPOS+=("$repo")
+    done <<< "$UMBRELLA_REPOS"
+  fi
+fi
+
+# 2. If no umbrella config OR it's empty, scan for nested repos
+if [ ${#REPOS[@]} -eq 0 ]; then
+  # Scan priority paths first
+  for dir in repositories packages services apps libs; do
+    if [ -d "$dir" ]; then
+      for repo in "$dir"/*/; do
+        [ -d "${repo}.git" ] && REPOS+=("${repo%/}")
+      done
+    fi
+  done
+
+  # Full recursive scan if nothing found in priority paths
+  if [ ${#REPOS[@]} -eq 0 ]; then
+    while IFS= read -r git_dir; do
+      REPOS+=("$(dirname "$git_dir")")
+    done < <(find . -maxdepth 4 -type d -name ".git" -not -path "./.git" -not -path "*/node_modules/*" 2>/dev/null)
+  fi
+fi
+
+# 3. Always include parent project if it has .git
+[ -d ".git" ] && REPOS+=(".")
+
+# Result: REPOS array contains all repositories to process
+echo "Discovered repos: ${REPOS[*]}"
+```
+
 **Example: Microservices without config**
 
 ```
-my-project/                    # ← Parent repo (included)
+my-project/                    # ← Parent repo (included via tier 3)
 ├── repositories/
-│   ├── frontend/              # ← Auto-discovered
-│   ├── backend/               # ← Auto-discovered
-│   └── shared-lib/            # ← Auto-discovered
+│   ├── frontend/              # ← Auto-discovered via tier 2
+│   │   └── .git
+│   ├── backend/               # ← Auto-discovered via tier 2
+│   │   └── .git
+│   └── shared-lib/            # ← Auto-discovered via tier 2
+│       └── .git
 └── .specweave/
 ```
 
 Running `/sw:save` will detect and commit+push to **all 4 repositories** automatically!
 
+**Microservices in `services/` folder:**
+```
+my-platform/
+├── services/
+│   ├── auth-service/          # ← Auto-discovered
+│   │   └── .git
+│   ├── payment-service/       # ← Auto-discovered
+│   │   └── .git
+│   └── notification-service/  # ← Auto-discovered
+│       └── .git
+└── .specweave/
+```
+
+**Monorepo with `packages/`:**
+```
+my-monorepo/
+├── packages/
+│   ├── frontend/              # ← Auto-discovered
+│   │   └── .git
+│   ├── backend/               # ← Auto-discovered
+│   │   └── .git
+│   └── shared/                # ← Auto-discovered
+│       └── .git
+└── .git                       # ← Parent repo also included
+```
+
 ## Usage
 
 ```bash

package/plugins/specweave/hooks/README.md

@@ -117,6 +117,36 @@ Core hooks automate SpecWeave's fundamental workflows:
 
 ---
 
+### 5. `stop-auto.sh` (Auto Mode)
+**Triggers**: When Claude tries to exit during autonomous execution (`/sw:auto`)
+
+**Actions**:
+1. Checks if all tasks are complete
+2. Validates test execution (unit + E2E)
+3. Verifies completion criteria met
+4. Blocks exit if work incomplete
+5. Re-feeds prompt to continue iteration
+
+**Configuration**: Registered in `hooks/hooks.json`:
+```json
+{
+  "hooks": {
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-auto.sh"
+      }]
+    }]
+  }
+}
+```
+
+**Use case**: Enables autonomous execution loops. Claude works until ALL tasks complete and tests pass, then gracefully exits.
+
+**See**: `/sw:auto` command documentation for full auto mode details.
+
+---
+
 ## How Hooks Work (Claude Code Native)
 
 **CRITICAL**: Hooks are **NOT copied** to `.claude/hooks/`. They stay in `plugins/specweave/hooks/` and Claude Code discovers them automatically.

package/plugins/specweave/hooks/hooks.json

@@ -31,6 +31,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-auto.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/plugins/specweave/hooks/stop-auto.sh

@@ -12,7 +12,14 @@
 # - Extracts specific failure details for fix prompts
 # - Blocks on ANY test failure (not just >3)
 #
-# IMPORTANT (v2.3): Stop hook runs PER AGENT
+# AGENT HIERARCHY LABELS (v2.4):
+# - Detects agent type: MAIN ORCHESTRATOR vs SUBAGENT
+# - Clear session stop/continue labels with box art
+# - Shows "WHEN WILL SESSION STOP?" criteria prominently
+# - Subagents show "Returns to: Main Orchestrator" on completion
+# - Tracks subagent spawns in session stats
+#
+# IMPORTANT (v2.3+): Stop hook runs PER AGENT
 # - Each spawned subagent (Task tool) gets its own stop hook invocation
 # - Iteration count is SHARED across all agents via session file
 # - Parent agent's exit triggers hook, subagent exits do NOT by default
@@ -317,6 +324,196 @@ get_coverage_targets() {
     fi
 }
 
+# ============================================================================
+# AGENT TYPE DETECTION & HIERARCHY (NEW - v2.4)
+# Distinguishes main orchestrator from subagents for clear labeling
+# ============================================================================
+
+# Agent type constants
+AGENT_TYPE_ORCHESTRATOR="orchestrator"
+AGENT_TYPE_SUBAGENT="subagent"
+
+# Detect if this is main orchestrator or a subagent
+# Returns: "orchestrator" or "subagent:<type>"
+detect_agent_type() {
+    local transcript="$1"
+
+    # No transcript = assume orchestrator
+    if [ -z "$transcript" ] || [ ! -f "$transcript" ]; then
+        echo "$AGENT_TYPE_ORCHESTRATOR"
+        return
+    fi
+
+    # Check for /sw:auto command - indicates main orchestrator
+    if grep -qE '(/sw:auto|/specweave:auto|setup-auto\.sh)' "$transcript" 2>/dev/null; then
+        echo "$AGENT_TYPE_ORCHESTRATOR"
+        return
+    fi
+
+    # Check for subagent invocation patterns in transcript
+    # Subagents are spawned via Task tool with subagent_type parameter
+    local subagent_pattern='subagent_type.*?["\x27]([^"\x27]+)["\x27]'
+    local subagent_match=$(grep -oE 'subagent_type["\x27]*:\s*["\x27]?[a-zA-Z0-9_:-]+' "$transcript" 2>/dev/null | tail -1)
+
+    if [ -n "$subagent_match" ]; then
+        # Extract the type name
+        local agent_name=$(echo "$subagent_match" | sed 's/.*["\x27]\([^"\x27]*\)["\x27].*/\1/' | sed 's/subagent_type["\x27]*:\s*["\x27]*//')
+        if [ -n "$agent_name" ] && [ "$agent_name" != "subagent_type" ]; then
+            echo "$AGENT_TYPE_SUBAGENT:$agent_name"
+            return
+        fi
+    fi
+
+    # Check for specialized agent prompts (subagent indicators)
+    if grep -qE '(You are a specialized agent|Task tool|subagent|Agent type:)' "$transcript" 2>/dev/null; then
+        # Try to extract agent type from common patterns
+        local agent_desc=$(grep -oE '(architect|qa-engineer|security|devops|frontend|backend|ml-engineer|data-scientist|sre|tech-lead|docs-writer)' "$transcript" 2>/dev/null | head -1)
+        if [ -n "$agent_desc" ]; then
+            echo "$AGENT_TYPE_SUBAGENT:$agent_desc"
+            return
+        fi
+        echo "$AGENT_TYPE_SUBAGENT:unknown"
+        return
+    fi
+
+    # Default to orchestrator if no subagent patterns found
+    echo "$AGENT_TYPE_ORCHESTRATOR"
+}
+
+# Get human-readable agent display name
+# Input: agent type from detect_agent_type()
+# Output: formatted display name
+get_agent_display_name() {
+    local agent_type="$1"
+
+    case "$agent_type" in
+        orchestrator)
+            echo "🤖 MAIN ORCHESTRATOR"
+            ;;
+        subagent:*)
+            local subtype="${agent_type#subagent:}"
+            # Format common agent types nicely
+            case "$subtype" in
+                sw:architect:architect|architect)
+                    echo "🏗️  SUBAGENT: System Architect"
+                    ;;
+                sw:tech-lead:tech-lead|tech-lead)
+                    echo "👨‍💻 SUBAGENT: Tech Lead"
+                    ;;
+                sw:qa-lead:qa-lead|qa-lead|qa-engineer)
+                    echo "🧪 SUBAGENT: QA Engineer"
+                    ;;
+                sw:security:security|security)
+                    echo "🔐 SUBAGENT: Security Engineer"
+                    ;;
+                sw-infra:devops:devops|devops)
+                    echo "🚀 SUBAGENT: DevOps Engineer"
+                    ;;
+                sw-frontend:frontend-architect:*|frontend*)
+                    echo "🎨 SUBAGENT: Frontend Architect"
+                    ;;
+                sw-backend:*|backend*)
+                    echo "⚙️  SUBAGENT: Backend Engineer"
+                    ;;
+                sw-ml:ml-engineer:*|ml-engineer)
+                    echo "🧠 SUBAGENT: ML Engineer"
+                    ;;
+                sw-ml:data-scientist:*|data-scientist)
+                    echo "📊 SUBAGENT: Data Scientist"
+                    ;;
+                sw-infra:sre:sre|sre)
+                    echo "🔧 SUBAGENT: SRE"
+                    ;;
+                sw:docs-writer:*|docs-writer)
+                    echo "📝 SUBAGENT: Docs Writer"
+                    ;;
+                Explore|explore)
+                    echo "🔍 SUBAGENT: Explorer"
+                    ;;
+                Plan|plan)
+                    echo "📋 SUBAGENT: Planner"
+                    ;;
+                unknown)
+                    echo "🔧 SUBAGENT: Specialized Agent"
+                    ;;
+                *)
+                    echo "🔧 SUBAGENT: $subtype"
+                    ;;
+            esac
+            ;;
+        *)
+            echo "🤖 AGENT: $agent_type"
+            ;;
+    esac
+}
+
+# Get short agent type for JSON logging
+get_agent_type_short() {
+    local agent_type="$1"
+
+    case "$agent_type" in
+        orchestrator)
+            echo "main"
+            ;;
+        subagent:*)
+            echo "${agent_type#subagent:}"
+            ;;
+        *)
+            echo "$agent_type"
+            ;;
+    esac
+}
+
+# Detect recent subagent activity from transcript
+# Returns JSON with subagent stats
+detect_subagent_activity() {
+    local transcript="$1"
+
+    if [ -z "$transcript" ] || [ ! -f "$transcript" ]; then
+        echo '{"spawned":0,"types":[]}'
+        return
+    fi
+
+    # Count Task tool invocations
+    local task_count=$(grep -c 'Task tool\|subagent_type\|<invoke name="Task">' "$transcript" 2>/dev/null || echo "0")
+
+    # Extract unique agent types
+    local agent_types=$(grep -oE 'subagent_type["\x27]*:\s*["\x27]?[a-zA-Z0-9_:-]+' "$transcript" 2>/dev/null | \
+        sed 's/subagent_type["\x27]*:\s*["\x27]*//' | \
+        sort -u | \
+        head -10 | \
+        jq -R -s 'split("\n") | map(select(length > 0))' 2>/dev/null || echo '[]')
+
+    echo "{\"spawned\":$task_count,\"types\":$agent_types}"
+}
+
+# Track subagent in session (called when subagent activity detected)
+track_subagent_spawn() {
+    local agent_type="$1"
+    local short_type=$(get_agent_type_short "$agent_type")
+
+    if [ -f "$SESSION_FILE" ]; then
+        local updated=$(cat "$SESSION_FILE" | jq \
+            --arg type "$short_type" \
+            --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            '.subagentStats.totalSpawned = ((.subagentStats.totalSpawned // 0) + 1) |
+             .subagentStats.lastSpawned = $type |
+             .subagentStats.lastSpawnTime = $now |
+             .subagentStats.history = ((.subagentStats.history // []) + [{"type": $type, "time": $now}]) |
+             .subagentStats.history = (.subagentStats.history | if length > 20 then .[-20:] else . end)')
+        echo "$updated" > "$SESSION_FILE"
+    fi
+}
+
+# Get subagent stats from session
+get_subagent_stats() {
+    if [ -f "$SESSION_FILE" ]; then
+        jq -r '.subagentStats // {"totalSpawned":0,"history":[]}' "$SESSION_FILE"
+    else
+        echo '{"totalSpawned":0,"history":[]}'
+    fi
+}
+
 # ============================================================================
 # STOP REASON TRACKING (NEW - v2.2)
 # Clear logging of WHY auto mode stops
@@ -373,74 +570,236 @@ detect_command_timeout() {
     fi
 }
 
+# ================================================================
+# SOUND NOTIFICATION HELPER (v2.6)
+# Cross-platform sound notification for user awareness
+# ================================================================
+play_notification_sound() {
+    local sound_type="${1:-attention}"  # "success" or "attention"
+
+    # Detect OS and play appropriate sound
+    case "$(uname -s)" in
+        Darwin)
+            # macOS - use afplay with system sounds
+            if [ "$sound_type" = "success" ]; then
+                afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+            else
+                afplay /System/Library/Sounds/Ping.aiff 2>/dev/null &
+            fi
+            ;;
+        Linux)
+            # Linux - try multiple sound systems (paplay, aplay, speaker-test)
+            if command -v paplay >/dev/null 2>&1; then
+                # PulseAudio (most common on modern Linux)
+                if [ "$sound_type" = "success" ]; then
+                    paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null &
+                else
+                    paplay /usr/share/sounds/freedesktop/stereo/bell.oga 2>/dev/null &
+                fi
+            elif command -v aplay >/dev/null 2>&1; then
+                # ALSA fallback
+                aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null &
+            elif command -v speaker-test >/dev/null 2>&1; then
+                # Last resort - system beep
+                speaker-test -t sine -f 1000 -l 1 >/dev/null 2>&1 &
+            fi
+            ;;
+        MINGW*|MSYS*|CYGWIN*)
+            # Windows (Git Bash, WSL, Cygwin)
+            if command -v powershell.exe >/dev/null 2>&1; then
+                # Use PowerShell to play sound
+                if [ "$sound_type" = "success" ]; then
+                    powershell.exe -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\Windows Notify System Generic.wav').PlaySync();" 2>/dev/null &
+                else
+                    powershell.exe -c "[console]::beep(800, 300)" 2>/dev/null &
+                fi
+            fi
+            ;;
+    esac
+}
+
 # Helper: Output approve decision
 # ALWAYS log why we're stopping for debugging
+# Enhanced v2.4: Agent-aware labeling with clear hierarchy
 approve() {
     local reason="${1:-Session complete}"
     local is_success="${2:-false}"
 
-    # Log the stop reason
-    log_stop_reason "$reason" "approve_called" "$is_success"
+    # Detect agent type for proper labeling
+    local agent_type=$(detect_agent_type "$TRANSCRIPT_PATH")
+    local agent_display=$(get_agent_display_name "$agent_type")
+    local agent_short=$(get_agent_type_short "$agent_type")
+
+    # Get subagent stats for summary
+    local subagent_stats=$(get_subagent_stats)
+    local subagents_spawned=$(echo "$subagent_stats" | jq -r '.totalSpawned // 0')
+
+    # Log the stop reason with agent info
+    log_stop_reason "$reason" "approve_called:$agent_short" "$is_success"
+
+    # Get test breakdown by type if available (NEW - v2.5)
+    local test_breakdown=$(get_test_type_breakdown "$TRANSCRIPT_PATH")
 
     # Display the stop reason prominently to STDERR (not stdout, which is for JSON)
     {
         echo ""
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "🛑 AUTO MODE STOPPING"
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-        echo "Reason: $reason"
-        echo "Iteration: ${ITERATION:-0}/${MAX_ITERATIONS:-100}"
-        [ -n "$CURRENT_INCREMENT" ] && echo "Increment: $CURRENT_INCREMENT"
-        [ "${TESTS_RUN:-false}" = "true" ] && echo "Tests: ${TESTS_PASSED:-0} passed, ${TESTS_FAILED:-0} failed"
-        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        if [ "$agent_type" = "orchestrator" ]; then
+            # Main orchestrator stopping - this is a SESSION END
+            if [ "$is_success" = "true" ]; then
+                echo "┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓"
+                echo "┃  ✅ AUTO SESSION COMPLETE                                   ┃"
+                echo "┃  $agent_display                                  ┃"
+                echo "┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫"
+                echo "┃  Status: SUCCESS - All work completed                       ┃"
+            else
+                echo "┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓"
+                echo "┃  🛑 AUTO SESSION STOPPING                                   ┃"
+                echo "┃  $agent_display                                  ┃"
+                echo "┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫"
+                echo "┃  Status: STOPPED - Requires attention                       ┃"
+            fi
+            echo "┃  Reason: $(printf '%-48s' "$reason")┃"
+            echo "┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫"
+            echo "┃  📊 SESSION SUMMARY                                         ┃"
+            echo "┃  ├─ Iterations: ${ITERATION:-0}/${MAX_ITERATIONS:-100}                                       ┃"
+            [ -n "$CURRENT_INCREMENT" ] && echo "┃  ├─ Increment: $(printf '%-42s' "$CURRENT_INCREMENT")┃"
+            [ "$subagents_spawned" -gt 0 ] && echo "┃  ├─ Subagents spawned: $(printf '%-35s' "$subagents_spawned")┃"
+            if [ "${TESTS_RUN:-false}" = "true" ]; then
+                if [ -n "$test_breakdown" ] && [ "$test_breakdown" != "{}" ]; then
+                    # Show detailed breakdown by test type (NEW - v2.5)
+                    echo "┃  └─ Tests (detailed breakdown):                             ┃"
+                    local unit_passed=$(echo "$test_breakdown" | jq -r '.unit.passed // 0')
+                    local unit_failed=$(echo "$test_breakdown" | jq -r '.unit.failed // 0')
+                    local integration_passed=$(echo "$test_breakdown" | jq -r '.integration.passed // 0')
+                    local integration_failed=$(echo "$test_breakdown" | jq -r '.integration.failed // 0')
+                    local e2e_passed=$(echo "$test_breakdown" | jq -r '.e2e.passed // 0')
+                    local e2e_failed=$(echo "$test_breakdown" | jq -r '.e2e.failed // 0')
+
+                    if [ "$unit_passed" -gt 0 ] || [ "$unit_failed" -gt 0 ]; then
+                        echo "┃     • Unit: ${unit_passed} passed, ${unit_failed} failed                              ┃"
+                    fi
+                    if [ "$integration_passed" -gt 0 ] || [ "$integration_failed" -gt 0 ]; then
+                        echo "┃     • Integration: ${integration_passed} passed, ${integration_failed} failed                      ┃"
+                    fi
+                    if [ "$e2e_passed" -gt 0 ] || [ "$e2e_failed" -gt 0 ]; then
+                        echo "┃     • E2E: ${e2e_passed} passed, ${e2e_failed} failed                                  ┃"
+                    fi
+                else
+                    # Fallback to simple summary
+                    echo "┃  └─ Tests: ${TESTS_PASSED:-0} passed, ${TESTS_FAILED:-0} failed                            ┃"
+                fi
+            fi
+            echo "┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛"
+
+            # ================================================================
+            # SOUND NOTIFICATION ON SUCCESS (v2.6)
+            # Play sound ONLY when session completes successfully
+            # This lets users know they can check back - work is done!
+            # Cross-platform support via helper function
+            # ================================================================
+            if [ "$is_success" = "true" ]; then
+                play_notification_sound "success"
+            fi
+        else
+            # Subagent stopping - this is a RETURN TO PARENT
+            echo "┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓"
+            echo "┃  ↩️  SUBAGENT COMPLETE - Returning to parent               ┃"
+            echo "┃  $agent_display                                  ┃"
+            echo "┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫"
+            echo "┃  Result: $(printf '%-49s' "$reason")┃"
+            echo "┃  ↩️  Control returning to: 🤖 Main Orchestrator            ┃"
+            echo "┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛"
+        fi
         echo ""
     } >&2
 
-    echo "{\"decision\": \"approve\", \"reason\": \"$reason\"}"
+    echo "{\"decision\": \"approve\", \"reason\": \"$reason\", \"agentType\": \"$agent_short\"}"
     exit 0
 }
 
 # Helper: Output block decision with system message
 # Properly escapes JSON strings with newlines
-# Also displays stop criteria prominently to stderr (NEW - v2.2, enhanced v2.3)
+# Enhanced v2.4: Agent-aware labeling with clear hierarchy and stop conditions
 block() {
     local reason="$1"
     local system_message="$2"
 
+    # Detect agent type for proper labeling
+    local agent_type=$(detect_agent_type "$TRANSCRIPT_PATH")
+    local agent_display=$(get_agent_display_name "$agent_type")
+    local agent_short=$(get_agent_type_short "$agent_type")
+
     # Get current stop criteria for display
     local tdd_mode=$(is_tdd_strict_mode)
     local stop_criteria=""
+    local stop_criteria_detail=""
 
-    # Build stop criteria message - MORE PROMINENT (v2.3)
+    # Build stop criteria message - MORE PROMINENT (v2.4)
     if [ "$tdd_mode" = "true" ]; then
-        stop_criteria="🔴 TDD MODE: ALL tasks [x] + ALL tests GREEN (0 failures)"
+        stop_criteria="TDD STRICT MODE"
+        stop_criteria_detail="ALL tasks [x] + ALL tests GREEN (0 failures)"
     else
-        stop_criteria="✅ ALL tasks [x] completed + tests passing"
+        stop_criteria="STANDARD MODE"
+        stop_criteria_detail="ALL tasks [x] completed + tests passing"
     fi
 
-    # Display stop criteria and continuation reason to STDERR (v2.3 enhanced)
+    # Get subagent activity for display
+    local subagent_stats=$(get_subagent_stats)
+    local subagents_spawned=$(echo "$subagent_stats" | jq -r '.totalSpawned // 0')
+
+    # Display stop criteria and continuation reason to STDERR (v2.4 enhanced)
     {
         echo ""
-        echo "╔══════════════════════════════════════════════════════════════╗"
-        echo "║  🔄 AUTO MODE CONTINUING - Agent will keep working           ║"
-        echo "╠══════════════════════════════════════════════════════════════╣"
-        echo "║  Reason: $(printf '%-50s' "$reason")║"
-        echo "║  Iteration: $(printf '%-47s' "${ITERATION:-0}/${MAX_ITERATIONS:-2500}")║"
-        [ -n "$CURRENT_INCREMENT" ] && echo "║  Increment: $(printf '%-47s' "$CURRENT_INCREMENT")║"
-        echo "╠══════════════════════════════════════════════════════════════╣"
-        echo "║  🎯 STOP CONDITION: $stop_criteria"
-        [ "${TESTS_RUN:-false}" = "true" ] && echo "║     Tests: ${TESTS_PASSED:-0} passed, ${TESTS_FAILED:-0} failed"
-        [ "$tdd_mode" = "true" ] && echo "║     TDD Source: $(get_tdd_source)"
-        echo "╚══════════════════════════════════════════════════════════════╝"
+        if [ "$agent_type" = "orchestrator" ]; then
+            # Main orchestrator continuing - SESSION CONTINUES
+            echo "╔══════════════════════════════════════════════════════════════╗"
+            echo "║  🔄 AUTO SESSION CONTINUING                                  ║"
+            echo "║  $agent_display                                  ║"
+            echo "╠══════════════════════════════════════════════════════════════╣"
+            echo "║  Why: $(printf '%-52s' "$reason")║"
+            echo "║  Iteration: $(printf '%-47s' "${ITERATION:-0}/${MAX_ITERATIONS:-2500}")║"
+            [ -n "$CURRENT_INCREMENT" ] && echo "║  Increment: $(printf '%-47s' "$CURRENT_INCREMENT")║"
+            [ "$subagents_spawned" -gt 0 ] && echo "║  Subagents used: $(printf '%-42s' "$subagents_spawned")║"
+            echo "╠══════════════════════════════════════════════════════════════╣"
+            echo "║  🎯 WHEN WILL SESSION STOP?                                  ║"
+            echo "║  ├─ Mode: $(printf '%-48s' "$stop_criteria")║"
+            echo "║  └─ Criteria: $(printf '%-44s' "$stop_criteria_detail")║"
+            if [ "${TESTS_RUN:-false}" = "true" ]; then
+                if [ "${TESTS_FAILED:-0}" -gt 0 ]; then
+                    echo "║  ⚠️  Tests: ${TESTS_PASSED:-0} passed, ${TESTS_FAILED:-0} FAILED (blocking!)             ║"
+                else
+                    echo "║  ✅ Tests: ${TESTS_PASSED:-0} passed, 0 failed                             ║"
+                fi
+            else
+                echo "║  ⏳ Tests: NOT YET RUN                                       ║"
+            fi
+            [ "$tdd_mode" = "true" ] && echo "║  📋 TDD Source: $(printf '%-42s' "$(get_tdd_source)")║"
+            echo "╚══════════════════════════════════════════════════════════════╝"
+        else
+            # Subagent continuing - SUBAGENT KEEPS WORKING
+            echo "╔══════════════════════════════════════════════════════════════╗"
+            echo "║  🔧 SUBAGENT CONTINUING WORK                                 ║"
+            echo "║  $agent_display                                  ║"
+            echo "╠══════════════════════════════════════════════════════════════╣"
+            echo "║  Task: $(printf '%-51s' "$reason")║"
+            echo "╠══════════════════════════════════════════════════════════════╣"
+            echo "║  🎯 WHEN WILL SUBAGENT RETURN?                               ║"
+            echo "║  └─ When assigned task is complete                           ║"
+            echo "║  ↩️  Returns to: 🤖 Main Orchestrator                         ║"
+            echo "╚══════════════════════════════════════════════════════════════╝"
+        fi
         echo ""
     } >&2
 
+    # NOTE: No sound notification on block - sounds only play on SUCCESS
+    # When Claude is continuing work, user doesn't need to be notified
+
     if [ -n "$system_message" ]; then
         # Escape special characters for JSON
         local escaped_message=$(echo "$system_message" | jq -Rs .)
-        echo "{\"decision\": \"block\", \"reason\": \"$reason\", \"systemMessage\": $escaped_message}"
+        echo "{\"decision\": \"block\", \"reason\": \"$reason\", \"systemMessage\": $escaped_message, \"agentType\": \"$agent_short\"}"
     else
-        echo "{\"decision\": \"block\", \"reason\": \"$reason\"}"
+        echo "{\"decision\": \"block\", \"reason\": \"$reason\", \"agentType\": \"$agent_short\"}"
     fi
     exit 0
 }
@@ -859,6 +1218,80 @@ parse_test_results() {
     echo "{\"passed\":$passed,\"failed\":$failed,\"total\":$total,\"framework\":\"$framework\",\"testsRun\":$tests_run}"
 }
 
+# ============================================================================
+# TEST TYPE BREAKDOWN (NEW - v2.5)
+# Categorizes test results by type (unit/integration/E2E) for detailed summary
+# ============================================================================
+
+# Get test type breakdown from transcript
+# Returns: JSON with {unit: {passed, failed}, integration: {passed, failed}, e2e: {passed, failed}}
+get_test_type_breakdown() {
+    local transcript="$1"
+
+    if [ ! -f "$transcript" ]; then
+        echo "{}"
+        return
+    fi
+
+    local unit_passed=0
+    local unit_failed=0
+    local integration_passed=0
+    local integration_failed=0
+    local e2e_passed=0
+    local e2e_failed=0
+
+    # Check for test command patterns to categorize
+    # Unit tests: vitest, jest, pytest, go test
+    if grep -qE '(npm.*test:unit|npx vitest|npx jest|pytest|go test|cargo test)' "$transcript" 2>/dev/null; then
+        # Parse unit test results
+        local unit_result=$(grep -oE 'Tests?\s+[0-9]+\s+passed' "$transcript" 2>/dev/null | tail -1)
+        if [ -n "$unit_result" ]; then
+            unit_passed=$(echo "$unit_result" | grep -oE '[0-9]+' | head -1)
+            local unit_failed_match=$(grep -oE '[0-9]+\s+failed' "$transcript" 2>/dev/null | tail -1 | grep -oE '[0-9]+' || echo "0")
+            unit_failed=${unit_failed_match:-0}
+        fi
+    fi
+
+    # Integration tests: usually named test:integration
+    if grep -qE 'npm.*test:integration' "$transcript" 2>/dev/null; then
+        # Parse integration test results (same format as unit)
+        local int_result=$(grep -oE 'Tests?\s+[0-9]+\s+passed' "$transcript" 2>/dev/null | tail -1)
+        if [ -n "$int_result" ]; then
+            integration_passed=$(echo "$int_result" | grep -oE '[0-9]+' | head -1)
+            local int_failed_match=$(grep -oE '[0-9]+\s+failed' "$transcript" 2>/dev/null | tail -1 | grep -oE '[0-9]+' || echo "0")
+            integration_failed=${int_failed_match:-0}
+        fi
+    fi
+
+    # E2E tests: Playwright, Cypress, Detox, Maestro
+    if grep -qE '(npx playwright|npx cypress|npx detox|maestro test|test:e2e)' "$transcript" 2>/dev/null; then
+        # Parse E2E test results
+        local e2e_passed_match=$(grep -oE '[0-9]+\s+passed' "$transcript" 2>/dev/null | tail -1 | grep -oE '[0-9]+')
+        local e2e_failed_match=$(grep -oE '[0-9]+\s+failed' "$transcript" 2>/dev/null | tail -1 | grep -oE '[0-9]+')
+
+        e2e_passed=${e2e_passed_match:-0}
+        e2e_failed=${e2e_failed_match:-0}
+    fi
+
+    # Return JSON with breakdown
+    cat <<EOF
+{
+  "unit": {
+    "passed": $unit_passed,
+    "failed": $unit_failed
+  },
+  "integration": {
+    "passed": $integration_passed,
+    "failed": $integration_failed
+  },
+  "e2e": {
+    "passed": $e2e_passed,
+    "failed": $e2e_failed
+  }
+}
+EOF
+}
+
 # Extract detailed failure information from transcript
 # Returns: JSON with failure details
 extract_failure_details() {
@@ -1787,7 +2220,30 @@ Continue with /sw:do and add missing E2E tests."
                     --argjson passed "${TESTS_PASSED:-0}" --argjson failed "${TESTS_FAILED:-0}" \
                     '.status = "completed" | .endTime = $now | .endReason = "all_tasks_complete" | .finalTestResults = {"passed": $passed, "failed": $failed}' \
                     > "$SESSION_FILE"
-                approve "All tasks completed, all tests passed ($TESTS_PASSED passed, 0 failed)" "true"
+
+                # Build detailed completion reason with test breakdown (NEW - v2.5)
+                local completion_reason="All tasks completed"
+                local test_breakdown=$(get_test_type_breakdown "$TRANSCRIPT_PATH")
+                if [ -n "$test_breakdown" ] && [ "$test_breakdown" != "{}" ]; then
+                    local unit_p=$(echo "$test_breakdown" | jq -r '.unit.passed // 0')
+                    local int_p=$(echo "$test_breakdown" | jq -r '.integration.passed // 0')
+                    local e2e_p=$(echo "$test_breakdown" | jq -r '.e2e.passed // 0')
+
+                    local test_details=""
+                    [ "$unit_p" -gt 0 ] && test_details="${test_details}${unit_p} unit"
+                    [ "$int_p" -gt 0 ] && test_details="${test_details}${test_details:+, }${int_p} integration"
+                    [ "$e2e_p" -gt 0 ] && test_details="${test_details}${test_details:+, }${e2e_p} E2E"
+
+                    if [ -n "$test_details" ]; then
+                        completion_reason="$completion_reason, tests passed: $test_details"
+                    else
+                        completion_reason="$completion_reason, all tests passed ($TESTS_PASSED passed, 0 failed)"
+                    fi
+                else
+                    completion_reason="$completion_reason, all tests passed ($TESTS_PASSED passed, 0 failed)"
+                fi
+
+                approve "$completion_reason" "true"
             else
                 # More increments in queue - transition to next
                 NEXT_INCREMENT=$(echo "$SESSION" | jq -r '.incrementQueue[1] // null')
@@ -1909,7 +2365,15 @@ echo "$SESSION" | jq --argjson iter "$NEXT_ITERATION" --arg now "$(date -u +%Y-%
     '.iteration = $iter | .lastActivity = $now' \
     > "$SESSION_FILE"
 
-# Build context message with test instructions (v2.2)
+# Build context message with test instructions (v2.4 enhanced with agent hierarchy)
+# Detect agent type for context message
+AGENT_TYPE=$(detect_agent_type "$TRANSCRIPT_PATH")
+AGENT_DISPLAY=$(get_agent_display_name "$AGENT_TYPE")
+
+# Get subagent activity for context
+SUBAGENT_ACTIVITY=$(detect_subagent_activity "$TRANSCRIPT_PATH")
+SUBAGENT_COUNT=$(echo "$SUBAGENT_ACTIVITY" | jq -r '.spawned // 0')
+
 if [ "$SIMPLE_MODE" = "true" ]; then
     CONTEXT="Continue working. Iteration $NEXT_ITERATION/$MAX_ITERATIONS."
 else
@@ -1936,36 +2400,75 @@ else
     # Get test instructions for this project (NEW - v2.2)
     TEST_INSTRUCTIONS=$(format_test_instructions)
 
-    # Build stop criteria message - MUST be clear for each agent
+    # Build agent header based on type (NEW - v2.4)
+    AGENT_HEADER=""
+    if [ "$AGENT_TYPE" = "orchestrator" ]; then
+        AGENT_HEADER="
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  $AGENT_DISPLAY                                  ┃
+┃  AUTO SESSION - Iteration $NEXT_ITERATION/$MAX_ITERATIONS                          ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛"
+    else
+        AGENT_HEADER="
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  $AGENT_DISPLAY                                  ┃
+┃  Working under: 🤖 Main Orchestrator                       ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛"
+    fi
+
+    # Build stop criteria message - MUST be clear for each agent (v2.4)
     STOP_CRITERIA=""
-    if [ "$TDD_MODE" = "true" ]; then
-        STOP_CRITERIA="
+    if [ "$AGENT_TYPE" = "orchestrator" ]; then
+        # Main orchestrator stop criteria
+        if [ "$TDD_MODE" = "true" ]; then
+            STOP_CRITERIA="
 ╔══════════════════════════════════════════════════════════════╗
-║  🎯 AGENT STOP CONDITION (TDD STRICT MODE)                   ║
+║  🎯 SESSION STOP CONDITION (TDD STRICT MODE)                 ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  ✅ ALL tasks in tasks.md marked [x] completed               ║
 ║  ✅ ALL tests pass (0 failures required)                     ║
 ║  ✅ Test execution detected in output                        ║
 ╠══════════════════════════════════════════════════════════════╣
-║  Source: $(printf '%-45s' "$(get_tdd_source)")║
+║  TDD Source: $(printf '%-42s' "$(get_tdd_source)")║
 ╚══════════════════════════════════════════════════════════════╝"
-    else
-        STOP_CRITERIA="
+        else
+            STOP_CRITERIA="
 ╔══════════════════════════════════════════════════════════════╗
-║  🎯 AGENT STOP CONDITION                                     ║
+║  🎯 SESSION STOP CONDITION                                   ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  ✅ ALL tasks in tasks.md marked [x] completed               ║
 ║  ✅ Tests executed and passing                               ║
 ╚══════════════════════════════════════════════════════════════╝"
+        fi
+    else
+        # Subagent stop criteria - simpler, just complete the task
+        STOP_CRITERIA="
+╔══════════════════════════════════════════════════════════════╗
+║  🎯 SUBAGENT STOP CONDITION                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║  ✅ Complete the assigned task                               ║
+║  ↩️  Then return control to Main Orchestrator                ║
+╚══════════════════════════════════════════════════════════════╝"
+    fi
+
+    # Build subagent info if any were spawned (NEW - v2.4)
+    SUBAGENT_INFO=""
+    if [ "$SUBAGENT_COUNT" -gt 0 ] && [ "$AGENT_TYPE" = "orchestrator" ]; then
+        SUBAGENT_TYPES=$(echo "$SUBAGENT_ACTIVITY" | jq -r '.types | join(", ")' 2>/dev/null || echo "various")
+        SUBAGENT_INFO="
+📦 SUBAGENT ACTIVITY (this session):
+  ├─ Spawned: $SUBAGENT_COUNT subagent(s)
+  └─ Types: $SUBAGENT_TYPES"
     fi
 
-    # Build full context message
-    CONTEXT="🤖 AUTO MODE ACTIVE - Iteration $NEXT_ITERATION/$MAX_ITERATIONS
+    # Build full context message (v2.4)
+    CONTEXT="$AGENT_HEADER
 $STOP_CRITERIA
 
 📊 CURRENT PROGRESS:
   $PROGRESS
   $TEST_STATUS
+$SUBAGENT_INFO
 
 $TEST_INSTRUCTIONS
 
@@ -1981,8 +2484,9 @@ $TEST_INSTRUCTIONS
 ⚠️ This agent will NOT stop until the STOP CONDITION above is met!"
 fi
 
-# Log iteration
-echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"iteration\",\"iteration\":$NEXT_ITERATION,\"increment\":\"$CURRENT_INCREMENT\",\"testsRun\":$TESTS_RUN,\"testsPassed\":${TESTS_PASSED:-0},\"testsFailed\":${TESTS_FAILED:-0}}" >> "$LOGS_DIR/auto-iterations.log"
+# Log iteration with agent info (v2.4)
+AGENT_SHORT=$(get_agent_type_short "$AGENT_TYPE")
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"iteration\",\"iteration\":$NEXT_ITERATION,\"increment\":\"$CURRENT_INCREMENT\",\"agentType\":\"$AGENT_SHORT\",\"subagentsSpawned\":$SUBAGENT_COUNT,\"testsRun\":$TESTS_RUN,\"testsPassed\":${TESTS_PASSED:-0},\"testsFailed\":${TESTS_FAILED:-0}}" >> "$LOGS_DIR/auto-iterations.log"
 
 # Block exit and re-feed prompt
 block "Work incomplete, continuing..." "$CONTEXT"

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

@@ -98,7 +98,7 @@ Technology stack        → .specweave/docs/internal/architecture/tech-stack.md
 Business rules          → .specweave/docs/internal/strategy/business-rules.md
 Team workflows          → .specweave/docs/internal/processes/team-workflows.md
 Deployment process      → .specweave/docs/internal/processes/deployment.md
-Domain knowledge        → .specweave/increments/{####-name}/domain/{domain}.md
+Domain knowledge        → .specweave/increments/{####-name}/docs/domain/{domain}.md
 
 # Public Documentation (user-facing, can be published)
 Project conventions     → .specweave/docs/public/guides/project-conventions.md
@@ -438,7 +438,7 @@ function useCustomAuth() {
 **Domain**: Healthcare, Patient Management, Provider Scheduling
 
 ### Quick Links
-- [Domain Model](.specweave/increments/####-name/domain/appointments/domain-model.md)
+- [Domain Model](.specweave/increments/####-name/docs/domain/appointments/domain-model.md)
 - [Existing System Architecture](.specweave/docs/internal/architecture/existing-system.md)
 - [Tech Stack](.specweave/docs/internal/architecture/tech-stack.md)
 - [Business Rules](.specweave/docs/internal/strategy/appointments/business-rules.md)
@@ -508,7 +508,7 @@ if (exists("specifications/modules/appointments/domain-model.md")) {
 I found the following project-specific content in your backup CLAUDE.md:
 
 📦 Domain Model (Healthcare Appointments)
-   → .specweave/increments/####-name/domain/appointments/domain-model.md
+   → .specweave/increments/####-name/docs/domain/appointments/domain-model.md
 
 🏗️ Microservices Architecture
    → .specweave/docs/internal/architecture/existing-system.md
@@ -665,7 +665,7 @@ The following content remains in the backup and will be extracted when you work
 
 ## Files Created
 
-1. ✅ `.specweave/increments/####-name/domain/appointments/domain-model.md` (450 lines)
+1. ✅ `.specweave/increments/####-name/docs/domain/appointments/domain-model.md` (450 lines)
 2. ✅ `.specweave/docs/internal/architecture/existing-system.md` (320 lines)
 3. ✅ `.specweave/docs/internal/architecture/tech-stack.md` (180 lines)
 4. ✅ `.specweave/docs/internal/strategy/appointments/business-rules.md` (280 lines)
@@ -688,7 +688,7 @@ The following content remains in the backup and will be extracted when you work
 
 | Content Type | Lines | Destination |
 |--------------|-------|-------------|
-| Domain Model | 450 | .specweave/increments/####-name/domain/ |
+| Domain Model | 450 | .specweave/increments/####-name/docs/domain/ |
 | Architecture | 320 | .specweave/docs/internal/architecture/ |
 | Tech Stack | 180 | .specweave/docs/internal/architecture/ |
 | Business Rules | 280 | .specweave/docs/internal/strategy/ |
@@ -782,7 +782,7 @@ Proceed with merge? (y/n)
 ✅ Merge complete!
 
 Created:
-1. .specweave/increments/####-name/domain/appointments/domain-model.md
+1. .specweave/increments/####-name/docs/domain/appointments/domain-model.md
 2. .specweave/docs/internal/architecture/existing-system.md
 3. .specweave/docs/internal/architecture/tech-stack.md
 4. .specweave/docs/internal/strategy/appointments/business-rules.md

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

@@ -762,6 +762,24 @@ node plugins/specweave/skills/increment-planner/scripts/feature-utils.js check-i
 mkdir -p .specweave/increments/0021-feature-name
 ```
 
+**⚠️ CRITICAL: Increment Folder Structure Rules**
+
+**ONLY these files allowed at increment ROOT:**
+- `metadata.json` - Increment state (auto-managed)
+- `spec.md` - Specification
+- `plan.md` - Implementation plan
+- `tasks.md` - Task list
+
+**ALL other files MUST go in subfolders:**
+```
+.specweave/increments/####-name/
+├── reports/     # Validation reports, QA, completion summaries
+├── logs/        # Debug logs, session traces
+├── scripts/     # Helper scripts
+├── docs/        # Additional documentation, domain knowledge
+└── backups/     # Backup files
+```
+
 ### STEP 4: Create metadata.json FIRST (MANDATORY - CRITICAL ORDER!)
 
 **🚨 CRITICAL: metadata.json MUST be created BEFORE spec.md!**

package/plugins/specweave/skills/umbrella-repo-detector/SKILL.md

@@ -271,12 +271,25 @@ Use `/sw:save` to commit and push changes across all repos at once:
 ```
 
 **Features:**
+- **Auto-discovers nested repos** - Scans `repositories/`, `packages/`, `services/`, `apps/`, `libs/` for `.git` directories (up to 4 levels deep)
 - Auto-detects repos with changes
 - Sets up remotes if missing (prompts for URL or uses umbrella config)
 - Commits with same message to all repos
 - Pushes to origin
 - Skips repos with no changes
 
+**Auto-Discovery (No Config Required):**
+Even without umbrella config, `/sw:save` automatically finds all nested repos:
+```
+my-project/
+├── repositories/
+│   ├── frontend/.git    # ← Auto-discovered
+│   ├── backend/.git     # ← Auto-discovered
+│   └── shared/.git      # ← Auto-discovered
+└── .git                 # ← Parent repo included
+```
+All 4 repos will be committed and pushed with a single `/sw:save` command!
+
 ## Important Notes
 
 1. **Each repo is independent** - Own `.specweave/`, own increments, own external tool sync