wolverine-ai 1.7.0 → 1.8.0

package/README.md

@@ -185,24 +185,26 @@ Most production bugs don't crash the process — Fastify/Express catch them and
 ```
 Route returns 500 (process still alive)
   → Error hook reports to parent via IPC (auto-injected, zero user code changes)
-  → ErrorMonitor tracks consecutive 500s per route
-  → 3 failures in 30s → triggers heal pipeline (same as crash healing)
+  → ErrorMonitor tracks errors per normalized route (/api/users/:id)
+  → Single error triggers heal pipeline immediately (configurable threshold)
   → Fix applied → server restarted → route prober verifies fix
 ```
 
 | Setting | Default | Env Variable |
 |---------|---------|-------------|
-| Failure threshold | 3 | `WOLVERINE_ERROR_THRESHOLD` |
+| Failure threshold | 1 | `WOLVERINE_ERROR_THRESHOLD` |
 | Time window | 30s | `WOLVERINE_ERROR_WINDOW_MS` |
 | Cooldown per route | 60s | `WOLVERINE_ERROR_COOLDOWN_MS` |
 
+Routes are auto-normalized: `/api/users/123` and `/api/users/456` aggregate as `/api/users/:id`.
+
 The error hook auto-patches Fastify and Express via `--require` preload. No middleware, no code changes to your server.
 
 ---
 
 ## Agent Tool Harness
 
-The AI agent has 16 built-in tools (inspired by [claw-code](https://github.com/ultraworkers/claw-code)):
+The AI agent has 18 built-in tools (inspired by [claw-code](https://github.com/ultraworkers/claw-code)):
 
 | Tool | Category | Description |
 |------|----------|-------------|
@@ -220,6 +222,8 @@ The AI agent has 16 built-in tools (inspired by [claw-code](https://github.com/u
 | `run_db_fix` | Database | UPDATE/DELETE/INSERT/ALTER on SQLite (auto-backup before write) |
 | `check_port` | Diagnostic | Check if a port is in use and by what process |
 | `check_env` | Diagnostic | Check environment variables (values auto-redacted) |
+| `audit_deps` | Deps | Full health check: vulnerabilities, outdated, peer conflicts, unused |
+| `check_migration` | Deps | Known upgrade paths (express→fastify, moment→dayjs, etc.) |
 | `web_fetch` | Research | Fetch URL content for documentation/research |
 | `done` | Control | Signal task completion with summary |
 
@@ -315,7 +319,7 @@ Reasoning models (`o-series`, `gpt-5-nano`) automatically get 4x token limits to
 | **Admin Auth** | Dashboard requires key + IP allowlist. Localhost always allowed. Remote IPs via `WOLVERINE_ADMIN_IPS` env var or `POST /api/admin/add-ip` at runtime. Timing-safe comparison, lockout after 10 failures |
 | **Rate Limiter** | Sliding window, min gap, hourly budget, exponential backoff on error loops |
 | **MCP Security** | Per-server tool allowlists, arg sanitization, result injection scanning |
-| **SQL Skill** | `sqlGuard()` middleware blocks 15 injection pattern families on all endpoints |
+| **SQL Skill** | `sqlGuard()` blocks 15 injection pattern families; `idempotencyGuard()` prevents double-fire in cluster mode |
 
 ---
 
@@ -354,17 +358,35 @@ The `📊 Analytics` dashboard panel shows memory/CPU charts, route health statu
 
 ---
 
-## Auto-Clustering
+## Cluster Mode
 
-Wolverine detects your machine and forks the optimal number of workers:
+The server handles its own clustering. Wolverine is the single process manager — it spawns your server, which forks workers internally.
 
 ```bash
-wolverine server/index.js           # auto-detect: 20 cores → 10 workers
-wolverine server/index.js --single  # force single worker (dev mode)
-wolverine server/index.js --workers 4  # force 4 workers
-wolverine --info                    # show system capabilities
+# Enable cluster mode
+WOLVERINE_CLUSTER=true wolverine server/index.js
+
+# System info (cores, RAM, recommended workers)
+wolverine --info
+```
+
+**How it works:**
+```
+Wolverine (single process manager)
+  └── spawns server/index.js
+        ├── WOLVERINE_CLUSTER=false → single server (default)
+        └── WOLVERINE_CLUSTER=true  → master forks N workers
+             ├── Worker 1 (port 3000, reusePort)
+             ├── Worker 2 (port 3000, reusePort)
+             └── Worker N (port 3000, reusePort)
 ```
 
+- **`WOLVERINE_RECOMMENDED_WORKERS`** auto-set based on CPU cores/RAM
+- Workers share port 3000 via `reusePort` — OS handles load balancing
+- Dead workers auto-respawn by the master process
+- Wolverine kills the **entire process tree** on restart (no orphaned workers)
+- **Idempotency protection** prevents double-fire across workers (see below)
+
 **System detection:**
 - CPU cores, model, speed
 - Total/free RAM, disk space
@@ -372,18 +394,6 @@ wolverine --info                    # show system capabilities
 - Container environment (Docker, Kubernetes)
 - Cloud provider (AWS, GCP, Azure, Railway, Fly, Render, Heroku)
 
-**Scaling rules:**
-
-| Cores | Workers |
-|-------|---------|
-| 1 | 1 (no clustering) |
-| 2 | 2 |
-| 3-4 | cores - 1 |
-| 5-8 | cores - 1, cap 6 |
-| 9+ | cores / 2, cap 16 |
-
-Workers auto-respawn on crash with exponential backoff (1s → 30s). Max 5 restarts per worker.
-
 ---
 
 ## Configuration
@@ -412,8 +422,8 @@ Startup:
 - Auto-registers on first run, retries every 60s until platform responds
 - Saves key to `.wolverine/platform-key` (survives restarts)
 - Sends one ~2KB JSON POST every 60 seconds (5s timeout, non-blocking)
-- Payload matches [PLATFORM.md](PLATFORM.md) spec: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (tokens/cost/calls + `byCategory` + `byModel` + `byTool`), `brain`, `backups`
-- Platform analytics aggregates across all servers: total tokens/cost, breakdown by category (heal/chat/develop/security/classify/research/brain), by model, by tool
+- Payload: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (tokens/cost/calls + `byCategory` + `byModel` + `byTool`), `brain`, `backups`
+- Platform aggregates across all servers: total tokens/cost by category, model, tool
 - Secrets redacted before sending
 - Offline-resilient: queues up to 1440 heartbeats locally, drains on reconnect
 
@@ -422,7 +432,7 @@ Startup:
 **Override:** `WOLVERINE_PLATFORM_URL=https://your-own-platform.com`
 **Opt out:** `WOLVERINE_TELEMETRY=false`
 
-See [PLATFORM.md](PLATFORM.md) for the backend spec and [TELEMETRY.md](TELEMETRY.md) for the protocol.
+Telemetry payload includes: `instanceId`, `server`, `process`, `routes`, `repairs`, `usage` (by category/model/tool), `brain`, `backups`.
 
 ---
 
@@ -478,14 +488,66 @@ Full `server/` directory snapshots with lifecycle management:
 Auto-discovered from `src/skills/`. Each skill exports metadata for the registry:
 
 ### SQL Skill (`src/skills/sql.js`)
-- **sqlGuard()** — Express middleware blocking SQL injection (UNION, stacked queries, tautologies, timing attacks, etc.)
-- **SafeDB** — Parameterized-only database wrapper (blocks string concatenation in queries)
+- **sqlGuard()** — Fastify/Express middleware blocking SQL injection (UNION, stacked queries, tautologies, timing attacks, 15 pattern families)
+- **SafeDB** — Cluster-safe database with split read/write connections, FIFO write queue, WAL mode
+- **idempotencyGuard()** — Prevents double-fire of write requests in cluster mode (see below)
+- **db.idempotent(key, fn)** — Database-level dedup for critical writes (payments, orders)
 - Auto-injected into agent prompts when building database features
 
+### Dependency Manager (`src/skills/deps.js`)
+- **diagnose()** — structured diagnosis of dependency errors before AI runs (zero tokens)
+- **healthReport()** — full audit: vulnerabilities, outdated, peer conflicts, unused packages, lock file, health score
+- **getMigration()** — known upgrade paths with code transformation patterns:
+
+| From | To | Why |
+|------|----|-----|
+| `express` | `fastify` | 5.6x faster, async-first, built-in validation |
+| `moment` | `dayjs` | Maintenance mode, 70KB → 2KB |
+| `request` | `node-fetch` | Deprecated since 2020 |
+| `body-parser` | built-in | Included in Express 4.16+ / Fastify |
+| callbacks | `async/await` | Cleaner error handling, no callback hell |
+
 Add new skills by creating a file in `src/skills/` with `SKILL_NAME`, `SKILL_DESCRIPTION`, `SKILL_KEYWORDS`, `SKILL_USAGE` exports.
 
 ---
 
+## Idempotency (Double-Fire Protection)
+
+In cluster mode, a retry or duplicate request can land on a different worker and execute twice. Two layers prevent this:
+
+### Layer 1: HTTP Middleware
+
+```javascript
+const { idempotencyGuard, idempotencyAfterHook } = require("wolverine-ai");
+
+fastify.addHook("preHandler", idempotencyGuard({ db, logger }));
+fastify.addHook("onSend", idempotencyAfterHook(db));
+```
+
+- Client sends `X-Idempotency-Key: order-abc-123` header
+- Without header: auto-generates key from `sha256(method + url + body)`
+- First request: executes handler, caches response in shared SQLite table
+- Duplicate: returns cached response with `X-Idempotency-Cached: true` header
+- Safe methods (GET/HEAD/OPTIONS) always pass through
+- Keys expire after 24h (configurable)
+
+### Layer 2: Database-Level
+
+```javascript
+const result = await db.idempotent("charge-abc-123", (tx) => {
+  tx.run("INSERT INTO charges (id, amount) VALUES (?, ?)", ["abc-123", 99.99]);
+  tx.run("UPDATE balance SET amount = amount - ? WHERE user_id = ?", [99.99, 1]);
+  return { charged: true };
+});
+// result.executed = true (first time) or false (duplicate)
+```
+
+- Wraps `fn` in a transaction with idempotency key check
+- All workers share the `_idempotency` table via WAL mode — globally consistent
+- Auto-created on `db.connect()`, pruned via `db.pruneIdempotency()`
+
+---
+
 ## MCP Integration
 
 Connect external tools via [Model Context Protocol](https://modelcontextprotocol.io):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wolverine-ai",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Self-healing Node.js server framework powered by AI. Catches crashes, diagnoses errors, generates fixes, verifies, and restarts — automatically.",
   "main": "src/index.js",
   "bin": {

package/src/agent/agent-engine.js

@@ -261,6 +261,33 @@ const TOOL_DEFINITIONS = [
       },
     },
   },
+  // ── DEPENDENCY MANAGEMENT ──
+  {
+    type: "function",
+    function: {
+      name: "audit_deps",
+      description: "Run a full dependency health check: npm audit (vulnerabilities), outdated packages, peer dep conflicts, unused packages, lock file status. Returns a health score and actionable fixes. Use BEFORE editing code when the error might be a dependency issue.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "check_migration",
+      description: "Check if a package has a known migration/upgrade path. Use when a deprecated API or old package is causing errors. Returns the recommended replacement and code transformation patterns.",
+      parameters: {
+        type: "object",
+        properties: {
+          package: { type: "string", description: "Package name to check (e.g. 'express', 'moment', 'request')" },
+        },
+        required: ["package"],
+      },
+    },
+  },
   // ── COMPLETION ──
   {
     type: "function",
@@ -352,6 +379,10 @@ DIAGNOSTICS:
 - check_port: Check if a port is in use and by what process
 - check_env: Check environment variables (values auto-redacted for security)
 
+DEPENDENCY MANAGEMENT:
+- audit_deps: Full health check (vulnerabilities, outdated, peer conflicts, unused). Use FIRST for dependency errors.
+- check_migration: Check if a package has a known upgrade path (express→fastify, moment→dayjs, etc.)
+
 RESEARCH:
 - web_fetch: Fetch a URL (docs, npm packages, error solutions)
 
@@ -365,7 +396,7 @@ RESEARCH:
 
 | Error Pattern | Category | Diagnostic Steps | Fix |
 |---|---|---|---|
-| Cannot find module 'X' | DEPENDENCY | check package.json | bash_exec: npm install X |
+| Cannot find module 'X' | DEPENDENCY | audit_deps first, check package.json | bash_exec: npm install X |
 | Cannot find module './X' | IMPORT | glob_files to find real path | edit_file: fix require path |
 | ENOENT: no such file | FILE MISSING | list_dir to check structure | write_file or move_file |
 | EACCES/EPERM | PERMISSION | bash_exec: ls -la | bash_exec: chmod 755 |
@@ -530,6 +561,8 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
       case "check_env":     return this._checkEnv(args);
       case "inspect_db":    return this._inspectDb(args);
       case "run_db_fix":    return this._runDbFix(args);
+      case "audit_deps":    return this._auditDeps(args);
+      case "check_migration": return this._checkMigration(args);
       case "done":          return this._done(args);
       // Legacy aliases
       case "list_files":    return this._globFiles({ pattern: (args.dir || ".") + "/*" + (args.pattern || "") });
@@ -932,6 +965,52 @@ Project root: ${this.cwd}${primaryFile ? `\nPrimary crash file: ${primaryFile}`
     } catch (e) { return { content: `DB error: ${e.message}` }; }
   }
 
+  _auditDeps() {
+    try {
+      const { healthReport } = require("../skills/deps");
+      const report = healthReport(this.cwd);
+      const { redact } = require("../security/secret-redactor");
+      const lines = [
+        `Dependency Health Score: ${report.score}/100 (${report.summary})`,
+        "",
+        `Vulnerabilities: ${report.audit.vulnerabilities} (${report.audit.critical} critical, ${report.audit.high} high, ${report.audit.moderate} moderate)`,
+        report.audit.fixes.length > 0 ? `Fix: ${report.audit.fixes.join(", ")}` : "",
+        "",
+        `Outdated: ${report.outdated.length} packages`,
+        ...report.outdated.slice(0, 10).map(p => `  ${p.name}: ${p.current} → ${p.latest}`),
+        report.outdated.length > 10 ? `  ... and ${report.outdated.length - 10} more` : "",
+        "",
+        `Peer Dependency Issues: ${report.peerDeps.length}`,
+        ...report.peerDeps.slice(0, 5).map(p => `  ${p.package}: ${p.requires}`),
+        "",
+        `Unused Packages: ${report.unused.length}`,
+        report.unused.length > 0 ? `  ${report.unused.join(", ")}` : "",
+        "",
+        `Lock File: ${report.lockFile.healthy ? "OK" : report.lockFile.issue}`,
+        report.lockFile.fix ? `  Fix: ${report.lockFile.fix}` : "",
+      ].filter(l => l !== undefined);
+      console.log(chalk.gray(`    📦 Deps audit: score ${report.score}/100, ${report.audit.vulnerabilities} vulns, ${report.outdated.length} outdated`));
+      return { content: redact(lines.join("\n")) };
+    } catch (e) { return { content: `Deps audit error: ${e.message}` }; }
+  }
+
+  _checkMigration(args) {
+    try {
+      const { getMigration } = require("../skills/deps");
+      const migration = getMigration(args.package);
+      if (!migration) return { content: `No known migration path for '${args.package}'.` };
+      const lines = [
+        `Migration: ${args.package} → ${migration.to}`,
+        `Reason: ${migration.reason}`,
+        "",
+        "Code patterns:",
+        ...migration.patterns.map(p => `  ${p.from}\n  → ${p.to}`),
+      ];
+      console.log(chalk.gray(`    📦 Migration: ${args.package} → ${migration.to}`));
+      return { content: lines.join("\n") };
+    } catch (e) { return { content: `Migration check error: ${e.message}` }; }
+  }
+
   _done(args) {
     console.log(chalk.green(`    ✅ Agent done: ${args.summary}`));
     if (this.logger) {

package/src/agent/sub-agents.js

@@ -23,9 +23,9 @@ const { getModel } = require("../core/models");
 
 // Tool restrictions per agent type (claw-code: allowed_tools_for_subagent)
 const AGENT_TOOL_SETS = {
-  explore: ["read_file", "glob_files", "grep_code", "git_log", "git_diff", "list_dir", "check_env", "check_port", "inspect_db", "done"],
-  plan: ["read_file", "glob_files", "grep_code", "list_dir", "inspect_db", "check_env", "search_brain", "done"],
-  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "bash_exec", "move_file", "run_db_fix", "done"],
+  explore: ["read_file", "glob_files", "grep_code", "git_log", "git_diff", "list_dir", "check_env", "check_port", "inspect_db", "audit_deps", "done"],
+  plan: ["read_file", "glob_files", "grep_code", "list_dir", "inspect_db", "check_env", "audit_deps", "check_migration", "search_brain", "done"],
+  fix: ["read_file", "write_file", "edit_file", "glob_files", "grep_code", "bash_exec", "move_file", "run_db_fix", "audit_deps", "done"],
   verify: ["read_file", "glob_files", "grep_code", "bash_exec", "inspect_db", "check_port", "done"],
   research: ["read_file", "grep_code", "web_fetch", "search_brain", "done"],
   security: ["read_file", "glob_files", "grep_code", "inspect_db", "done"],

package/src/brain/brain.js

@@ -228,9 +228,13 @@ const SEED_DOCS = [
     metadata: { topic: "idempotency" },
   },
   {
-    text: "Heal pipeline no longer requires a file path. When no file is identified from the error (database errors, config problems, port conflicts), the pipeline skips fast path and goes straight to the agent, which uses investigation tools (glob_files, grep_code, list_dir, inspect_db, check_env, check_port) to find the root cause. Agent verification for no-file errors: if agent made changes or ran commands, trust the agent's assessment. For file-based errors, verification uses syntax check + boot probe as before.",
+    text: "Heal pipeline no longer requires a file path. When no file is identified from the error (database errors, config problems, port conflicts), the pipeline skips fast path and goes straight to the agent, which uses investigation tools (glob_files, grep_code, list_dir, inspect_db, check_env, check_port, audit_deps) to find the root cause. Agent verification for no-file errors: if agent made changes or ran commands, trust the agent's assessment. For file-based errors, verification uses syntax check + boot probe + route probe as before.",
     metadata: { topic: "fileless-heal" },
   },
+  {
+    text: "Dependency manager skill (src/skills/deps.js): structured npm dependency analysis + repair. diagnose(errorMessage, cwd) returns {diagnosed, category, summary, fixes} — categories: missing_install, missing_package, version_conflict, outdated_api, corrupted_modules. healthReport(cwd) returns full health check: npm audit (vulnerabilities), outdated packages, peer dep conflicts, unused packages, lock file status, health score 0-100. getMigration(packageName) returns known upgrade paths: express→fastify (5.6x faster), moment→dayjs (2KB vs 70KB), request→node-fetch (deprecated), body-parser→built-in, callbacks→async/await. Agent tools: audit_deps (full health check), check_migration (upgrade paths). Heal pipeline uses diagnose() in tryOperationalFix before AI — zero tokens for dependency issues.",
+    metadata: { topic: "skill-deps" },
+  },
 ];
 
 class Brain {

package/src/core/wolverine.js

@@ -13,6 +13,7 @@ const { ResearchAgent } = require("../agent/research-agent");
 const { GoalLoop } = require("../agent/goal-loop");
 const { exploreAndFix, spawnParallel } = require("../agent/sub-agents");
 const { EVENT_TYPES } = require("../logger/event-logger");
+const { diagnose: diagnoseDeps } = require("../skills/deps");
 
 /**
  * The Wolverine healing engine — v3.
@@ -400,33 +401,19 @@ async function tryOperationalFix(parsed, cwd, logger) {
   const { execSync } = require("child_process");
   const msg = parsed.errorMessage || "";
 
-  // Pattern 1: Cannot find module 'X' — missing npm package
-  const missingModule = msg.match(/Cannot find module '([^']+)'/);
-  if (missingModule) {
-    const moduleName = missingModule[1];
-
-    // Only npm install if it's a package name (not a relative/absolute path)
-    if (!moduleName.startsWith(".") && !moduleName.startsWith("/") && !moduleName.startsWith("\\")) {
-      // Check if it's already in package.json but not installed
-      const fs = require("fs");
-      const path = require("path");
-      const pkgPath = path.join(cwd, "package.json");
-      let isInPkg = false;
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-        isInPkg = !!allDeps[moduleName];
-      } catch {}
+  // Pattern 1: Dependency issues — use deps skill for structured diagnosis
+  const depsDiag = diagnoseDeps(msg, cwd);
+  if (depsDiag.diagnosed) {
+    console.log(chalk.blue(`  📦 Deps diagnosis: ${depsDiag.category} — ${depsDiag.summary}`));
+    if (logger) logger.info("heal.ops.deps", depsDiag.summary, { category: depsDiag.category });
 
+    for (const fix of (depsDiag.fixes || [])) {
       try {
-        const cmd = isInPkg ? "npm install" : `npm install ${moduleName}`;
-        console.log(chalk.blue(`  📦 Missing module '${moduleName}' — running: ${cmd}`));
-        if (logger) logger.info("heal.ops", `Running: ${cmd}`, { module: moduleName });
-        execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
-        return { fixed: true, action: `Installed missing module '${moduleName}' via: ${cmd}` };
+        console.log(chalk.blue(`  📦 Running: ${fix}`));
+        execSync(fix, { cwd, stdio: "pipe", timeout: 60000 });
+        return { fixed: true, action: `${depsDiag.summary}. Fixed via: ${fix}` };
       } catch (e) {
-        console.log(chalk.yellow(`  ⚠️ npm install failed: ${e.message?.slice(0, 100)}`));
-        // Fall through to AI repair
+        console.log(chalk.yellow(`  ⚠️ ${fix} failed: ${e.message?.slice(0, 80)}`));
       }
     }
   }

package/src/index.js

@@ -34,6 +34,7 @@ const { detect: detectSystem } = require("./core/system-info");
 const { ClusterManager } = require("./core/cluster-manager");
 const { loadConfig, getConfig } = require("./core/config");
 const { sqlGuard, SafeDB, scanForInjection, idempotencyGuard, idempotencyAfterHook } = require("./skills/sql");
+const { diagnose: diagnoseDeps, healthReport: depsHealthReport, getMigration } = require("./skills/deps");
 
 module.exports = {
   // Core
@@ -95,4 +96,7 @@ module.exports = {
   scanForInjection,
   idempotencyGuard,
   idempotencyAfterHook,
+  diagnoseDeps,
+  depsHealthReport,
+  getMigration,
 };

package/src/skills/deps.js

@@ -0,0 +1,449 @@
+/**
+ * Dependency Manager Skill — structured npm dependency analysis + repair.
+ *
+ * The agent often sees errors caused by dependency issues (version conflicts,
+ * missing peer deps, deprecated APIs, vulnerabilities) and wastes tokens trying
+ * to "fix" code when the real problem is in package.json or node_modules.
+ *
+ * This skill provides structured analysis BEFORE the AI runs, so the agent
+ * gets actionable context like "express@4.21 has a known vulnerability,
+ * upgrade to 4.22" instead of guessing from a stack trace.
+ *
+ * Capabilities:
+ * 1. Audit: npm audit wrapper — finds vulnerabilities with fix commands
+ * 2. Outdated: detects packages with available updates
+ * 3. Peer deps: finds missing/conflicting peer dependencies
+ * 4. Unused: detects packages in package.json not imported anywhere
+ * 5. Lock repair: detects and fixes corrupted package-lock.json
+ * 6. Version conflicts: finds packages requiring incompatible versions
+ * 7. Migration knowledge: knows common upgrade paths (express→fastify, etc.)
+ */
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const chalk = require("chalk");
+
+/**
+ * Run npm audit and return structured vulnerability data.
+ * @param {string} cwd — project root
+ * @returns {{ vulnerabilities: number, critical: number, high: number, fixes: string[] }}
+ */
+function audit(cwd) {
+  try {
+    const raw = execSync("npm audit --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw);
+    const meta = data.metadata || {};
+    const vulns = meta.vulnerabilities || {};
+    const total = (vulns.critical || 0) + (vulns.high || 0) + (vulns.moderate || 0) + (vulns.low || 0);
+
+    const fixes = [];
+    if (total > 0) {
+      try {
+        const fixOutput = execSync("npm audit fix --dry-run --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+        const fixData = JSON.parse(fixOutput);
+        if (fixData.added || fixData.updated || fixData.removed) {
+          fixes.push("npm audit fix");
+        }
+      } catch { fixes.push("npm audit fix (may require --force for breaking changes)"); }
+    }
+
+    return {
+      vulnerabilities: total,
+      critical: vulns.critical || 0,
+      high: vulns.high || 0,
+      moderate: vulns.moderate || 0,
+      low: vulns.low || 0,
+      fixes,
+    };
+  } catch (e) {
+    // npm audit exits non-zero when vulnerabilities exist
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      const vulns = (data.metadata || {}).vulnerabilities || {};
+      return {
+        vulnerabilities: (vulns.critical || 0) + (vulns.high || 0) + (vulns.moderate || 0) + (vulns.low || 0),
+        critical: vulns.critical || 0,
+        high: vulns.high || 0,
+        moderate: vulns.moderate || 0,
+        low: vulns.low || 0,
+        fixes: ["npm audit fix"],
+      };
+    } catch { return { vulnerabilities: 0, critical: 0, high: 0, moderate: 0, low: 0, fixes: [], error: e.message?.slice(0, 100) }; }
+  }
+}
+
+/**
+ * Find outdated packages.
+ * @param {string} cwd
+ * @returns {Array<{ name, current, wanted, latest, type }>}
+ */
+function outdated(cwd) {
+  try {
+    const raw = execSync("npm outdated --json 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw || "{}");
+    return Object.entries(data).map(([name, info]) => ({
+      name,
+      current: info.current,
+      wanted: info.wanted,
+      latest: info.latest,
+      type: info.type || "dependencies",
+    }));
+  } catch (e) {
+    // npm outdated exits non-zero when outdated packages exist
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      return Object.entries(data).map(([name, info]) => ({
+        name,
+        current: info.current,
+        wanted: info.wanted,
+        latest: info.latest,
+        type: info.type || "dependencies",
+      }));
+    } catch { return []; }
+  }
+}
+
+/**
+ * Find missing or conflicting peer dependencies.
+ * @param {string} cwd
+ * @returns {Array<{ package, requires, missing }>}
+ */
+function checkPeerDeps(cwd) {
+  const issues = [];
+  try {
+    const raw = execSync("npm ls --json --depth=1 2>/dev/null", { cwd, encoding: "utf-8", timeout: 30000 });
+    const data = JSON.parse(raw || "{}");
+
+    const walk = (deps, parentName = "root") => {
+      if (!deps) return;
+      for (const [name, info] of Object.entries(deps)) {
+        if (info.peerMissing) {
+          for (const peer of info.peerMissing) {
+            issues.push({ package: name, requires: peer.requires, missing: peer.requiredBy || name });
+          }
+        }
+        if (info.problems) {
+          for (const problem of info.problems) {
+            if (problem.includes("peer dep")) {
+              issues.push({ package: name, requires: problem, missing: parentName });
+            }
+          }
+        }
+        if (info.dependencies) walk(info.dependencies, name);
+      }
+    };
+    walk(data.dependencies);
+  } catch (e) {
+    try {
+      const data = JSON.parse(e.stdout || "{}");
+      if (data.problems) {
+        for (const p of data.problems) {
+          issues.push({ package: "root", requires: p, missing: "project" });
+        }
+      }
+    } catch {}
+  }
+  return issues;
+}
+
+/**
+ * Find packages in package.json that aren't imported anywhere in the project.
+ * @param {string} cwd
+ * @returns {string[]} — unused package names
+ */
+function findUnused(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) return [];
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+  const allDeps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+
+  // Scan all .js/.ts/.mjs/.cjs files for require/import statements
+  const usedPackages = new Set();
+  const scanDir = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".wolverine") continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) { scanDir(fullPath); continue; }
+      if (!/\.(js|ts|mjs|cjs|jsx|tsx)$/.test(entry.name)) continue;
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        // Match require("X") and import ... from "X"
+        const requires = content.match(/require\s*\(\s*["']([^"'./][^"']*)["']\s*\)/g) || [];
+        const imports = content.match(/from\s+["']([^"'./][^"']*)["']/g) || [];
+        for (const r of requires) {
+          const m = r.match(/["']([^"']+)["']/);
+          if (m) usedPackages.add(m[1].split("/")[0]);
+        }
+        for (const i of imports) {
+          const m = i.match(/["']([^"']+)["']/);
+          if (m) usedPackages.add(m[1].split("/")[0]);
+        }
+      } catch {}
+    }
+  };
+  scanDir(cwd);
+
+  // Filter: only report deps that are truly unused
+  // Exclude common false positives (types, plugins, bin-only packages)
+  const falsePositives = new Set(["typescript", "@types", "eslint", "prettier", "nodemon", "ts-node"]);
+  return allDeps.filter(dep => {
+    const baseName = dep.startsWith("@") ? dep : dep.split("/")[0];
+    return !usedPackages.has(baseName) && !falsePositives.has(baseName) && !baseName.startsWith("@types/");
+  });
+}
+
+/**
+ * Check if package-lock.json is healthy.
+ * @param {string} cwd
+ * @returns {{ healthy: boolean, issue?: string, fix?: string }}
+ */
+function checkLockFile(cwd) {
+  const lockPath = path.join(cwd, "package-lock.json");
+  const pkgPath = path.join(cwd, "package.json");
+
+  if (!fs.existsSync(lockPath)) {
+    return { healthy: false, issue: "No package-lock.json found", fix: "npm install" };
+  }
+
+  try {
+    const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+
+    // Check lock version
+    if (!lock.lockfileVersion || lock.lockfileVersion < 2) {
+      return { healthy: false, issue: `Outdated lockfile version ${lock.lockfileVersion || 1}`, fix: "rm package-lock.json && npm install" };
+    }
+
+    // Check if lock matches package.json
+    const pkgDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const lockDeps = lock.packages?.[""]?.dependencies || {};
+    const lockDevDeps = lock.packages?.[""]?.devDependencies || {};
+    const allLockDeps = { ...lockDeps, ...lockDevDeps };
+
+    for (const [name] of Object.entries(pkgDeps)) {
+      if (!allLockDeps[name] && !lock.dependencies?.[name]) {
+        return { healthy: false, issue: `${name} in package.json but missing from lock`, fix: "npm install" };
+      }
+    }
+
+    return { healthy: true };
+  } catch (e) {
+    return { healthy: false, issue: `Corrupted lock file: ${e.message?.slice(0, 60)}`, fix: "rm package-lock.json && npm install" };
+  }
+}
+
+/**
+ * Diagnose a dependency-related error and return structured fix recommendations.
+ * This is the main entry point — call it from the heal pipeline.
+ *
+ * @param {string} errorMessage
+ * @param {string} cwd
+ * @returns {{ diagnosed: boolean, category: string, summary: string, fixes: string[] }}
+ */
+function diagnose(errorMessage, cwd) {
+  const msg = (errorMessage || "").toLowerCase();
+
+  // Pattern: Cannot find module 'X'
+  const missingMatch = errorMessage.match(/Cannot find module '([^']+)'/);
+  if (missingMatch) {
+    const mod = missingMatch[1];
+    if (!mod.startsWith(".") && !mod.startsWith("/")) {
+      // Check if it's in package.json
+      const pkgPath = path.join(cwd, "package.json");
+      let inPkg = false;
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        inPkg = !!(pkg.dependencies?.[mod] || pkg.devDependencies?.[mod]);
+      } catch {}
+
+      if (inPkg) {
+        return {
+          diagnosed: true,
+          category: "missing_install",
+          summary: `${mod} is in package.json but not installed`,
+          fixes: ["npm install"],
+        };
+      }
+      return {
+        diagnosed: true,
+        category: "missing_package",
+        summary: `${mod} is not in package.json and not installed`,
+        fixes: [`npm install ${mod}`],
+      };
+    }
+  }
+
+  // Pattern: version/compatibility errors
+  if (/version mismatch|incompatible|peer dep|ERESOLVE/i.test(msg)) {
+    const peerIssues = checkPeerDeps(cwd);
+    return {
+      diagnosed: true,
+      category: "version_conflict",
+      summary: `Dependency version conflict (${peerIssues.length} peer dep issues)`,
+      fixes: peerIssues.length > 0
+        ? peerIssues.map(p => `npm install ${p.package}@latest`).concat(["npm install --legacy-peer-deps"])
+        : ["npm install --legacy-peer-deps", "rm -rf node_modules && npm install"],
+      details: peerIssues,
+    };
+  }
+
+  // Pattern: deprecated/removed API
+  if (/is not a function|is not a constructor|has no method|deprecated/i.test(msg)) {
+    const outdatedPkgs = outdated(cwd);
+    if (outdatedPkgs.length > 0) {
+      // Find the package mentioned in the error
+      const relevantPkgs = outdatedPkgs.filter(p =>
+        msg.includes(p.name.toLowerCase()) || errorMessage.includes(p.name)
+      );
+      if (relevantPkgs.length > 0) {
+        return {
+          diagnosed: true,
+          category: "outdated_api",
+          summary: `API may have changed in newer version of ${relevantPkgs.map(p => p.name).join(", ")}`,
+          fixes: relevantPkgs.map(p => `npm install ${p.name}@${p.latest}`),
+          details: relevantPkgs,
+        };
+      }
+    }
+  }
+
+  // Pattern: corrupted node_modules
+  if (/unexpected token|cannot find module.*node_modules|EISDIR|ENOTDIR/i.test(msg) && msg.includes("node_modules")) {
+    return {
+      diagnosed: true,
+      category: "corrupted_modules",
+      summary: "node_modules appears corrupted",
+      fixes: ["rm -rf node_modules package-lock.json && npm install"],
+    };
+  }
+
+  return { diagnosed: false };
+}
+
+/**
+ * Full dependency health report — used by dashboard and agent context.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function healthReport(cwd) {
+  const auditResult = audit(cwd);
+  const outdatedPkgs = outdated(cwd);
+  const peerIssues = checkPeerDeps(cwd);
+  const unused = findUnused(cwd);
+  const lockStatus = checkLockFile(cwd);
+
+  const score = Math.max(0, 100
+    - (auditResult.critical * 20)
+    - (auditResult.high * 10)
+    - (auditResult.moderate * 3)
+    - (peerIssues.length * 5)
+    - (lockStatus.healthy ? 0 : 15)
+    - Math.min(outdatedPkgs.length * 2, 20)
+  );
+
+  return {
+    score,
+    audit: auditResult,
+    outdated: outdatedPkgs,
+    peerDeps: peerIssues,
+    unused,
+    lockFile: lockStatus,
+    summary: score >= 80 ? "Healthy" : score >= 50 ? "Needs attention" : "Critical issues",
+  };
+}
+
+// ── Migration Knowledge ──
+
+const MIGRATION_PATTERNS = {
+  "express": {
+    to: "fastify",
+    reason: "5.6x faster routing, built-in validation, async-first",
+    patterns: [
+      { from: "app.get(path, handler)", to: "fastify.get(path, handler)" },
+      { from: "app.use(middleware)", to: "fastify.addHook('preHandler', middleware)" },
+      { from: "res.json(data)", to: "reply.send(data)" },
+      { from: "res.status(code)", to: "reply.code(code)" },
+      { from: "app.listen(port)", to: "fastify.listen({ port, host: '0.0.0.0' })" },
+    ],
+  },
+  "request": {
+    to: "node-fetch or undici",
+    reason: "request is deprecated since 2020",
+    patterns: [
+      { from: "request(url, callback)", to: "const res = await fetch(url)" },
+      { from: "request.post(url, { body })", to: "await fetch(url, { method: 'POST', body })" },
+    ],
+  },
+  "moment": {
+    to: "dayjs or date-fns",
+    reason: "moment is in maintenance mode, 70KB vs 2KB",
+    patterns: [
+      { from: "moment().format('YYYY-MM-DD')", to: "dayjs().format('YYYY-MM-DD')" },
+      { from: "moment(date).diff(other)", to: "dayjs(date).diff(other)" },
+    ],
+  },
+  "body-parser": {
+    to: "built-in (Express 4.16+ / Fastify)",
+    reason: "Included by default in modern frameworks",
+    patterns: [
+      { from: "app.use(bodyParser.json())", to: "app.use(express.json())" },
+    ],
+  },
+  "callback-style": {
+    to: "async/await with util.promisify",
+    reason: "Cleaner error handling, no callback hell",
+    patterns: [
+      { from: "fs.readFile(path, (err, data) => {})", to: "const data = await fs.promises.readFile(path)" },
+      { from: "db.query(sql, (err, rows) => {})", to: "const rows = await db.query(sql)" },
+    ],
+  },
+};
+
+/**
+ * Check if a package has a known migration path.
+ * @param {string} packageName
+ * @returns {object|null}
+ */
+function getMigration(packageName) {
+  return MIGRATION_PATTERNS[packageName] || null;
+}
+
+// ── Skill Metadata ──
+
+const SKILL_NAME = "deps";
+const SKILL_DESCRIPTION = "Dependency manager: npm audit, version conflicts, peer deps, unused packages, lock file repair, migration knowledge. Diagnoses dependency-related errors before AI runs, providing actionable fix commands instead of code edits.";
+const SKILL_KEYWORDS = ["dependency", "dependencies", "npm", "package", "install", "audit", "vulnerability", "outdated", "peer", "version", "conflict", "lock", "node_modules", "upgrade", "migrate", "deprecated"];
+const SKILL_USAGE = `// Diagnose a dependency error (returns structured fix)
+const { diagnose } = require("../src/skills/deps");
+const result = diagnose("Cannot find module 'cors'", process.cwd());
+// { diagnosed: true, category: "missing_package", fixes: ["npm install cors"] }
+
+// Full health report
+const { healthReport } = require("../src/skills/deps");
+const report = healthReport(process.cwd());
+// { score: 85, audit: {...}, outdated: [...], peerDeps: [...], unused: [...] }
+
+// Check migration paths
+const { getMigration } = require("../src/skills/deps");
+const migration = getMigration("moment");
+// { to: "dayjs", reason: "maintenance mode, 70KB vs 2KB", patterns: [...] }`;
+
+module.exports = {
+  SKILL_NAME,
+  SKILL_DESCRIPTION,
+  SKILL_KEYWORDS,
+  SKILL_USAGE,
+  audit,
+  outdated,
+  checkPeerDeps,
+  findUnused,
+  checkLockFile,
+  diagnose,
+  healthReport,
+  getMigration,
+  MIGRATION_PATTERNS,
+};