specweave 0.33.3 → 0.33.5

package/dist/src/utils/platform-utils.js

@@ -297,13 +297,19 @@ export class PlatformUtils {
      *
      * Fails gracefully if notification system is unavailable
      *
-     * @param title Notification title
-     * @param body Notification body text
+     * IMPORTANT: Notifications MUST be explicit! Always:
+     * 1. Start title with "SpecWeave:" to identify source
+     * 2. Use explicit message describing what happened
+     * 3. Include "No action needed" for informational notifications
+     *
+     * @param title Notification title (should start with "SpecWeave:")
+     * @param body Notification body text (should be explicit about what happened)
+     * @param sound Optional sound name for macOS (default: "Pop" for neutral notifications)
      */
-    async sendNotification(title, body) {
+    async sendNotification(title, body, sound) {
         try {
             if (this.platform === 'darwin') {
-                await this.sendNotificationMacOS(title, body);
+                await this.sendNotificationMacOS(title, body, sound);
             }
             else if (this.platform === 'linux') {
                 await this.sendNotificationLinux(title, body);
@@ -319,11 +325,16 @@ export class PlatformUtils {
     }
     /**
      * macOS notification using osascript
+     *
+     * @param title Notification title (should start with "SpecWeave:")
+     * @param body Notification body (should be explicit about what happened)
+     * @param sound Optional sound name (default: "Pop" for neutral notifications)
      */
-    async sendNotificationMacOS(title, body) {
+    async sendNotificationMacOS(title, body, sound = 'Pop') {
         const escapedTitle = title.replace(/"/g, '\\"');
         const escapedBody = body.replace(/"/g, '\\"');
-        const cmd = `osascript -e 'display notification "${escapedBody}" with title "${escapedTitle}"'`;
+        const soundParam = sound ? ` sound name "${sound}"` : '';
+        const cmd = `osascript -e 'display notification "${escapedBody}" with title "${escapedTitle}"${soundParam}'`;
         execSync(cmd, { stdio: 'ignore' });
     }
     /**

package/dist/src/utils/platform-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform-utils.js","sourceRoot":"","sources":["../../../src/utils/platform-utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform-utils.js","sourceRoot":"","sources":["../../../src/utils/platform-utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.33.3",
+  "version": "0.33.5",
   "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/commands/specweave-increment.md

@@ -364,6 +364,52 @@ Proceeding with hotfix 0006...
 - Hotfixes and bugs bypass context switching warnings (emergency work)
 - Use sparingly - discipline exists for a reason!
 
+### Step 0D: Get Project Context (MANDATORY - RUN FIRST!)
+
+**⛔ THIS STEP MUST BE COMPLETED BEFORE ANY SPEC GENERATION!**
+
+**🚨 YOU MUST USE THE BASH TOOL TO RUN THIS COMMAND:**
+
+```bash
+specweave context projects
+```
+
+**CAPTURE THE OUTPUT AND STORE IT:**
+
+```json
+// Example 1-level output:
+{
+  "level": 1,
+  "projects": [{"id": "frontend-app"}, {"id": "backend-api"}, {"id": "shared"}]
+}
+
+// Example 2-level output:
+{
+  "level": 2,
+  "projects": [{"id": "acme-corp"}],
+  "boardsByProject": {
+    "acme-corp": [{"id": "digital-ops"}, {"id": "mobile-team"}]
+  }
+}
+```
+
+**STORE THESE VALUES FOR USE IN STEP 5:**
+```
+STRUCTURE_LEVEL = 1 or 2
+AVAILABLE_PROJECTS = ["frontend-app", "backend-api", "shared"]
+AVAILABLE_BOARDS = {...}  // for 2-level only
+```
+
+**WHY THIS IS MANDATORY:**
+- Without this data, spec.md will have `{{PROJECT_ID}}` placeholders
+- Placeholders WILL BE BLOCKED by `spec-project-validator.sh` hook
+- Living docs sync and external tool sync WILL FAIL
+- User will get frustrated with blocked edits
+
+**YOU MUST ACTUALLY RUN THE COMMAND** - reading documentation about it is NOT enough!
+
+---
+
 ### Step 1: Find next increment number
 
 - Scan `.specweave/increments/` directory (active increments)

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

@@ -1,7 +1,7 @@
 ---
 name: specweave:jobs
 description: Show current work status (active increments, progress) and background jobs (imports, cloning). Even with no jobs, shows increment summary and helpful context.
-usage: /specweave:jobs [--all] [--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>]
+usage: /specweave:jobs [--all] [--id <job-id>] [--resume <job-id>] [--kill <job-id>] [--follow <job-id>] [--logs <job-id>] [--diagnostics]
 ---
 
 # Background Jobs Monitor
@@ -17,6 +17,7 @@ Monitor and manage long-running background operations:
 - **Issue import** (10K+ items from GitHub/JIRA/ADO)
 - **External sync** operations
 - **Brownfield analysis** (codebase documentation gap detection)
+- **Session health monitoring** (watchdog diagnostics)
 
 **ASYNC ARCHITECTURE (2025-12-01)**:
 - Jobs run as **detached processes** that survive terminal close
@@ -29,13 +30,14 @@ Monitor and manage long-running background operations:
 
 | Option | Description |
 |--------|-------------|
-| (none) | Show active jobs |
+| (none) | Show active jobs + session health |
 | `--all` | Show all jobs (including completed) |
 | `--id <jobId>` | Show details for specific job |
 | `--follow <jobId>` | Follow job progress in real-time |
 | `--logs <jobId>` | Show worker log output |
 | `--resume <jobId>` | Resume paused job |
 | `--kill <jobId>` | Kill running background job |
+| `--diagnostics` | Show detailed watchdog diagnostics |
 
 ---
 
@@ -57,7 +59,9 @@ STATE_FILE=".specweave/state/background-jobs.json"
 ### Display Format
 
 ```
-📋 Background Jobs
+📋 Background Jobs & Session Health
+
+🩺 Session Health: ✅ healthy (last check: 30s ago)
 
 🔄 Running (2):
   [abc12345] import-issues (ADO)
@@ -87,6 +91,7 @@ STATE_FILE=".specweave/state/background-jobs.json"
    /specweave:jobs --logs abc12345   → View worker logs
    /specweave:jobs --resume def67890 → Resume paused job
    /specweave:jobs --kill abc12345   → Kill running job
+   /specweave:jobs --diagnostics     → Show watchdog diagnostics
    /specweave:jobs --all             → Show all jobs (including old)
 ```
 
@@ -221,14 +226,57 @@ const result = await launchImportJob({
 ## Implementation
 
 1. Read `.specweave/state/background-jobs.json`
-2. Parse job entries
-3. Display formatted status
-4. For --resume, update job status and continue operation
+2. Read `.specweave/state/.watchdog-diagnostics.json` for session health
+3. Parse job entries
+4. Display formatted status with health indicator
+5. For --resume, update job status and continue operation
+6. For --diagnostics, show detailed watchdog checks
 
-### State File Location
+### State File Locations
 
 ```
-.specweave/state/background-jobs.json
+.specweave/state/background-jobs.json          - Job status and progress
+.specweave/state/.watchdog-diagnostics.json    - Session health checks
+.specweave/state/jobs/<jobId>/config.json      - Job configuration
+.specweave/state/jobs/<jobId>/worker.pid       - Worker process ID
+.specweave/state/jobs/<jobId>/worker.log       - Worker output log
+.specweave/logs/watchdog.log                   - Watchdog history
+```
+
+### Reading Session Health
+
+```typescript
+import * as fs from 'fs';
+import * as path from 'path';
+
+function getSessionHealth(projectPath: string): SessionHealth | null {
+  const diagnosticsPath = path.join(projectPath, '.specweave/state/.watchdog-diagnostics.json');
+  if (!fs.existsSync(diagnosticsPath)) {
+    return null; // Watchdog not running
+  }
+
+  try {
+    const content = fs.readFileSync(diagnosticsPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+interface SessionHealth {
+  timestamp: string;
+  severity: 0 | 1 | 2;  // INFO | WARNING | CRITICAL
+  status: 'healthy' | 'warning' | 'critical';
+  checks: {
+    lock: { severity: number; message: string };
+    zombies: { count: number; message: string };
+    mcp: { drops: number; message: string };
+    orphanedJobs: { count: number; message: string };
+  };
+  consecutiveWarnings: number;
+  thresholdSeconds: number;
+  checkIntervalSeconds: number;
+}
 ```
 
 ### Job Types
@@ -299,9 +347,106 @@ If job failed:
 
 ---
 
+## Session Health & Watchdog Diagnostics (v2.0)
+
+The `/specweave:jobs` command now includes session health monitoring. The watchdog runs in the background and writes diagnostics that help explain any alerts you may have received.
+
+### Display Format (with health status)
+
+```
+📋 Background Jobs & Session Health
+
+🩺 Session Health: ✅ healthy
+   Last check: 30 seconds ago
+   Consecutive warnings: 0/3
+
+🔄 Running (1):
+  [abc12345] import-issues (ADO)
+     Progress: 2,500/10,000 (25%)
+     ...
+```
+
+### Diagnostics File
+
+The watchdog writes diagnostics to `.specweave/state/.watchdog-diagnostics.json`:
+
+```json
+{
+  "timestamp": "2025-12-10T10:30:00Z",
+  "severity": 0,
+  "status": "healthy",
+  "checks": {
+    "lock": { "severity": 0, "message": "ok" },
+    "zombies": { "count": 0, "message": "none" },
+    "mcp": { "drops": 2, "message": "minor instability" },
+    "orphanedJobs": { "count": 0, "message": "none" }
+  },
+  "consecutiveWarnings": 0,
+  "thresholdSeconds": 300,
+  "checkIntervalSeconds": 60
+}
+```
+
+### View Detailed Diagnostics
+
+```
+/specweave:jobs --diagnostics
+
+🩺 Watchdog Diagnostics
+
+Overall Status: ✅ healthy
+Last Check: 2025-12-10 10:30:00
+Severity Level: INFO (0)
+
+Checks:
+  📁 Lock File:      ✅ ok
+  💀 Zombie Procs:   ✅ none (0)
+  🔌 MCP Connection: ⚠️  2 drops detected (minor instability)
+  📦 Orphaned Jobs:  ✅ none (0)
+
+Alert Threshold: 3 consecutive warnings
+Current Warnings: 0/3
+
+Severity Levels:
+  INFO (0)     - Everything healthy, no action needed
+  WARNING (1)  - Minor issue detected, monitoring (NO notification)
+  CRITICAL (2) - Real stuck condition detected → NOTIFICATION SENT
+
+💡 The watchdog only sends notifications for CRITICAL issues
+   that persist across 3+ consecutive checks (prevents false positives).
+```
+
+### Why You Got a Notification
+
+If you received a notification but your job completed successfully, here's what happened:
+
+1. **Old behavior (v1)**: Watchdog triggered on stale lock files even if no process was stuck
+2. **New behavior (v2)**: Watchdog verifies actual process state before alerting
+
+Common false positive causes (now fixed):
+- Stale `.processor.lock` file from completed job
+- Missing heartbeat file (never written in normal operation)
+- MCP connection drops (warning only, not critical)
+
+**The v2 watchdog now requires**:
+1. **Actual stuck process** (zombie heredoc, hung worker)
+2. **3 consecutive checks** showing the same issue
+3. **CRITICAL severity** (not just warnings)
+
+### Watchdog Log
+
+View historical watchdog checks:
+
+```bash
+cat .specweave/logs/watchdog.log
+```
+
+---
+
 ## Notes
 
 - Jobs persist across Claude sessions
 - Paused jobs can be resumed later
 - Completed jobs cleaned up after 10 entries
 - Rate limiting auto-pauses and notifies
+- Watchdog diagnostics available via `--diagnostics` flag

package/plugins/specweave/commands/specweave-judge-llm.md

@@ -0,0 +1,296 @@
+---
+name: specweave:judge-llm
+description: Ultrathink LLM-as-Judge validation of completed work. Uses extended thinking by DEFAULT for thorough evaluation.
+---
+
+# /specweave:judge-llm - Ultrathink LLM-as-Judge Validation
+
+**ULTRATHINK BY DEFAULT** - Validate completed work using extended thinking and the LLM-as-Judge pattern.
+
+## CRITICAL: Extended Thinking is DEFAULT
+
+This command ALWAYS uses **ultrathink (extended thinking)** for thorough LLM-as-Judge evaluation:
+
+```
+DEFAULT BEHAVIOR = ULTRATHINK MODE
+- Extended thinking enabled
+- Deep chain-of-thought reasoning
+- Thorough multi-dimensional analysis
+- ~60-90 seconds for comprehensive evaluation
+```
+
+Use `--quick` only if you explicitly need faster (but less thorough) validation.
+
+## Purpose
+
+Use when you've completed work and want **maximum-quality AI validation**:
+- Works on **any files** (not just SpecWeave increments)
+- Uses **ultrathink extended thinking** for deepest analysis
+- Returns **clear verdict** with detailed reasoning
+
+## Usage
+
+```bash
+# DEFAULT: Ultrathink validation (recommended)
+/specweave:judge-llm src/file.ts
+/specweave:judge-llm "src/**/*.ts"
+
+# Validate git changes (ultrathink by default)
+/specweave:judge-llm --staged           # Staged changes
+/specweave:judge-llm --last-commit      # Last commit
+/specweave:judge-llm --diff main        # Diff vs branch
+
+# Quick mode (ONLY if you need speed over thoroughness)
+/specweave:judge-llm src/file.ts --quick
+
+# Additional options
+/specweave:judge-llm src/file.ts --strict   # Fail on any concern
+/specweave:judge-llm src/file.ts --fix      # Include fix suggestions
+/specweave:judge-llm src/file.ts --export   # Export report to markdown
+```
+
+## How It Works
+
+When you invoke `/specweave:judge-llm`, Claude will:
+
+### Step 1: Gather Input
+
+Determine what to validate:
+- If file paths provided → read those files
+- If `--staged` → get staged git changes
+- If `--last-commit` → get files from last commit
+- If `--diff <branch>` → get diff against branch
+- If no args → validate recent work in conversation context
+
+### Step 2: ULTRATHINK Analysis (Default)
+
+**MANDATORY**: Use extended thinking for deep LLM-as-Judge evaluation:
+
+```
+Claude MUST use ultrathink/extended thinking to:
+
+1. **DEEP READ**: Thoroughly understand all code, context, and intent
+2. **MULTI-DIMENSIONAL ANALYSIS**: Evaluate across ALL dimensions:
+   - Correctness: Does it work exactly as intended?
+   - Completeness: ALL edge cases handled? ALL requirements met?
+   - Security: ANY vulnerabilities? OWASP Top 10 checked?
+   - Performance: Algorithmic complexity? Memory usage? Bottlenecks?
+   - Maintainability: Clean? Clear? Follows conventions?
+   - Testability: Can it be tested? Are tests adequate?
+   - Error handling: All failure modes covered?
+3. **CRITICAL EVALUATION**: Weigh ALL findings by severity
+4. **REASONED VERDICT**: Form verdict based on thorough analysis
+```
+
+### Step 3: Return Verdict
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JUDGE-LLM VERDICT: APPROVED | CONCERNS | REJECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: ULTRATHINK (extended thinking)
+Confidence: 0.XX
+Files Analyzed: N
+
+REASONING:
+[Detailed chain-of-thought from extended thinking]
+
+ISSUES (if any):
+🔴 CRITICAL: [title]
+   [description]
+   📍 [file:line]
+   💡 [suggestion]
+
+🟡 HIGH: [title]
+   ...
+
+🟢 LOW: [title]
+   ...
+
+VERDICT: [summary sentence]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Verdict Meanings
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| **APPROVED** | Work is solid, no significant issues | Safe to proceed |
+| **CONCERNS** | Issues found worth addressing | Review and fix recommended |
+| **REJECTED** | Critical issues found | MUST fix before proceeding |
+
+## Validation Modes
+
+### Default Mode (ULTRATHINK) - RECOMMENDED
+- **Extended thinking ENABLED by default**
+- Most thorough validation (~60-90 seconds)
+- Deep multi-dimensional analysis
+- Best for any completed work
+- Cost: ~$0.10-0.25
+
+### Quick Mode (`--quick`)
+- Fast validation (~10-15 seconds)
+- Standard reasoning (no extended thinking)
+- Good for quick sanity checks during development
+- Cost: ~$0.02-0.05
+
+### Strict Mode (`--strict`)
+- Any concern results in REJECTED
+- Use for critical paths, security code, or CI gates
+- Combines with ultrathink by default
+
+## Examples
+
+### Example 1: Default ultrathink validation
+
+```
+User: /specweave:judge-llm src/core/auth/login.ts
+
+Claude: [Uses extended thinking for deep analysis]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JUDGE-LLM VERDICT: APPROVED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: ULTRATHINK (extended thinking)
+Confidence: 0.91
+Files Analyzed: 1
+
+REASONING:
+After thorough analysis with extended thinking:
+
+The login implementation demonstrates excellent security practices:
+- Password hashing uses bcrypt with cost factor 12 (appropriate)
+- Rate limiting implemented correctly (5 attempts, 15 min exponential backoff)
+- Input validation prevents SQL injection and XSS
+- Error messages are generic (don't leak user existence)
+- Session tokens use cryptographically secure random generation
+- CSRF protection properly implemented
+
+Edge cases handled:
+- Empty input validation ✓
+- Unicode normalization for usernames ✓
+- Timing attack mitigation via constant-time comparison ✓
+
+No security, performance, or maintainability issues found.
+
+VERDICT: Production-ready implementation with excellent security posture.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Example 2: Validate staged changes
+
+```
+User: /specweave:judge-llm --staged
+
+Claude: [Uses extended thinking]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JUDGE-LLM VERDICT: CONCERNS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: ULTRATHINK (extended thinking)
+Confidence: 0.84
+Files Analyzed: 3
+
+REASONING:
+Extended thinking analysis of staged changes reveals:
+
+Positive aspects:
+- New API endpoint follows existing patterns
+- TypeScript types are correct
+- Error handling present
+
+However, thorough analysis found issues:
+
+🟡 HIGH: Missing Input Validation
+   User input passed to database without sanitization
+   📍 src/api/users.ts:45
+   💡 Add Zod schema validation:
+   ```typescript
+   const schema = z.object({ userId: z.string().uuid() });
+   const { userId } = schema.parse(req.body);
+   ```
+
+🟡 HIGH: Information Disclosure Risk
+   Stack traces exposed in error responses
+   📍 src/api/users.ts:62
+   💡 Use production error handler that sanitizes output
+
+🟢 LOW: Missing rate limiting
+   New endpoint has no rate limiting
+   📍 src/api/users.ts:30
+   💡 Add rate limiter middleware
+
+VERDICT: Address HIGH issues before merging. LOW can be follow-up.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Example 3: Quick validation (when needed)
+
+```
+User: /specweave:judge-llm src/utils/format.ts --quick
+
+Claude: [Standard reasoning, no extended thinking]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+JUDGE-LLM VERDICT: APPROVED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: QUICK (standard reasoning)
+Confidence: 0.75
+Files Analyzed: 1
+
+REASONING:
+Utility formatting functions look correct. No obvious issues.
+
+VERDICT: Looks good for a utility file.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Simplest Usage
+
+Just say in your prompt:
+```
+"judge-llm my work"
+"use judge-llm"
+"judge-llm this"
+```
+
+Claude will:
+1. Automatically gather context from the conversation
+2. Use ULTRATHINK extended thinking by default
+3. Apply thorough LLM-as-Judge evaluation
+
+## Difference from /specweave:qa
+
+| Aspect | `/specweave:qa` | `/specweave:judge-llm` |
+|--------|-----------------|------------------------|
+| **Scope** | Increments only | Any files |
+| **Input** | Increment ID | Files, git diff, context |
+| **Default Mode** | Standard | **ULTRATHINK** |
+| **Pattern** | 7-dimension scoring | Judge LLM reasoning |
+| **Focus** | Spec quality, risks | Code correctness |
+| **When** | Before increment close | After any work |
+
+## Best Practices
+
+1. **Use by default**: Ultrathink is worth the extra time for quality
+2. **Use `--staged`**: Validate before committing
+3. **Use `--strict` for critical code**: Payment, auth, security
+4. **Fix CRITICAL issues immediately**: Never ignore these
+5. **Trust the ultrathink analysis**: Extended thinking catches subtle issues
+
+## Limitations
+
+- ❌ Doesn't execute tests (use test runners)
+- ❌ Doesn't auto-apply fixes (only suggests)
+- ❌ May miss domain-specific issues
+- ❌ Not a replacement for human review
+
+## Related
+
+- `/specweave:qa` - Increment-bound quality assessment
+- `/specweave:validate` - Rule-based increment validation
+- `ado-sync-judge` agent - Uses judge pattern for sync validation

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

@@ -162,7 +162,7 @@ Uncategorized: 14 files
 After running this command, use:
 
 ```bash
-/specweave-docs:preview
+/specweave-docs:view
 ```
 
 The generated indexes will appear in the sidebar:
@@ -180,6 +180,6 @@ The generated indexes will appear in the sidebar:
 
 ## Related Commands
 
-- `/specweave-docs:preview` - Preview documentation with Docusaurus
+- `/specweave-docs:view` - View documentation with Docusaurus
 - `/specweave-docs:build` - Build static documentation site
 - Enterprise health report - Includes organization recommendations