specweave 1.0.78 → 1.0.80

package/plugins/specweave/commands/status.md

@@ -2,494 +2,9 @@
 name: sw:status
 description: Show increment status overview with rich details (active, backlog, paused, completed, abandoned)
 usage: /sw:status [--active|--backlog|--paused|--completed|--abandoned|--stale]
+allowed-tools: Bash(bash:*)
 ---
 
-# Increment Status Command
+# Increment Status
 
-**Usage**: `/sw:status [filter]`
-
----
-
-## Purpose
-
-Display comprehensive increment status overview:
-- **Active** increments (currently working)
-- **Backlog** increments (planned but not started)
-- **Paused** increments (blocked/deprioritized)
-- **Completed** increments (done)
-- **Abandoned** increments (obsolete)
-- **Warnings** for stale increments (paused >7 days, active >30 days)
-- **Suggestions** for next actions
-
----
-
-## Output Format
-
-### Default (All Increments)
-
-```bash
-/sw:status
-
-📊 Increment Status Overview
-
-🔥 Active (2):
-  🚨 0005-payment-hotfix [hotfix]
-     Progress: 90% (18/20 tasks)
-     Age: 6 hours
-     Last: Fixed Stripe webhook signature
-
-  🔧 0006-i18n [feature]
-     Progress: 50% (10/20 tasks)
-     Age: 2 days
-     Last: Created translation pipeline
-
-🗂️  Backlog (2):
-  📦 0032-feature-a [feature]
-     In backlog: 5 days
-     Reason: Low priority
-
-  📦 0033-feature-b [feature]
-     In backlog: 3 days
-     Reason: Waiting for decisions
-
-⏸️  Paused (1):
-  🔄 0007-stripe-integration [feature]
-     Progress: 30% (6/20 tasks)
-     Paused: 3 days ago
-     Reason: Waiting for Stripe API keys
-     ⚠️  Review or abandon?
-
-✅ Completed (4):
-  0001-core-framework
-  0002-core-enhancements
-  0003-intelligent-model-selection
-  0004-plugin-architecture
-
-📊 Summary:
-  - Active: 2 increments (1 hotfix, 1 feature)
-  - Backlog: 2 increments (planned for future)
-  - Paused: 1 increment
-  - Completed: 4 increments
-  - Context switching: 20-40% cost (2 active)
-
-📋 Type Limits (v0.7.0+):
-  ✅ hotfix: 1/unlimited active
-  ✅ feature: 1/2 active
-  ✅ refactor: 0/1 active
-  ✅ bug: 0/unlimited active
-  ✅ change-request: 0/2 active
-  ✅ experiment: 0/unlimited active
-
-💡 Suggestions:
-  - Complete 0005 first (90% done, almost there!)
-  - Resume or abandon 0007 (stale)
-
-Commands:
-  /sw:do              # Continue current work
-  /sw:resume 0007     # Resume paused increment
-  /sw:abandon 0007    # Abandon if obsolete
-```
-
-### Filtered Views
-
-```bash
-# Active only
-/sw:status --active
-
-🔥 Active Increments (2):
-  🚨 0005-payment-hotfix [hotfix] (90% done, 6 hours)
-  🔧 0006-i18n [feature] (50% done, 2 days)
-
-# Paused only
-/sw:status --paused
-
-⏸️  Paused Increments (1):
-  🔄 0007-stripe [feature] (paused 3 days)
-     Reason: Waiting for API keys
-
-# Stale only (paused >7 days OR active >30 days)
-/sw:status --stale
-
-⚠️  Stale Increments (2):
-  🔄 0008-experiment [experiment] (paused 10 days)
-     🚨 AUTO-ABANDON WARNING (14 days inactive)
-
-  🔧 0009-big-refactor [refactor] (active 35 days)
-     ⚠️  Long-running - consider breaking into smaller increments
-```
-
----
-
-## Implementation
-
-Uses MetadataManager and Limits to query and display:
-
-```typescript
-import { MetadataManager, IncrementStatus } from '../src/core/increment/metadata-manager';
-import { checkAllLimits, getLimitsSummary } from '../src/core/increment/limits';
-
-// Get all increments
-const allIncrements = MetadataManager.getAll();
-
-// Group by status
-const active = allIncrements.filter(m => m.status === IncrementStatus.ACTIVE);
-const backlog = allIncrements.filter(m => m.status === IncrementStatus.BACKLOG);
-const paused = allIncrements.filter(m => m.status === IncrementStatus.PAUSED);
-const completed = allIncrements.filter(m => m.status === IncrementStatus.COMPLETED);
-const abandoned = allIncrements.filter(m => m.status === IncrementStatus.ABANDONED);
-
-// Get extended metadata (with progress%)
-const extended = active.map(m => MetadataManager.getExtended(m.id));
-
-// Display rich output
-console.log('📊 Increment Status Overview\n');
-
-// Active
-if (active.length > 0) {
-  console.log(`🔥 Active (${active.length}):`);
-  extended.forEach(inc => {
-    const icon = inc.type === 'hotfix' ? '🚨' : '🔧';
-    console.log(`  ${icon} ${inc.id} [${inc.type}]`);
-    console.log(`     Progress: ${inc.progress}% (${inc.completedTasks}/${inc.totalTasks} tasks)`);
-    console.log(`     Age: ${formatAge(inc.ageInDays)}`);
-  });
-}
-
-// ... similar for paused, completed, abandoned
-
-// Summary with type limits (v0.7.0+)
-console.log('\n📊 Summary:');
-console.log(`  - Active: ${active.length} increments`);
-console.log(`  - Backlog: ${backlog.length} increments`);
-console.log(`  - Paused: ${paused.length} increments`);
-console.log(`  - Completed: ${completed.length} increments`);
-
-// Type limits breakdown
-console.log('\n📋 Type Limits (v0.7.0+):');
-const limitsCheck = checkAllLimits();
-for (const [type, check] of Object.entries(limitsCheck)) {
-  const icon = check.exceeded ? '⚠️ ' : '✅';
-  const limitStr = check.limit === null ? 'unlimited' : check.limit.toString();
-  console.log(`  ${icon} ${type}: ${check.current}/${limitStr} active`);
-}
-
-// Context switching warning if multiple active
-if (active.length > 1) {
-  const cost = active.length === 2 ? '20-30%' : '40%';
-  console.log(`\n⚠️  Context switching: ${cost} productivity cost`);
-}
-```
-
----
-
-## Progress Calculation
-
-Progress percentage calculated from tasks.md:
-
-```typescript
-// Count completed tasks: [x] or [X]
-const completedMatches = tasksContent.match(/\[x\]/gi);
-const completedTasks = completedMatches ? completedMatches.length : 0;
-
-// Count total tasks: [ ] or [x]
-const totalMatches = tasksContent.match(/\[ \]|\[x\]/gi);
-const totalTasks = totalMatches ? totalMatches.length : 0;
-
-// Calculate percentage
-const progress = Math.round((completedTasks / totalTasks) * 100);
-```
-
----
-
-## Warnings and Suggestions
-
-### Stale Paused Increments
-
-Paused >7 days → warning:
-
-```
-⏸️  Paused (1):
-  🔄 0007-stripe [feature]
-     Paused: 10 days ago
-     ⚠️  STALE! Review or abandon?
-
-💡 Actions:
-   /sw:resume 0007  # If unblocked
-   /sw:abandon 0007 # If no longer needed
-```
-
-### Long-Running Active Increments
-
-Active >30 days → warning:
-
-```
-🔥 Active (1):
-  🔧 0009-big-refactor [refactor]
-     Progress: 45% (23/50 tasks)
-     Age: 35 days
-     ⚠️  Long-running! Consider breaking into smaller increments
-
-💡 Suggestion: Large increments increase risk and reduce velocity
-```
-
-### Context Switching Cost
-
-Multiple active features → warning:
-
-```
-📊 Summary:
-  - Active: 3 features (0010, 0011, 0012)
-  - Context switching: 40-60% productivity cost
-
-⚠️  High context switching detected!
-   Research shows: 3+ concurrent tasks = 40% productivity loss
-   Suggestion: Complete or pause one before continuing
-```
-
-### Auto-Abandon Warning (Experiments)
-
-Experiments inactive >14 days → warning:
-
-```
-🧪 Experiments (1):
-  🔬 0010-graphql-experiment [experiment]
-     Last activity: 15 days ago
-     🚨 AUTO-ABANDON WARNING
-
-💡 Experiments auto-abandon after 14 days of inactivity
-   To prevent: Update via /sw:do or /touch 0010
-```
-
----
-
-## Cross-Project View (v0.33.0+)
-
-When an increment has user stories targeting multiple projects, show grouped view:
-
-```bash
-/sw:status 0125
-
-📊 Increment Status: 0125-cross-project-targeting
-
-🔀 Cross-Project Increment (spans 3 projects):
-
-┌───────────────┬────────────┬──────────┬────────────────┬─────────────────────┐
-│ Project       │ Provider   │ USs      │ Status         │ External Issues     │
-├───────────────┼────────────┼──────────┼────────────────┼─────────────────────┤
-│ frontend-app  │ github     │ US-001,  │ ✅ Synced      │ #45, #46            │
-│               │            │ US-003   │                │ github.com/org/fe   │
-├───────────────┼────────────┼──────────┼────────────────┼─────────────────────┤
-│ backend-api   │ jira       │ US-002   │ ✅ Synced      │ SEC-123             │
-│               │            │          │                │ jira.com/browse     │
-├───────────────┼────────────┼──────────┼────────────────┼─────────────────────┤
-│ shared-lib    │ ⚠️ None    │ US-004   │ Not mapped     │ —                   │
-│               │            │          │                │                     │
-└───────────────┴────────────┴──────────┴────────────────┴─────────────────────┘
-
-📋 Progress by Project:
-  frontend-app: 75% (3/4 tasks)
-  backend-api:  50% (2/4 tasks)
-  shared-lib:   100% (2/2 tasks)
-
-💡 Unmapped project 'shared-lib':
-   Add to .specweave/config.json projectMappings or create issues manually
-```
-
-### Cross-Project Implementation
-
-```typescript
-import { CrossProjectSync } from '../src/core/living-docs/cross-project-sync';
-import { ExternalSyncOrchestrator } from '../src/core/living-docs/external-sync-orchestrator';
-
-// Detect cross-project
-const crossProjectSync = new CrossProjectSync(projectRoot);
-const userStories = parseUserStories(specContent);
-const isCrossProject = crossProjectSync.isCrossProject(userStories, defaultProject);
-
-if (isCrossProject) {
-  // Group by project
-  const groups = crossProjectSync.groupByProject(userStories, defaultProject);
-
-  // Load project mappings
-  const orchestrator = new ExternalSyncOrchestrator(projectRoot);
-  await orchestrator.loadProjectMappings();
-
-  // Display per-project status
-  for (const [projectId, stories] of groups) {
-    const mapping = orchestrator.getProjectMapping(projectId);
-    const provider = mapping?.github ? 'github' : mapping?.jira ? 'jira' : mapping?.ado ? 'ado' : null;
-
-    console.log(`│ ${projectId.padEnd(13)} │ ${(provider || '⚠️ None').padEnd(10)} │ ...`);
-  }
-}
-```
-
----
-
-## Filters
-
-### --active
-
-Show only active increments
-
-```bash
-/sw:status --active
-
-🔥 Active (2):
-  🚨 0005-hotfix [hotfix] (90% done)
-  🔧 0006-i18n [feature] (50% done)
-```
-
-### --backlog
-
-Show only backlog increments
-
-```bash
-/sw:status --backlog
-
-🗂️  Backlog (3):
-  📦 0032-feature-a [feature] (in backlog 5 days)
-     Reason: Low priority
-
-  📦 0033-feature-b [feature] (in backlog 3 days)
-     Reason: Waiting for decisions
-
-  📦 0034-feature-c [feature] (in backlog 1 day)
-     Reason: Multiple planned ideas
-
-💡 Start work: /sw:resume <id>
-```
-
-### --paused
-
-Show only paused increments
-
-```bash
-/sw:status --paused
-
-⏸️  Paused (2):
-  🔄 0007-stripe [feature] (paused 3 days)
-     Reason: Waiting for API keys
-
-  🔄 0008-refactor [refactor] (paused 10 days)
-     Reason: Deprioritized
-     ⚠️  STALE
-```
-
-### --completed
-
-Show only completed increments
-
-```bash
-/sw:status --completed
-
-✅ Completed (5):
-  0001-core-framework (completed 30 days ago)
-  0002-core-enhancements (completed 25 days ago)
-  0003-model-selection (completed 20 days ago)
-  0004-plugin-architecture (completed 15 days ago)
-  0005-cross-platform (completed 10 days ago)
-```
-
-### --abandoned
-
-Show only abandoned increments
-
-```bash
-/sw:status --abandoned
-
-❌ Abandoned (3):
-  0008-old-approach (Requirements changed)
-  0009-failed-experiment (Experiment failed)
-  0010-superseded (Replaced by 0011)
-
-📊 Stats:
-  - Abandonment rate: 30% (3/10 total)
-  - Common reasons: Requirements changed (2), Experiment failed (1)
-
-💡 Periodically review _abandoned/ for learnings
-```
-
-### --stale
-
-Show only stale increments (paused >7 days OR active >30 days)
-
-```bash
-/sw:status --stale
-
-⚠️  Stale Increments (3):
-  🔄 0007-stripe [feature] (paused 10 days)
-  🔄 0008-experiment [experiment] (paused 15 days)
-     🚨 AUTO-ABANDON WARNING
-  🔧 0009-refactor [refactor] (active 35 days)
-     ⚠️  Long-running
-
-💡 Review stale increments weekly
-   Paused >7 days: Resume or abandon
-   Active >30 days: Consider breaking into smaller increments
-```
-
----
-
-## Related Commands
-
-- `/sw:do` - Continue work on active increment
-- `/sw:progress` - Detailed progress for current increment
-- `/sw:backlog <id>` - Move increment to backlog
-- `/sw:pause <id>` - Pause active increment
-- `/sw:resume <id>` - Resume paused or backlog increment
-- `/sw:abandon <id>` - Abandon increment (move to _abandoned/)
-
----
-
-## Best Practices
-
-✅ **Check status regularly** - Daily or before starting work
-
-✅ **Address warnings promptly** - Don't let stale increments pile up
-
-✅ **Complete before starting new** - Minimize context switching
-
-✅ **Review abandoned for learnings** - Understand patterns
-
-❌ **Don't ignore stale warnings** - They indicate blocked or forgotten work
-
-❌ **Don't accumulate paused increments** - Resume or abandon
-
----
-
-## Statistics and Analytics
-
-Future enhancement (v0.8.0+):
-
-```bash
-/sw:status --analytics
-
-📊 Increment Analytics (Last 90 Days):
-
-Velocity:
-  - Completed: 8 increments
-  - Avg cycle time: 4.2 days
-  - Completion rate: 80%
-
-Quality:
-  - Avg coverage: 85%
-  - Avg tasks/increment: 25
-
-Patterns:
-  - Most common type: feature (70%)
-  - Context switching: 1.5 active avg
-  - Stale rate: 15% (paused >7 days)
-
-Recommendations:
-  - ✅ Good velocity (8 increments/90 days)
-  - ⚠️  High abandonment (20%) - review scoping
-  - ✅ Low context switching (1.5 avg)
-```
-
----
-
-**Command**: `/sw:status`
-**Plugin**: specweave (core)
-**Version**: v0.7.0+
-**Part of**: Increment 0007 - Smart Status Management
+!`bash "${CLAUDE_PLUGIN_ROOT}/scripts/read-status.sh" $ARGUMENTS`

package/plugins/specweave/hooks/README.md

@@ -8,10 +8,11 @@
 ## Purpose
 
 Core hooks automate SpecWeave's fundamental workflows:
-- **Sound notifications** when tasks complete or input is needed
+- **Sound notifications** when tasks complete (v1.0.77+: plays when task marked `[x]` in tasks.md)
 - **Living docs sync** after task completion
 - **Translation** of non-English documentation
 - **Self-reflection** for AI-driven quality improvements
+- **Auto mode loops** for autonomous execution
 
 **Note**: External tool sync (GitHub, JIRA, Azure DevOps) has been moved to respective plugin hooks as of v0.13.0. See "Architecture Changes" section below.
 
@@ -147,6 +148,29 @@ Core hooks automate SpecWeave's fundamental workflows:
 
 ---
 
+### 🔊 Task Completion Sound (v1.0.77+)
+
+**Triggers**: Automatically when any task is marked `[x]` in tasks.md
+
+**How It Works**:
+- Monitors task completion count in `.specweave/state/.last-task-completion`
+- Plays pleasant sound (Glass.aiff) when count increases
+- Runs in background (never blocks or delays hook execution)
+- **Smart auto mode detection**: Skips during `/sw:auto` (Stop hook plays ONE sound at END)
+
+**Behavior by Mode**:
+- **Normal mode**: Sound plays after EACH task completion
+- **Auto mode** (`/sw:auto`): NO sounds during execution, ONE completion sound when main orchestrator finishes
+
+**Platforms**:
+- macOS: `Glass.aiff` (built-in system sound)
+- Linux (PulseAudio): `/usr/share/sounds/freedesktop/stereo/complete.oga`
+- Linux (ALSA): `/usr/share/sounds/alsa/Front_Center.wav`
+
+**Implementation**: Integrated into `PostToolUse` hook dispatcher (`v2/dispatchers/post-tool-use.sh`)
+
+---
+
 ## 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/v2/dispatchers/post-tool-use.sh

@@ -42,6 +42,8 @@ while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
 done
 [[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
 
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+
 # ============================================================================
 # LOGGING INFRASTRUCTURE
 # ============================================================================
@@ -154,6 +156,57 @@ safe_run_sync() {
   return 0  # Always succeed
 }
 
+# ============================================================================
+# TASK COMPLETION SOUND (plays when task marked [x])
+# ============================================================================
+
+play_task_completion_sound() {
+  local tasks_file="$1"
+  local state_file="$STATE_DIR/.last-task-completion"
+  local session_file="$STATE_DIR/auto-session.json"
+
+  # CRITICAL: Skip sound if auto mode is active
+  # Auto mode has its own completion sound via Stop hook (plays once at END)
+  if [[ -f "$session_file" ]]; then
+    local auto_status=$(jq -r '.status // "unknown"' "$session_file" 2>/dev/null || echo "unknown")
+    if [[ "$auto_status" == "active" ]] || [[ "$auto_status" == "running" ]]; then
+      log_debug "Auto mode active - skipping task completion sound (Stop hook will handle it)"
+      return 0
+    fi
+  fi
+
+  # Extract current completion count
+  local current_count=$(grep -c '\*\*Status\*\*:.*\[x\]' "$tasks_file" 2>/dev/null || echo "0")
+
+  # Read previous count
+  local previous_count="0"
+  if [[ -f "$state_file" ]]; then
+    previous_count=$(cat "$state_file" 2>/dev/null || echo "0")
+  fi
+
+  # If count increased, a task was just completed
+  if [[ "$current_count" -gt "$previous_count" ]]; then
+    # Save new count
+    echo "$current_count" > "$state_file" 2>/dev/null
+
+    # Play completion sound (background, never blocks)
+    (
+      if [[ "$OSTYPE" == "darwin"* ]]; then
+        # macOS - use Glass.aiff for pleasant completion sound
+        afplay /System/Library/Sounds/Glass.aiff 2>/dev/null &
+      elif command -v paplay >/dev/null 2>&1; then
+        # Linux with PulseAudio
+        paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null &
+      elif command -v aplay >/dev/null 2>&1; then
+        # Linux with ALSA
+        aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null &
+      fi
+    ) &
+
+    log_debug "Task completion sound played (count: $previous_count → $current_count)"
+  fi
+}
+
 # ============================================================================
 # INPUT PARSING (with safe fallbacks)
 # ============================================================================
@@ -217,6 +270,9 @@ case "$FILE_PATH" in
         log_debug "Running task-ac-sync guard"
         safe_run_sync "$SYNC_SCRIPT" "task-ac-sync" "$INPUT"
       fi
+
+      # Play completion sound if task was marked complete (v1.0.77+)
+      play_task_completion_sound "$FILE_PATH"
     fi
 
     # Tasks or spec changed -> check for US completion (background)