specweave 0.28.68 → 0.29.1

package/plugins/specweave/commands/specweave-sync-logs.md

@@ -0,0 +1,131 @@
+# Sync Logs Command
+
+Query and export sync audit logs. Supports date range, platform, and result filtering.
+
+## Usage
+
+```bash
+/specweave:sync-logs                       # Last 24 hours
+/specweave:sync-logs --since "2025-12-01"  # Since specific date
+/specweave:sync-logs --platform github     # Filter by platform
+/specweave:sync-logs --result denied       # Filter by result
+/specweave:sync-logs --export logs.json    # Export to file
+```
+
+## Arguments
+
+- `--since <date>`: Start date (ISO 8601 or YYYY-MM-DD)
+- `--until <date>`: End date (ISO 8601 or YYYY-MM-DD)
+- `--platform <name>`: Filter by platform: `github`, `jira`, `ado`
+- `--operation <type>`: Filter by operation type
+- `--result <result>`: Filter by result: `success`, `denied`, `error`
+- `--limit <n>`: Maximum entries to return (default: 100)
+- `--export <path>`: Export to file (JSON, JSONL, or CSV based on extension)
+- `--json`: Output as JSON to stdout
+
+## Examples
+
+### View Recent Logs
+
+```bash
+/specweave:sync-logs
+```
+
+Output:
+```
+📋 SYNC LOGS (last 24 hours)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+2025-12-01 12:00:05  github  upsert-internal  FS-001     ✅ success   150ms
+2025-12-01 12:00:04  jira    update-status    US-001     ✅ success   200ms
+2025-12-01 12:00:03  github  upsert-external  EXT-001    🚫 denied    -
+2025-12-01 12:00:02  ado     read             WI-001     ❌ error     -
+2025-12-01 12:00:01  github  upsert-internal  FS-002     ✅ success   100ms
+
+Showing 5 of 57 entries
+Use --limit to show more, --export to save all
+```
+
+### Filter by Platform
+
+```bash
+/specweave:sync-logs --platform github
+```
+
+### Filter by Result
+
+```bash
+/specweave:sync-logs --result denied
+```
+
+Shows only denied operations (permission enforcement in action):
+```
+📋 SYNC LOGS (denied only)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+2025-12-01 12:00:03  github  upsert-external  EXT-001    🚫 denied
+   Reason: External updates disabled in config
+
+2025-12-01 11:45:00  jira    delete           JIRA-123   🚫 denied
+   Reason: Delete operations not permitted
+```
+
+### Date Range Query
+
+```bash
+/specweave:sync-logs --since "2025-12-01" --until "2025-12-02"
+```
+
+### Export to File
+
+```bash
+# Export to JSON
+/specweave:sync-logs --export logs.json
+
+# Export to CSV (for spreadsheets)
+/specweave:sync-logs --export logs.csv
+
+# Export to JSONL (for processing)
+/specweave:sync-logs --export logs.jsonl
+```
+
+## Output Formats
+
+### Default (Human-readable)
+
+Tabular format with timestamps, platforms, operations, items, results, and durations.
+
+### JSON (`--json` or `.json` export)
+
+```json
+{
+  "metadata": {
+    "exportedAt": "2025-12-01T12:00:00Z",
+    "total": 57,
+    "hasMore": false,
+    "query": { "limit": 100 }
+  },
+  "entries": [
+    {
+      "timestamp": "2025-12-01T12:00:05Z",
+      "platform": "github",
+      "operation": "upsert-internal",
+      "itemId": "FS-001",
+      "result": "success",
+      "durationMs": 150
+    }
+  ]
+}
+```
+
+### CSV (`.csv` export)
+
+```csv
+timestamp,platform,operation,itemId,result,reason,error,durationMs
+2025-12-01T12:00:05Z,github,upsert-internal,FS-001,success,,,150
+```
+
+## Related
+
+- `/specweave:sync-monitor`: Dashboard with activity summary
+- `/specweave:notifications`: View sync failure notifications

package/plugins/specweave/commands/specweave-sync-monitor.md

@@ -0,0 +1,57 @@
+# Sync Monitor Dashboard
+
+Show sync orchestration status at a glance - jobs, notifications, and recent activity.
+
+## Usage
+
+```bash
+/specweave:sync-monitor           # Show dashboard
+/specweave:sync-monitor --json    # JSON output for scripting
+```
+
+## Arguments
+
+- `--json`: Output machine-readable JSON instead of formatted dashboard
+
+## Workflow
+
+1. **Fetch dashboard data** from DashboardDataProvider:
+   - Get all scheduled job statuses (real-time)
+   - Get notification summary (5s cache)
+   - Get last 24h sync activity (1m cache)
+
+2. **Display formatted dashboard**:
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║                    SYNC MONITOR DASHBOARD                     ║
+   ╠══════════════════════════════════════════════════════════════╣
+   ║ SCHEDULED JOBS                                                ║
+   ╟──────────────────────────────────────────────────────────────╢
+   ║ external-sync      │ ✅ idle    │ Last: 5m ago │ Next: 10m   ║
+   ║ discrepancy-check  │ 🔄 running │ Started: 2m ago            ║
+   ║ living-docs-sync   │ ⏸️ disabled                             ║
+   ╠══════════════════════════════════════════════════════════════╣
+   ║ PENDING NOTIFICATIONS (3)                                     ║
+   ╟──────────────────────────────────────────────────────────────╢
+   ║ ❗ CRITICAL: GitHub sync failed (rate limited)                ║
+   ║ ⚠️ WARNING: 2 discrepancies detected in FS-045               ║
+   ║ ℹ️ INFO: 107 items imported from JIRA (project CORE)         ║
+   ╠══════════════════════════════════════════════════════════════╣
+   ║ RECENT SYNC ACTIVITY (last 24h)                               ║
+   ╟──────────────────────────────────────────────────────────────╢
+   ║ GitHub: 45 synced │ JIRA: 12 synced │ ADO: 0 synced          ║
+   ║ Success: 55 │ Failed: 2 │ Skipped (no permission): 8         ║
+   ╚══════════════════════════════════════════════════════════════╝
+   ```
+
+## Output
+
+- **Jobs Section**: Shows each scheduled job with status emoji, last run, next run
+- **Notifications Section**: Shows pending notification count and recent items
+- **Activity Section**: Shows last 24h sync stats by platform and result
+
+## Related
+
+- `/specweave:notifications`: Manage notifications
+- `/specweave:discrepancies`: View and act on discrepancies
+- `/specweave:sync-logs`: Query sync audit logs

package/plugins/specweave/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/v2/dispatchers/session-start.sh"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\" session-start"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/v2/guards/completion-guard.sh"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\" completion-guard"
           }
         ]
       }
@@ -29,7 +29,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/v2/dispatchers/post-tool-use.sh"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/universal/dispatcher.mjs\" post-tool-use"
           }
         ]
       }

package/plugins/specweave/hooks/lib/scheduler-startup.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# scheduler-startup.sh - Check for due jobs on session start
+# Called from session-start hook to initialize scheduler
+set -e
+
+# Skip if hooks disabled
+[[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]] && exit 0
+
+# Find project root
+PROJECT_ROOT="$PWD"
+while [[ "$PROJECT_ROOT" != "/" ]] && [[ ! -d "$PROJECT_ROOT/.specweave" ]]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+
+# Exit if no .specweave directory
+[[ ! -d "$PROJECT_ROOT/.specweave" ]] && exit 0
+
+# Paths
+SCHEDULED_JOBS_FILE="$PROJECT_ROOT/.specweave/state/scheduled-jobs.json"
+CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
+
+# Check if scheduler is enabled
+if [[ -f "$CONFIG_FILE" ]]; then
+  # Check if sync.orchestration.scheduler.enabled is true
+  # Use node for reliable JSON parsing
+  SCHEDULER_ENABLED=$(node -e "
+    try {
+      const config = require('$CONFIG_FILE');
+      const enabled = config?.sync?.orchestration?.scheduler?.enabled ?? false;
+      console.log(enabled ? 'true' : 'false');
+    } catch(e) {
+      console.log('false');
+    }
+  " 2>/dev/null || echo "false")
+
+  if [[ "$SCHEDULER_ENABLED" != "true" ]]; then
+    exit 0
+  fi
+fi
+
+# Check if scheduled jobs file exists
+if [[ ! -f "$SCHEDULED_JOBS_FILE" ]]; then
+  exit 0
+fi
+
+# Use node to check for due jobs (robust JSON parsing)
+DUE_JOBS=$(node -e "
+  const fs = require('fs');
+  try {
+    const data = JSON.parse(fs.readFileSync('$SCHEDULED_JOBS_FILE', 'utf-8'));
+    const now = Date.now();
+    const dueJobs = (data.jobs || []).filter(job => {
+      if (!job.schedule.enabled || job.status !== 'idle') return false;
+      if (!job.schedule.nextRun) return true;
+      return new Date(job.schedule.nextRun).getTime() <= now;
+    });
+    console.log(JSON.stringify(dueJobs.map(j => j.id)));
+  } catch(e) {
+    console.log('[]');
+  }
+" 2>/dev/null || echo "[]")
+
+# Exit if no due jobs
+if [[ "$DUE_JOBS" == "[]" ]]; then
+  exit 0
+fi
+
+# Log due jobs (for debugging)
+echo "📅 Due sync jobs: $DUE_JOBS" >> "$PROJECT_ROOT/.specweave/logs/scheduler.log" 2>/dev/null || true
+
+# Output status (will be captured by hook system)
+echo "{\"continue\": true, \"systemMessage\": \"📅 Scheduled sync jobs ready to run. Use /specweave:sync-now to execute.\"}"

package/plugins/specweave/hooks/universal/dispatcher.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * Universal Hook Dispatcher (Cross-Platform)
+ *
+ * Routes hook calls to the appropriate TypeScript implementation.
+ * Works on Windows, macOS, and Linux.
+ *
+ * Usage:
+ *   node dispatcher.mjs <hook-type>
+ *
+ * Where hook-type is one of:
+ *   - session-start
+ *   - post-tool-use
+ *   - completion-guard
+ *
+ * @module hooks/universal/dispatcher
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Hook type from arguments
+const hookType = process.argv[2] || 'unknown';
+
+/**
+ * Find the dist/hooks directory
+ */
+function findHooksDir() {
+  // Try multiple locations
+  const candidates = [
+    // Production: node_modules/specweave/dist/hooks
+    join(__dirname, '..', '..', '..', '..', 'node_modules', 'specweave', 'dist', 'hooks'),
+    // Development: project root dist/hooks
+    join(__dirname, '..', '..', '..', '..', 'dist', 'hooks'),
+    // Relative to this file
+    join(__dirname, '..', '..', '..', '..', 'src', 'hooks'),
+  ];
+
+  for (const candidate of candidates) {
+    const resolved = resolve(candidate);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Run a hook script
+ */
+async function runHook(scriptName) {
+  const hooksDir = findHooksDir();
+  if (!hooksDir) {
+    // No hooks directory - just continue
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const scriptPath = join(hooksDir, scriptName);
+  if (!existsSync(scriptPath) && !existsSync(scriptPath + '.js')) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Spawn node to run the script
+  const child = spawn(process.execPath, [scriptPath], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+    windowsHide: true,
+  });
+
+  return new Promise((resolve) => {
+    child.on('exit', (code) => resolve(code || 0));
+    child.on('error', () => {
+      console.log(JSON.stringify({ continue: true }));
+      resolve(1);
+    });
+  });
+}
+
+/**
+ * Cached Git Bash path (computed once per session)
+ * undefined = not yet checked, null = checked and not found, string = path found
+ */
+let gitBashCache = undefined;
+
+/**
+ * Find Git Bash on Windows (with caching)
+ *
+ * Checks common Git for Windows installation paths.
+ * Caches result to avoid repeated filesystem checks.
+ */
+function findGitBash() {
+  // Return cached result if available
+  if (gitBashCache !== undefined) {
+    return gitBashCache;
+  }
+
+  const gitBashPaths = [
+    // Environment variable paths with proper fallbacks
+    join(process.env.PROGRAMFILES || 'C:\\Program Files', 'Git', 'bin', 'bash.exe'),
+    join(process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)', 'Git', 'bin', 'bash.exe'),
+    join(process.env.LOCALAPPDATA || '', 'Programs', 'Git', 'bin', 'bash.exe'),
+    // Hardcoded fallbacks for edge cases where env vars are missing
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    'C:\\Git\\bin\\bash.exe',
+  ];
+
+  for (const p of gitBashPaths) {
+    if (p && existsSync(p)) {
+      gitBashCache = p;
+      return p;
+    }
+  }
+
+  gitBashCache = null;
+  return null;
+}
+
+/**
+ * Fallback to bash script if TypeScript not built
+ *
+ * @param bashScript - Name of the bash script (e.g., 'post-tool-use.sh')
+ * @param subdir - Subdirectory under v2 (e.g., 'dispatchers', 'guards')
+ */
+async function fallbackToBash(bashScript, subdir = 'dispatchers') {
+  const isWindows = process.platform === 'win32';
+  const bashDir = join(__dirname, '..', 'v2', subdir);
+  const scriptPath = join(bashDir, bashScript);
+
+  if (!existsSync(scriptPath)) {
+    console.log(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  if (isWindows) {
+    // Strategy 1: Git Bash (preferred - most common)
+    const bashExe = findGitBash();
+    if (bashExe) {
+      const child = spawn(bashExe, [scriptPath], {
+        stdio: ['inherit', 'inherit', 'inherit'],
+        windowsHide: true,
+      });
+      return new Promise((resolve) => {
+        child.on('exit', (code) => resolve(code || 0));
+        child.on('error', () => {
+          console.log(JSON.stringify({ continue: true }));
+          resolve(1);
+        });
+      });
+    }
+
+    // Strategy 2: WSL (if Git Bash not available) - FALLBACK only
+    const wslPath = join(process.env.SYSTEMROOT || 'C:\\Windows', 'System32', 'wsl.exe');
+    if (existsSync(wslPath)) {
+      // Convert Windows path to WSL path:
+      // 1. Backslashes to forward slashes: C:\path\file -> C:/path/file
+      // 2. Drive letter to /mnt/: C:/path/file -> /mnt/c/path/file
+      // NOTE: Handle BOTH uppercase and lowercase drive letters (C: and c:)
+      const wslScriptPath = scriptPath
+        .replace(/\\/g, '/')
+        .replace(/^([A-Za-z]):/, (_, d) => `/mnt/${d.toLowerCase()}`);
+      const child = spawn('wsl', ['bash', wslScriptPath], {
+        stdio: ['inherit', 'inherit', 'inherit'],
+        windowsHide: true,
+      });
+      return new Promise((resolve) => {
+        child.on('exit', (code) => resolve(code || 0));
+        child.on('error', () => {
+          console.log(JSON.stringify({ continue: true }));
+          resolve(1);
+        });
+      });
+    }
+
+    // Strategy 3: No bash available - output warning and continue
+    // Hooks should not block Claude Code operation
+    console.log(JSON.stringify({
+      continue: true,
+      systemMessage: 'SpecWeave hooks require Git Bash on Windows. Install from https://git-scm.com'
+    }));
+    return;
+  }
+
+  // POSIX (macOS, Linux) - run directly
+  const child = spawn('bash', [scriptPath], {
+    stdio: ['inherit', 'inherit', 'inherit'],
+  });
+  return new Promise((resolve) => {
+    child.on('exit', (code) => resolve(code || 0));
+    child.on('error', () => {
+      console.log(JSON.stringify({ continue: true }));
+      resolve(1);
+    });
+  });
+}
+
+// Main routing
+async function main() {
+  const isWindows = process.platform === 'win32';
+
+  try {
+    switch (hookType) {
+      case 'session-start':
+        // CRITICAL: On Windows, ALWAYS use TypeScript implementation
+        // Bash nohup/disown is unreliable in Git Bash (process may terminate early)
+        // TypeScript uses proper Windows detached spawn with windowsHide
+        if (isWindows) {
+          await runHook('session-start.js');
+        } else {
+          // POSIX: try TypeScript first (preferred), fallback to bash for compatibility
+          try {
+            await runHook('session-start.js');
+          } catch {
+            await fallbackToBash('session-start.sh', 'dispatchers');
+          }
+        }
+        break;
+
+      case 'post-tool-use':
+        // Currently only bash implementation
+        // On Windows without Git Bash, will gracefully skip
+        await fallbackToBash('post-tool-use.sh', 'dispatchers');
+        break;
+
+      case 'completion-guard':
+        // Guards are in a different subdirectory
+        // On Windows without Git Bash, will gracefully skip
+        await fallbackToBash('completion-guard.sh', 'guards');
+        break;
+
+      default:
+        console.log(JSON.stringify({ continue: true, error: `Unknown hook type: ${hookType}` }));
+    }
+  } catch (err) {
+    console.log(JSON.stringify({ continue: true, error: String(err) }));
+  }
+}
+
+main();

package/plugins/specweave/hooks/universal/session-start.cmd

@@ -0,0 +1,16 @@
+@echo off
+:: Universal Session Start Hook for Windows
+:: Calls the Node.js dispatcher
+
+:: Find node.exe
+where node >nul 2>&1
+if %ERRORLEVEL% neq 0 (
+    echo {"continue": true, "error": "Node.js not found"}
+    exit /b 0
+)
+
+:: Get the directory of this script
+set "SCRIPT_DIR=%~dp0"
+
+:: Run the dispatcher
+node "%SCRIPT_DIR%dispatcher.mjs" session-start

package/plugins/specweave/hooks/universal/session-start.ps1

@@ -0,0 +1,16 @@
+# Universal Session Start Hook for Windows PowerShell
+# Calls the Node.js dispatcher for cross-platform compatibility
+
+# Find node.exe
+$nodePath = Get-Command node -ErrorAction SilentlyContinue
+
+if (-not $nodePath) {
+    Write-Host '{"continue": true, "error": "Node.js not found"}'
+    exit 0
+}
+
+# Get script directory
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+# Run the dispatcher
+& node "$scriptDir\dispatcher.mjs" session-start

package/plugins/specweave/hooks/v2/dispatchers/session-start.sh

@@ -15,10 +15,19 @@ done
 # Consume stdin
 cat > /dev/null
 
-PROCESSOR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../queue" && pwd)/processor.sh"
-[[ ! -f "$PROCESSOR" ]] && exit 0
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROCESSOR="$HOOK_DIR/../queue/processor.sh"
+SCHEDULER_STARTUP="$HOOK_DIR/../../lib/scheduler-startup.sh"
+
+# Launch queue processor in background (daemon mode)
+if [[ -f "$PROCESSOR" ]]; then
+  nohup bash "$PROCESSOR" --daemon > /dev/null 2>&1 &
+  disown 2>/dev/null
+fi
+
+# Check for due scheduled jobs (non-blocking)
+if [[ -f "$SCHEDULER_STARTUP" ]]; then
+  bash "$SCHEDULER_STARTUP" 2>/dev/null || true
+fi
 
-# Launch processor in background (daemon mode)
-nohup bash "$PROCESSOR" --daemon > /dev/null 2>&1 &
-disown 2>/dev/null
 exit 0

package/plugins/specweave/lib/vendor/core/types/increment-metadata.d.ts

@@ -247,6 +247,11 @@ export interface ExternalContainerContext {
 }
 /**
  * Extended increment metadata with multi-project support (v0.29.0+)
+ *
+ * NOTE (v0.29.0): featureId field was REMOVED
+ * Feature ID is derived from increment number: 0081 → FS-081
+ * Use deriveFeatureId() from src/utils/feature-id-derivation.ts
+ * See ADR-0140 for rationale
  */
 export interface IncrementMetadataV2 extends IncrementMetadata {
     /** Single project ID (backward compatible) */
@@ -255,8 +260,6 @@ export interface IncrementMetadataV2 extends IncrementMetadata {
     multiProject?: MultiProjectUserStory;
     /** External container context for 2-level directory structure */
     externalContainer?: ExternalContainerContext;
-    /** Feature ID this increment belongs to */
-    featureId?: string;
     /** Epic ID if part of an epic */
     epicId?: string;
 }