burhan-mop 0.1.0

package/.claude/helpers/guidance-hooks.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Guidance Hooks for Claude Flow V3
+# Provides context and routing for Claude Code operations
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CACHE_DIR="$PROJECT_ROOT/.claude-flow"
+
+# Ensure cache directory exists
+mkdir -p "$CACHE_DIR" 2>/dev/null || true
+
+# Color codes
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+RESET='\033[0m'
+DIM='\033[2m'
+
+# Get command
+COMMAND="${1:-help}"
+shift || true
+
+case "$COMMAND" in
+    pre-edit)
+        FILE_PATH="$1"
+        if [[ -n "$FILE_PATH" ]]; then
+            if [[ "$FILE_PATH" =~ (config|secret|credential|password|key|auth) ]]; then
+                echo -e "${YELLOW}[Guidance] Security-sensitive file${RESET}"
+            fi
+            if [[ "$FILE_PATH" =~ ^v3/ ]]; then
+                echo -e "${CYAN}[Guidance] V3 module - follow ADR guidelines${RESET}"
+            fi
+        fi
+        exit 0
+        ;;
+
+    post-edit)
+        FILE_PATH="$1"
+        echo "$(date -Iseconds) edit $FILE_PATH" >> "$CACHE_DIR/edit-history.log" 2>/dev/null || true
+        exit 0
+        ;;
+
+    pre-command)
+        COMMAND_STR="$1"
+        if [[ "$COMMAND_STR" =~ (rm -rf|sudo|chmod 777) ]]; then
+            echo -e "${RED}[Guidance] High-risk command${RESET}"
+        fi
+        exit 0
+        ;;
+
+    route)
+        TASK="$1"
+        [[ -z "$TASK" ]] && exit 0
+        if [[ "$TASK" =~ (security|CVE|vulnerability) ]]; then
+            echo -e "${DIM}[Route] security-architect${RESET}"
+        elif [[ "$TASK" =~ (memory|AgentDB|HNSW|vector) ]]; then
+            echo -e "${DIM}[Route] memory-specialist${RESET}"
+        elif [[ "$TASK" =~ (performance|optimize|benchmark) ]]; then
+            echo -e "${DIM}[Route] performance-engineer${RESET}"
+        elif [[ "$TASK" =~ (test|TDD|spec) ]]; then
+            echo -e "${DIM}[Route] test-architect${RESET}"
+        fi
+        exit 0
+        ;;
+
+    session-context)
+        cat << 'EOF'
+## V3 Development Context
+
+**Architecture**: Domain-Driven Design with 15 @claude-flow modules
+**Priority**: Security-first (CVE-1, CVE-2, CVE-3 remediation)
+**Performance Targets**:
+- HNSW search: 150x-12,500x faster
+- Flash Attention: 2.49x-7.47x speedup
+- Memory: 50-75% reduction
+
+**Active Patterns**:
+- Use TDD London School (mock-first)
+- Event sourcing for state changes
+- agentic-flow@alpha as core foundation
+- Bounded contexts with clear interfaces
+
+**Code Quality Rules**:
+- Files under 500 lines
+- No hardcoded secrets
+- Input validation at boundaries
+- Typed interfaces for all public APIs
+
+**Learned Patterns**: 17 available for reference
+EOF
+        exit 0
+        ;;
+
+    user-prompt)
+        exit 0
+        ;;
+
+    *)
+        exit 0
+        ;;
+esac

package/.claude/helpers/health-monitor.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Claude Flow V3 - Health Monitor Worker
+# Checks disk space, memory pressure, process health
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+METRICS_DIR="$PROJECT_ROOT/.claude-flow/metrics"
+HEALTH_FILE="$METRICS_DIR/health.json"
+LAST_RUN_FILE="$METRICS_DIR/.health-last-run"
+
+mkdir -p "$METRICS_DIR"
+
+should_run() {
+  if [ ! -f "$LAST_RUN_FILE" ]; then return 0; fi
+  local last_run=$(cat "$LAST_RUN_FILE" 2>/dev/null || echo "0")
+  local now=$(date +%s)
+  [ $((now - last_run)) -ge 300 ]  # 5 minutes
+}
+
+check_health() {
+  echo "[$(date +%H:%M:%S)] Running health check..."
+
+  # Disk usage
+  local disk_usage=$(df -h "$PROJECT_ROOT" 2>/dev/null | awk 'NR==2 {print $5}' | tr -d '%')
+  local disk_free=$(df -h "$PROJECT_ROOT" 2>/dev/null | awk 'NR==2 {print $4}')
+
+  # Memory usage
+  local mem_total=$(free -m 2>/dev/null | awk '/Mem:/ {print $2}' || echo "0")
+  local mem_used=$(free -m 2>/dev/null | awk '/Mem:/ {print $3}' || echo "0")
+  local mem_pct=$((mem_used * 100 / (mem_total + 1)))
+
+  # Process counts
+  local node_procs=$(pgrep -c node 2>/dev/null || echo "0")
+  local agentic_procs=$(ps aux 2>/dev/null | grep -c "agentic-flow" | grep -v grep || echo "0")
+
+  # CPU load
+  local load_avg=$(cat /proc/loadavg 2>/dev/null | awk '{print $1}' || echo "0")
+
+  # File descriptor usage
+  local fd_used=$(ls /proc/$$/fd 2>/dev/null | wc -l || echo "0")
+
+  # Determine health status
+  local status="healthy"
+  local warnings=""
+
+  if [ "$disk_usage" -gt 90 ]; then
+    status="critical"
+    warnings="$warnings disk_full"
+  elif [ "$disk_usage" -gt 80 ]; then
+    status="warning"
+    warnings="$warnings disk_high"
+  fi
+
+  if [ "$mem_pct" -gt 90 ]; then
+    status="critical"
+    warnings="$warnings memory_full"
+  elif [ "$mem_pct" -gt 80 ]; then
+    [ "$status" != "critical" ] && status="warning"
+    warnings="$warnings memory_high"
+  fi
+
+  # Write health metrics
+  cat > "$HEALTH_FILE" << EOF
+{
+  "status": "$status",
+  "timestamp": "$(date -Iseconds)",
+  "disk": {
+    "usage_pct": $disk_usage,
+    "free": "$disk_free"
+  },
+  "memory": {
+    "total_mb": $mem_total,
+    "used_mb": $mem_used,
+    "usage_pct": $mem_pct
+  },
+  "processes": {
+    "node": $node_procs,
+    "agentic_flow": $agentic_procs
+  },
+  "load_avg": $load_avg,
+  "fd_used": $fd_used,
+  "warnings": "$(echo $warnings | xargs)"
+}
+EOF
+
+  echo "[$(date +%H:%M:%S)] ✓ Health: $status | Disk: ${disk_usage}% | Memory: ${mem_pct}% | Load: $load_avg"
+
+  date +%s > "$LAST_RUN_FILE"
+
+  # Return non-zero if unhealthy
+  [ "$status" = "healthy" ] && return 0 || return 1
+}
+
+case "${1:-check}" in
+  "run") check_health ;;
+  "check") should_run && check_health || echo "[$(date +%H:%M:%S)] Skipping (throttled)" ;;
+  "force") rm -f "$LAST_RUN_FILE"; check_health ;;
+  "status")
+    if [ -f "$HEALTH_FILE" ]; then
+      jq -r '"Status: \(.status) | Disk: \(.disk.usage_pct)% | Memory: \(.memory.usage_pct)% | Load: \(.load_avg)"' "$HEALTH_FILE"
+    else
+      echo "No health data available"
+    fi
+    ;;
+  *) echo "Usage: $0 [run|check|force|status]" ;;
+esac

package/.claude/helpers/hook-handler.cjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * Claude Flow Hook Handler (Cross-Platform)
+ * Dispatches hook events to the appropriate helper modules.
+ *
+ * Usage: node hook-handler.cjs <command> [args...]
+ *
+ * Commands:
+ *   route          - Route a task to optimal agent (reads PROMPT from env/stdin)
+ *   pre-bash       - Validate command safety before execution
+ *   post-edit      - Record edit outcome for learning
+ *   session-restore - Restore previous session state
+ *   session-end    - End session and persist state
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const helpersDir = __dirname;
+
+// Safe require with stdout suppression - the helper modules have CLI
+// sections that run unconditionally on require(), so we mute console
+// during the require to prevent noisy output.
+function safeRequire(modulePath) {
+  try {
+    if (fs.existsSync(modulePath)) {
+      const origLog = console.log;
+      const origError = console.error;
+      console.log = () => {};
+      console.error = () => {};
+      try {
+        const mod = require(modulePath);
+        return mod;
+      } finally {
+        console.log = origLog;
+        console.error = origError;
+      }
+    }
+  } catch (e) {
+    // silently fail
+  }
+  return null;
+}
+
+const router = safeRequire(path.join(helpersDir, 'router.js'));
+const session = safeRequire(path.join(helpersDir, 'session.js'));
+const memory = safeRequire(path.join(helpersDir, 'memory.js'));
+const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));
+
+// ── Intelligence timeout protection (fixes #1530, #1531) ───────────────────
+const INTELLIGENCE_TIMEOUT_MS = 3000;
+function runWithTimeout(fn, label) {
+  // For synchronous blocking calls, we use a global safety timer.
+  // The readJSON file-size guard prevents loading huge files, but this
+  // is an additional safety net.
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      process.stderr.write("[WARN] " + label + " timed out after " + INTELLIGENCE_TIMEOUT_MS + "ms, skipping\n");
+      resolve(null);
+    }, INTELLIGENCE_TIMEOUT_MS);
+    try {
+      const result = fn();
+      clearTimeout(timer);
+      resolve(result);
+    } catch (e) {
+      clearTimeout(timer);
+      resolve(null);
+    }
+  });
+}
+
+
+// Get the command from argv
+const [,, command, ...args] = process.argv;
+
+// Read stdin with timeout — Claude Code sends hook data as JSON via stdin.
+// Timeout prevents hanging when stdin is not properly closed (common on Windows).
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return new Promise((resolve) => {
+    let data = '';
+    const timer = setTimeout(() => {
+      process.stdin.removeAllListeners();
+      process.stdin.pause();
+      resolve(data);
+    }, 500);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(data); });
+    process.stdin.resume();
+  });
+}
+
+async function main() {
+  // Global safety timeout: hooks must NEVER hang (#1530, #1531)
+  const safetyTimer = setTimeout(() => {
+    process.stderr.write("[WARN] Hook handler global timeout (5s), forcing exit\n");
+    process.exit(0);
+  }, 5000);
+  safetyTimer.unref(); // don't keep process alive just for this timer
+
+  let stdinData = '';
+  try { stdinData = await readStdin(); } catch (e) { /* ignore stdin errors */ }
+
+  let hookInput = {};
+  if (stdinData.trim()) {
+    try { hookInput = JSON.parse(stdinData); } catch (e) { /* ignore parse errors */ }
+  }
+
+  // Normalize snake_case/camelCase: Claude Code sends tool_input/tool_name (snake_case)
+  const toolInput = hookInput.toolInput || hookInput.tool_input || {};
+  const toolName = hookInput.toolName || hookInput.tool_name || '';
+
+  // Merge stdin data into prompt resolution: prefer stdin fields, then env, then argv.
+  // `toolInput` is an object (e.g. {command:"ls"}) — it's truthy but not a string,
+  // so falling back to it directly bound `prompt` to the object and tripped
+  // `.toLowerCase()` / `.substring()` on every Bash hook (#1944). Use the
+  // `.command` field instead, which is the actual string the hook needs.
+  const prompt = hookInput.prompt || hookInput.command || toolInput.command
+    || process.env.PROMPT || process.env.TOOL_INPUT_command || args.join(' ') || '';
+
+const handlers = {
+  'route': () => {
+    // Inject ranked intelligence context before routing
+    if (intelligence && intelligence.getContext) {
+      try {
+        const ctx = intelligence.getContext(prompt);
+        if (ctx) console.log(ctx);
+      } catch (e) { /* non-fatal */ }
+    }
+    if (router && router.routeTask) {
+      const result = router.routeTask(prompt);
+      // Format output for Claude Code hook consumption — real data only
+      const output = [
+        `[INFO] Routing task: ${prompt.substring(0, 80) || '(no prompt)'}`,
+        '',
+        '+------------------- Primary Recommendation -------------------+',
+        `| Agent: ${result.agent.padEnd(53)}|`,
+        `| Confidence: ${(result.confidence * 100).toFixed(1)}%${' '.repeat(44)}|`,
+        `| Reason: ${(result.reason || '').substring(0, 53).padEnd(53)}|`,
+        '+--------------------------------------------------------------+',
+      ];
+      console.log(output.join('\n'));
+    } else {
+      console.log('[INFO] Router not available, using default routing');
+    }
+  },
+
+  'pre-bash': () => {
+    // Basic command safety check — prefer stdin command data from Claude Code.
+    // String() wrap is belt-and-suspenders for #2017: even if a future regression
+    // re-binds `prompt` or `hookInput.command` to a non-string, `.toLowerCase()`
+    // can no longer throw a TypeError that the global try/catch would swallow
+    // (silently exiting 0 and letting the dangerous command through).
+    const cmd = String(hookInput.command || toolInput.command || prompt || '').toLowerCase();
+    const dangerous = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:'];
+    for (const d of dangerous) {
+      if (cmd.includes(d)) {
+        console.error(`[BLOCKED] Dangerous command detected: ${d}`);
+        process.exit(1);
+      }
+    }
+    console.log('[OK] Command validated');
+  },
+
+  'post-edit': () => {
+    // Record edit for session metrics
+    if (session && session.metric) {
+      try { session.metric('edits'); } catch (e) { /* no active session */ }
+    }
+    // Record edit for intelligence consolidation — prefer stdin data from Claude Code
+    if (intelligence && intelligence.recordEdit) {
+      try {
+        const file = hookInput.file_path || toolInput.file_path
+          || process.env.TOOL_INPUT_file_path || args[0] || '';
+        intelligence.recordEdit(file);
+      } catch (e) { /* non-fatal */ }
+    }
+    console.log('[OK] Edit recorded');
+  },
+
+  'session-restore': async () => {
+    if (session) {
+      // Try restore first, fall back to start
+      const existing = session.restore && session.restore();
+      if (!existing) {
+        session.start && session.start();
+      }
+    } else {
+      // Minimal session restore output
+      const sessionId = `session-${Date.now()}`;
+      console.log(`[INFO] Restoring session: %SESSION_ID%`);
+      console.log('');
+      console.log(`[OK] Session restored from %SESSION_ID%`);
+      console.log(`New session ID: ${sessionId}`);
+      console.log('');
+      console.log('Restored State');
+      console.log('+----------------+-------+');
+      console.log('| Item           | Count |');
+      console.log('+----------------+-------+');
+      console.log('| Tasks          |     0 |');
+      console.log('| Agents         |     0 |');
+      console.log('| Memory Entries |     0 |');
+      console.log('+----------------+-------+');
+    }
+    // Initialize intelligence graph after session restore (with timeout — #1530)
+    if (intelligence && intelligence.init) {
+      const initResult = await runWithTimeout(() => intelligence.init(), 'intelligence.init()');
+      if (initResult && initResult.nodes > 0) {
+        console.log(`[INTELLIGENCE] Loaded ${initResult.nodes} patterns, ${initResult.edges} edges`);
+      }
+    }
+  },
+
+  'session-end': async () => {
+    // Consolidate intelligence before ending session (with timeout — #1530)
+    if (intelligence && intelligence.consolidate) {
+      const consResult = await runWithTimeout(() => intelligence.consolidate(), 'intelligence.consolidate()');
+      if (consResult && consResult.entries > 0) {
+        console.log(`[INTELLIGENCE] Consolidated: ${consResult.entries} entries, ${consResult.edges} edges${consResult.newEntries > 0 ? `, ${consResult.newEntries} new` : ''}, PageRank recomputed`);
+      }
+    }
+    if (session && session.end) {
+      session.end();
+    } else {
+      console.log('[OK] Session ended');
+    }
+  },
+
+  'pre-task': () => {
+    if (session && session.metric) {
+      try { session.metric('tasks'); } catch (e) { /* no active session */ }
+    }
+    // Route the task if router is available
+    if (router && router.routeTask && prompt) {
+      const result = router.routeTask(prompt);
+      console.log(`[INFO] Task routed to: ${result.agent} (confidence: ${result.confidence})`);
+    } else {
+      console.log('[OK] Task started');
+    }
+  },
+
+  'post-task': () => {
+    // Implicit success feedback for intelligence
+    if (intelligence && intelligence.feedback) {
+      try {
+        intelligence.feedback(true);
+      } catch (e) { /* non-fatal */ }
+    }
+    console.log('[OK] Task completed');
+  },
+
+  'stats': () => {
+    if (intelligence && intelligence.stats) {
+      intelligence.stats(args.includes('--json'));
+    } else {
+      console.log('[WARN] Intelligence module not available. Run session-restore first.');
+    }
+  },
+};
+
+  // Execute the handler
+  if (command && handlers[command]) {
+    try {
+      await Promise.resolve(handlers[command]());
+    } catch (e) {
+      // Hooks should never crash Claude Code - fail silently
+      console.log(`[WARN] Hook ${command} encountered an error: ${e.message}`);
+    }
+  } else if (command) {
+    // Unknown command - pass through without error
+    console.log(`[OK] Hook: ${command}`);
+  } else {
+    console.log('Usage: hook-handler.cjs <route|pre-bash|post-edit|session-restore|session-end|pre-task|post-task|stats>');
+  }
+}
+
+// Hooks must ALWAYS exit 0 — Claude Code treats non-zero as "hook error"
+// and skips all subsequent hooks for the event.
+process.exitCode = 0;
+main().catch((e) => {
+  try { console.log(`[WARN] Hook handler error: ${e.message}`); } catch (_) {}
+}).finally(() => {
+  process.exit(0);
+});