code-ai-installer 2.0.1 → 2.1.0

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: dependency-supply-chain-review
-description: Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.
+description: Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.
+last_verified: 2026-04-08
+version: 2.0
+mcp_server: socket-mcp
 ---
 
 # Skill: Dependency & Supply Chain Review
 
-Audit of npm dependencies: vulnerabilities, licenses, suspicious packages.
+Audit of npm dependencies: supply chain, vulnerabilities, licenses, suspicious packages.
+**Since v2.0** — mandatory integration with **socket.dev MCP** (`depscore`) for every new or updated package. P0 alerts block installation until explicit user confirmation.
 
 **Sections:**
+0. [Prerequisites — Socket.dev MCP](#0-prerequisites)
 1. [When to activate](#1-when-to-activate)
 2. [Audit Commands](#2-audit-commands)
 3. [Checklist](#3-checklist)
@@ -16,6 +21,70 @@ Audit of npm dependencies: vulnerabilities, licenses, suspicious packages.
 6. [Decision Framework](#6-decision-framework)
 7. [CI Integration](#7-ci-integration)
 8. [Output Template](#8-output-template)
+9. [Socket.dev Integration](#9-socket-dev)
+
+---
+
+## 0. Prerequisites — Socket.dev MCP <a id="0-prerequisites"></a>
+
+> [!IMPORTANT]
+> **Socket.dev MCP is mandatory since v2.0.** Without it, this skill operates in **degraded mode** with a notice in the report.
+
+### Why
+
+[socket.dev](https://socket.dev) provides automated supply-chain analytics for packages: detection of malware, typosquatting, suspicious maintainer changes, native binding risks. Without it, the review relies only on `npm audit`, which catches only known CVEs.
+
+### Installation (recommended — HTTP, no API key required)
+
+Add the snippet to the `mcpServers` config of your AI client (Claude Code / Codex / Qwen / Copilot / Antigravity):
+
+```json
+{
+  "mcpServers": {
+    "socket-mcp": {
+      "type": "http",
+      "url": "https://mcp.socket.dev/"
+    }
+  }
+}
+```
+
+### Alternative — stdio with API key (for teams with paid socket.dev account)
+
+```json
+{
+  "mcpServers": {
+    "socket-mcp": {
+      "command": "npx",
+      "args": ["-y", "@socketsecurity/mcp@latest"],
+      "env": {
+        "SOCKET_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+API key is available at https://socket.dev/.
+
+### Detection protocol (agent runs this before review)
+
+1. Try calling `depscore` on a known package (e.g., `lodash@4.17.21`).
+2. If the tool is available and returns a valid response → **Active mode**, proceed.
+3. If the tool is unavailable → **degraded mode**, follow the steps below.
+
+### Degraded mode protocol
+
+If `socket-mcp` is not connected:
+
+1. **Log a warning**: `[degraded] socket-mcp not detected — falling back to npm audit only`.
+2. **Offer installation**: show the user both JSON snippets (HTTP + stdio) and ask:
+   > "Socket.dev MCP is not connected. Want to install it now? (HTTP mode requires no API key). [y/n]"
+3. If **y** → instruct: "Add the snippet to the `mcpServers` config of your AI client and restart the session", then re-run detection after restart.
+4. If **n** or the tool is still unavailable after installation → continue review with `Mode: Degraded` in Output Template, fall back to `npm audit` + manual checks from section 4 (Red Flags).
+
+> [!WARNING]
+> In degraded mode, the review **does not block** merge on DEP-05a/05b/05c (socket-checks), but Reviewer must explicitly record the degraded status in the Handoff Envelope.
 
 ---
 
@@ -95,11 +164,18 @@ grep_search: Query="prebuild" SearchPath="package-lock.json"
 | # | Check | Severity | Status |
 |---|-------|----------|--------|
 | DEP-05 | `npm audit` — no high/critical vulnerabilities | 🔴 P0 | ☐ |
+| DEP-05a | socket.dev `depscore.supply_chain ≥ 0.75` for all new/updated deps | 🔴 P0 | ☐ |
+| DEP-05b | socket.dev `depscore.vulnerability ≥ 0.80` | 🔴 P0 | ☐ |
+| DEP-05c | socket.dev `depscore.license ≥ 0.50` (no copyleft contamination) | 🔴 P0 | ☐ |
+| DEP-05d | socket-mcp tool detected (not degraded mode) | 🟠 P1 | ☐ |
 | DEP-06 | `package-lock.json` committed and up to date | 🔴 P0 | ☐ |
 | DEP-07 | No `npm install` with `--force` or `--legacy-peer-deps` (unless justified) | 🟠 P1 | ☐ |
 | DEP-08 | No postinstall scripts from untrusted packages | 🔴 P0 | ☐ |
 | DEP-09 | Packages use well-known publishers (npm org verified) | 🟠 P1 | ☐ |
 
+> [!NOTE]
+> DEP-05a/05b/05c are checked automatically via socket.dev `depscore` (see section [9. Socket.dev Integration](#9-socket-dev)). In **degraded mode** these checks are marked `N/A — degraded` and do not block merge, but Reviewer must record this in the Output Template.
+
 ### 3.3 Maintenance
 
 | # | Check | Severity | Status |
@@ -262,10 +338,22 @@ dependency-review:
 **Reviewer:** Reviewer Agent
 **Total deps:** production: XX, dev: YY
 
+## Socket.dev Audit
+- **Mode:** ✅ Active / ⚠️ **Degraded** (socket-mcp not available)
+- Packages scanned: XX
+- P0 blockers: Y
+- P1 warnings: Z
+
+| Package | supply_chain | vuln | license | quality | maint | Verdict |
+|---------|--------------|------|---------|---------|-------|---------|
+| `zod@3.22.0` | 0.95 | 0.92 | 1.00 | 0.88 | 0.91 | ✅ OK |
+| `event-stream@3.3.6` | 0.10 | 0.05 | 0.85 | 0.40 | 0.20 | 🔴 P0 BLOCK |
+
 ## Audit Results
 | Check | Result |
 |-------|--------|
 | npm audit | ✅ No high/critical |
+| socket.dev depscore | ✅ All deps pass / 🔴 1 P0 blocker / ⚠️ Degraded |
 | License check | ⚠️ 1 GPL package found |
 | Unused deps | ✅ All used |
 | Outdated (major) | ⚠️ 3 packages behind |
@@ -274,7 +362,7 @@ dependency-review:
 
 | # | Severity | Package | Finding | Action |
 |---|----------|---------|---------|--------|
-| 1 | 🔴 P0 | `event-stream@3.3.6` | Known supply chain attack | Remove immediately |
+| 1 | 🔴 P0 | `event-stream@3.3.6` | socket.dev: supply_chain=0.10 (known attack) | Remove immediately |
 | 2 | 🟠 P1 | `moment@2.29.1` | 290KB, abandoned | Replace with dayjs |
 | 3 | 🟠 P1 | `some-lib@0.1.0` | GPL-3.0 license | Replace or get legal approval |
 | 4 | 🟡 P2 | `lodash@4.17.21` | Only using `debounce` | Replace with `lodash.debounce` or native |
@@ -293,8 +381,97 @@ dependency-review:
 
 ---
 
+## 9. Socket.dev Integration <a id="9-socket-dev"></a>
+
+### Tool: `depscore`
+
+`@socketsecurity/mcp` exposes **a single** tool — `depscore` — which returns five metrics per package:
+
+| Metric | Meaning |
+|--------|---------|
+| `supply_chain` | Supply-chain attack risk (typosquatting, malware, maintainer changes, scripts) |
+| `vulnerability` | Known CVEs and vulnerabilities |
+| `quality` | Code quality, tests, documentation |
+| `maintenance` | Maintainer activity, release frequency |
+| `license` | License compliance (low = copyleft / unlicensed) |
+
+All metrics are in the range `0.0–1.0`, where `1.0` is perfect.
+
+### Tool call
+
+```javascript
+depscore({
+  packages: [
+    { ecosystem: "npm", depname: "lodash", version: "4.17.21" },
+    { ecosystem: "npm", depname: "zod", version: "3.22.0" }
+  ]
+})
+```
+
+Returns lines in the format:
+```
+pkg:npm/lodash@4.17.21: supply_chain: 0.95, quality: 0.88, maintenance: 0.91, vulnerability: 0.92, license: 1.0
+pkg:npm/zod@3.22.0: supply_chain: 0.97, quality: 0.95, maintenance: 0.93, vulnerability: 0.95, license: 1.0
+```
+
+### Threshold matrix (action policy)
+
+| Metric | Range | Severity | Action |
+|--------|-------|----------|--------|
+| `supply_chain` | < 0.50 | 🔴 **P0** | **BLOCK** — escalate to user with metrics |
+| `supply_chain` | 0.50 – 0.74 | 🟠 P1 | WARN — require justification |
+| `supply_chain` | ≥ 0.75 | ✅ | OK |
+| `vulnerability` | < 0.50 | 🔴 **P0** | **BLOCK** |
+| `vulnerability` | 0.50 – 0.79 | 🟠 P1 | WARN |
+| `vulnerability` | ≥ 0.80 | ✅ | OK |
+| `license` | < 0.50 | 🔴 **P0** | **BLOCK** — likely copyleft/unlicensed |
+| `license` | ≥ 0.50 | ✅ | OK |
+| `quality` | < 0.50 | 🟡 P2 | INFO |
+| `maintenance` | < 0.50 | 🟡 P2 | INFO (abandoned) |
+
+### Workflow (agent pseudocode)
+
+```
+for each new or updated package (from package.json diff):
+  result = depscore({ packages: [{ ecosystem: "npm", depname, version }] })
+  metrics = parse(result)
+
+  if metrics.supply_chain < 0.50
+     OR metrics.vulnerability < 0.50
+     OR metrics.license < 0.50:
+    → 🔴 P0 BLOCK
+    → escalate to user: "Package X has critical socket.dev alert: <metric>=<value>. Installation blocked. Confirm explicitly to proceed."
+    → wait for confirmation
+
+  elif any metric in P1 range:
+    → 🟠 P1 WARN
+    → add to Findings with "requires justification" note
+
+  else:
+    → ✅ OK
+    → proceed
+
+record all results in Output Template → Socket.dev Audit table
+```
+
+### When to call `depscore`
+
+| Trigger | Caller |
+|---------|--------|
+| DEV: before `npm install <pkg>` | Senior Full Stack |
+| DEV: before `npm update` or major version bump | Senior Full Stack |
+| REV: when reviewing PR with `package.json` / `package-lock.json` changes | Reviewer |
+| RG: pre-release full audit of all production deps | Reviewer (on Conductor request) |
+
+### Batch optimization
+
+For large diffs (>10 packages) — batch calls into chunks of 10–20 packages per `depscore({ packages: [...] })`. Socket.dev accepts arrays; no need to call one-by-one.
+
+---
+
 ## See also
 - `$security-review` — application security review
 - `$security-baseline-dev` — secure coding patterns
 - `$cloud-infrastructure-security` — CI/CD pipeline security
-- `$tooling-bun-biome` — package manager setup
+- `$tooling-bun-biome` — package manager setup
+- [socket.dev MCP server](https://github.com/SocketDev/socket-mcp) — official repo

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/claude.json

@@ -1,13 +1,13 @@
 {
   "name": "dependency-supply-chain-review",
   "display_name": "Dependency & Supply Chain Review",
-  "description": "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.",
+  "description": "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.",
   "default_prompt": "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill.",
   "triggers": [
     "dependency-supply-chain-review",
     "dependency supply chain review",
     "Dependency & Supply Chain Review",
-    "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+    "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
   ],
   "capabilities": [
     "dependency",

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/copilot.json

@@ -1,13 +1,13 @@
 {
   "name": "dependency-supply-chain-review",
   "display_name": "Dependency & Supply Chain Review",
-  "description": "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.",
+  "description": "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.",
   "default_prompt": "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill.",
   "triggers": [
     "dependency-supply-chain-review",
     "dependency supply chain review",
     "Dependency & Supply Chain Review",
-    "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+    "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
   ],
   "capabilities": [
     "dependency",

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/gemini.json

@@ -1,13 +1,13 @@
 {
   "name": "dependency-supply-chain-review",
   "display_name": "Dependency & Supply Chain Review",
-  "description": "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.",
+  "description": "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.",
   "default_prompt": "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill.",
   "triggers": [
     "dependency-supply-chain-review",
     "dependency supply chain review",
     "Dependency & Supply Chain Review",
-    "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+    "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
   ],
   "capabilities": [
     "dependency",

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Dependency & Supply Chain Review"
-  short_description: "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe…"
+  short_description: "Dependency review with socket.dev MCP (depscore) — supply chain, vuln, licenses. P0 blocks."
   default_prompt: "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill."
 dependencies:
   tools: []

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/qwen.json

@@ -1,13 +1,13 @@
 {
   "name": "dependency-supply-chain-review",
   "display_name": "Dependency & Supply Chain Review",
-  "description": "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.",
+  "description": "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.",
   "default_prompt": "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill.",
   "triggers": [
     "dependency-supply-chain-review",
     "dependency supply chain review",
     "Dependency & Supply Chain Review",
-    "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+    "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
   ],
   "capabilities": [
     "dependency",

package/domains/development/locales/en/.agents/skills/dependency-supply-chain-review/agents/skill.yaml

@@ -1,13 +1,13 @@
 version: 1
 name: "dependency-supply-chain-review"
 display_name: "Dependency & Supply Chain Review"
-description: "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages."
+description: "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation."
 default_prompt: "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill."
 triggers:
   - "dependency-supply-chain-review"
   - "dependency supply chain review"
   - "Dependency & Supply Chain Review"
-  - "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+  - "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
 capabilities:
   - "dependency"
   - "supply"

package/domains/development/locales/en/agents/reviewer.md

@@ -21,6 +21,7 @@ Reviewer is the “quality gate” before Tester and Release Gate.
 - API Contracts + Data Model + Threat Model baseline (if available)
 - Deployment/CI Plan + Observability Plan (if relevant)
 - PR diff / file list / branch link / CI results
+- **socket-mcp tool availability** — mandatory check before reviewing `package.json` / `package-lock.json` changes. If unavailable → degraded mode (see [`$dependency-supply-chain-review`](.agents/skills/dependency-supply-chain-review/) → section 0 Prerequisites).
 
 ---
 
@@ -30,6 +31,7 @@ Reviewer is the “quality gate” before Tester and Release Gate.
 - Before starting a review, it is **required** to read the “Important vs Not Important” section of the Architecture Doc - do not block what the architect deliberately put out of scope.
 - Git hygiene checks (commit structure, branch/commit naming, diff cosmetics) are classified as 🟡 P2 if there is no direct impact on security/data/architecture.
 - Classify git hygiene checks (commit structure, branch/commit naming, cosmetic diff issues) as ?? P2 if they do not directly affect security, data, or architecture.
+- **Supply chain via socket.dev is mandatory** for any change to `package.json` / `package-lock.json`. Run `$dependency-supply-chain-review` → `depscore` for all new/updated packages. P0 alerts (`supply_chain<0.5` / `vulnerability<0.5` / `license<0.5`) = 🔴 NO-GO until explicit user confirmation or package removal. In **degraded mode** (socket-mcp unavailable) — review is allowed, but the `Degraded` status must be recorded in the Handoff Envelope.
 
 ---
 
@@ -244,10 +246,11 @@ OPEN ITEMS: [list P1/P2 for tracking]
 ## HANDOFF (Mandatory)
 MERGE STATUS: GO ✅ / NO-GO ❌
 CONTAINER RELOAD VERIFIED: ✅ / ❌
+SOCKET.DEV MODE: Active ✅ / Degraded ⚠️ / N/A (no package.json changes)
 ```
 
 ## HANDOFF (Mandatory)
 - Every REV output must end with a completed `Handoff Envelope`.
-- Required fields: `HANDOFF TO`, `ARTIFACTS PRODUCED`, `REQUIRED INPUTS FULFILLED`, `OPEN ITEMS`, `BLOCKERS FOR NEXT PHASE`, `MERGE STATUS`, `CONTAINER RELOAD VERIFIED`.
+- Required fields: `HANDOFF TO`, `ARTIFACTS PRODUCED`, `REQUIRED INPUTS FULFILLED`, `OPEN ITEMS`, `BLOCKERS FOR NEXT PHASE`, `MERGE STATUS`, `CONTAINER RELOAD VERIFIED`, `SOCKET.DEV MODE`.
 - If `OPEN ITEMS` is not empty, include owner and due date per item.
 - Missing HANDOFF block means REV phase is `BLOCKED` and cannot move to QA/RG.

package/domains/development/locales/en/agents/senior_full_stack.md

@@ -49,6 +49,7 @@ If it is explicitly stated that the project is a Wix iFrame app:
 7. **JSDoc is required** on all public functions/methods
 8. **Feedback loop** - after each slice a DEMO instruction is required
 9. **Batch tasks** - tasks are performed in batches (10–15), forming a tested vertical slice
+10. **Socket.dev pre-install gate** — before every `npm install <pkg>` / `npm update` / major version bump, mandatory call to `depscore` via socket-mcp. P0 alerts (`supply_chain<0.5` / `vulnerability<0.5` / `license<0.5`) → **hard block**: stop, escalate to user, wait for explicit confirmation. In **degraded mode** (socket-mcp unavailable) — follow the degraded protocol from [`$dependency-supply-chain-review`](.agents/skills/dependency-supply-chain-review/) → section 0.
 
 ---
 
@@ -129,6 +130,12 @@ According to Threat Model from the architect:
 - Uniform safe error format (no stack trace)
 - No secrets/PII in code and logs
 - Dependency hygiene
+- **Socket.dev pre-install check** — before every `npm install <pkg>`:
+  1. Call `depscore({ packages: [{ ecosystem: "npm", depname, version }] })` via socket-mcp
+  2. If `supply_chain < 0.5` OR `vulnerability < 0.5` OR `license < 0.5` → **STOP**, escalate to user with metrics, wait for explicit confirmation
+  3. If all metrics are OK → proceed with installation
+  4. If socket-mcp is unavailable → degraded protocol (see `$dependency-supply-chain-review` section 0)
+  5. Record metrics in DEV report for the next gate
 
 ### 6) Demo Gate
 After each `DEV-xx` provide `DEMO-xx`:
@@ -154,6 +161,7 @@ The report for the conductor contains:
 - Secrets are not in the code/logs
 - There is a DEMO instruction
 - Basic security: login validation, authorization, dependency hygiene
+- **Socket.dev depscore performed for all new/updated deps; no P0 alerts (or explicit user confirmation recorded)**
 - Production-ready: no mock functions in production scripts
 - Anti-pattern self-check: PASS
 
@@ -275,6 +283,7 @@ BLOCKERS FOR REVIEW: no / [list if available]
 ANTI-PATTERN CHECK: PASS ✅ / FAIL ❌
 JSDOC COVERAGE: X/Y
 CI STATUS: GREEN ✅ / RED ❌
+SOCKET.DEV PRE-INSTALL: Active ✅ (N packages scanned, 0 P0) / Degraded ⚠️ / N/A (no new deps)
 ```
 
 
@@ -284,5 +293,5 @@ CI STATUS: GREEN ✅ / RED ❌
 
 ## HANDOFF (Mandatory)
 - Every DEV output must end with a completed `Handoff Envelope`.
-- Required fields: `HANDOFF TO`, `ARTIFACTS PRODUCED`, `REQUIRED INPUTS FULFILLED`, `OPEN ITEMS`, `BLOCKERS FOR REVIEW`, `ANTI-PATTERN CHECK`, `JSDOC COVERAGE`, `CI STATUS`.
+- Required fields: `HANDOFF TO`, `ARTIFACTS PRODUCED`, `REQUIRED INPUTS FULFILLED`, `OPEN ITEMS`, `BLOCKERS FOR REVIEW`, `ANTI-PATTERN CHECK`, `JSDOC COVERAGE`, `CI STATUS`, `SOCKET.DEV PRE-INSTALL`.
 - If `OPEN ITEMS` is not empty, include owner and due date per item.

package/locales/en/.agents/skills/dependency-supply-chain-review/SKILL.md

@@ -1,13 +1,18 @@
 ---
 name: dependency-supply-chain-review
-description: Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.
+description: Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.
+last_verified: 2026-04-08
+version: 2.0
+mcp_server: socket-mcp
 ---
 
 # Skill: Dependency & Supply Chain Review
 
-Audit of npm dependencies: vulnerabilities, licenses, suspicious packages.
+Audit of npm dependencies: supply chain, vulnerabilities, licenses, suspicious packages.
+**Since v2.0** — mandatory integration with **socket.dev MCP** (`depscore`) for every new or updated package. P0 alerts block installation until explicit user confirmation.
 
 **Sections:**
+0. [Prerequisites — Socket.dev MCP](#0-prerequisites)
 1. [When to activate](#1-when-to-activate)
 2. [Audit Commands](#2-audit-commands)
 3. [Checklist](#3-checklist)
@@ -16,6 +21,70 @@ Audit of npm dependencies: vulnerabilities, licenses, suspicious packages.
 6. [Decision Framework](#6-decision-framework)
 7. [CI Integration](#7-ci-integration)
 8. [Output Template](#8-output-template)
+9. [Socket.dev Integration](#9-socket-dev)
+
+---
+
+## 0. Prerequisites — Socket.dev MCP <a id="0-prerequisites"></a>
+
+> [!IMPORTANT]
+> **Socket.dev MCP is mandatory since v2.0.** Without it, this skill operates in **degraded mode** with a notice in the report.
+
+### Why
+
+[socket.dev](https://socket.dev) provides automated supply-chain analytics for packages: detection of malware, typosquatting, suspicious maintainer changes, native binding risks. Without it, the review relies only on `npm audit`, which catches only known CVEs.
+
+### Installation (recommended — HTTP, no API key required)
+
+Add the snippet to the `mcpServers` config of your AI client (Claude Code / Codex / Qwen / Copilot / Antigravity):
+
+```json
+{
+  "mcpServers": {
+    "socket-mcp": {
+      "type": "http",
+      "url": "https://mcp.socket.dev/"
+    }
+  }
+}
+```
+
+### Alternative — stdio with API key (for teams with paid socket.dev account)
+
+```json
+{
+  "mcpServers": {
+    "socket-mcp": {
+      "command": "npx",
+      "args": ["-y", "@socketsecurity/mcp@latest"],
+      "env": {
+        "SOCKET_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+API key is available at https://socket.dev/.
+
+### Detection protocol (agent runs this before review)
+
+1. Try calling `depscore` on a known package (e.g., `lodash@4.17.21`).
+2. If the tool is available and returns a valid response → **Active mode**, proceed.
+3. If the tool is unavailable → **degraded mode**, follow the steps below.
+
+### Degraded mode protocol
+
+If `socket-mcp` is not connected:
+
+1. **Log a warning**: `[degraded] socket-mcp not detected — falling back to npm audit only`.
+2. **Offer installation**: show the user both JSON snippets (HTTP + stdio) and ask:
+   > "Socket.dev MCP is not connected. Want to install it now? (HTTP mode requires no API key). [y/n]"
+3. If **y** → instruct: "Add the snippet to the `mcpServers` config of your AI client and restart the session", then re-run detection after restart.
+4. If **n** or the tool is still unavailable after installation → continue review with `Mode: Degraded` in Output Template, fall back to `npm audit` + manual checks from section 4 (Red Flags).
+
+> [!WARNING]
+> In degraded mode, the review **does not block** merge on DEP-05a/05b/05c (socket-checks), but Reviewer must explicitly record the degraded status in the Handoff Envelope.
 
 ---
 
@@ -95,11 +164,18 @@ grep_search: Query="prebuild" SearchPath="package-lock.json"
 | # | Check | Severity | Status |
 |---|-------|----------|--------|
 | DEP-05 | `npm audit` — no high/critical vulnerabilities | 🔴 P0 | ☐ |
+| DEP-05a | socket.dev `depscore.supply_chain ≥ 0.75` for all new/updated deps | 🔴 P0 | ☐ |
+| DEP-05b | socket.dev `depscore.vulnerability ≥ 0.80` | 🔴 P0 | ☐ |
+| DEP-05c | socket.dev `depscore.license ≥ 0.50` (no copyleft contamination) | 🔴 P0 | ☐ |
+| DEP-05d | socket-mcp tool detected (not degraded mode) | 🟠 P1 | ☐ |
 | DEP-06 | `package-lock.json` committed and up to date | 🔴 P0 | ☐ |
 | DEP-07 | No `npm install` with `--force` or `--legacy-peer-deps` (unless justified) | 🟠 P1 | ☐ |
 | DEP-08 | No postinstall scripts from untrusted packages | 🔴 P0 | ☐ |
 | DEP-09 | Packages use well-known publishers (npm org verified) | 🟠 P1 | ☐ |
 
+> [!NOTE]
+> DEP-05a/05b/05c are checked automatically via socket.dev `depscore` (see section [9. Socket.dev Integration](#9-socket-dev)). In **degraded mode** these checks are marked `N/A — degraded` and do not block merge, but Reviewer must record this in the Output Template.
+
 ### 3.3 Maintenance
 
 | # | Check | Severity | Status |
@@ -262,10 +338,22 @@ dependency-review:
 **Reviewer:** Reviewer Agent
 **Total deps:** production: XX, dev: YY
 
+## Socket.dev Audit
+- **Mode:** ✅ Active / ⚠️ **Degraded** (socket-mcp not available)
+- Packages scanned: XX
+- P0 blockers: Y
+- P1 warnings: Z
+
+| Package | supply_chain | vuln | license | quality | maint | Verdict |
+|---------|--------------|------|---------|---------|-------|---------|
+| `zod@3.22.0` | 0.95 | 0.92 | 1.00 | 0.88 | 0.91 | ✅ OK |
+| `event-stream@3.3.6` | 0.10 | 0.05 | 0.85 | 0.40 | 0.20 | 🔴 P0 BLOCK |
+
 ## Audit Results
 | Check | Result |
 |-------|--------|
 | npm audit | ✅ No high/critical |
+| socket.dev depscore | ✅ All deps pass / 🔴 1 P0 blocker / ⚠️ Degraded |
 | License check | ⚠️ 1 GPL package found |
 | Unused deps | ✅ All used |
 | Outdated (major) | ⚠️ 3 packages behind |
@@ -274,7 +362,7 @@ dependency-review:
 
 | # | Severity | Package | Finding | Action |
 |---|----------|---------|---------|--------|
-| 1 | 🔴 P0 | `event-stream@3.3.6` | Known supply chain attack | Remove immediately |
+| 1 | 🔴 P0 | `event-stream@3.3.6` | socket.dev: supply_chain=0.10 (known attack) | Remove immediately |
 | 2 | 🟠 P1 | `moment@2.29.1` | 290KB, abandoned | Replace with dayjs |
 | 3 | 🟠 P1 | `some-lib@0.1.0` | GPL-3.0 license | Replace or get legal approval |
 | 4 | 🟡 P2 | `lodash@4.17.21` | Only using `debounce` | Replace with `lodash.debounce` or native |
@@ -293,8 +381,97 @@ dependency-review:
 
 ---
 
+## 9. Socket.dev Integration <a id="9-socket-dev"></a>
+
+### Tool: `depscore`
+
+`@socketsecurity/mcp` exposes **a single** tool — `depscore` — which returns five metrics per package:
+
+| Metric | Meaning |
+|--------|---------|
+| `supply_chain` | Supply-chain attack risk (typosquatting, malware, maintainer changes, scripts) |
+| `vulnerability` | Known CVEs and vulnerabilities |
+| `quality` | Code quality, tests, documentation |
+| `maintenance` | Maintainer activity, release frequency |
+| `license` | License compliance (low = copyleft / unlicensed) |
+
+All metrics are in the range `0.0–1.0`, where `1.0` is perfect.
+
+### Tool call
+
+```javascript
+depscore({
+  packages: [
+    { ecosystem: "npm", depname: "lodash", version: "4.17.21" },
+    { ecosystem: "npm", depname: "zod", version: "3.22.0" }
+  ]
+})
+```
+
+Returns lines in the format:
+```
+pkg:npm/lodash@4.17.21: supply_chain: 0.95, quality: 0.88, maintenance: 0.91, vulnerability: 0.92, license: 1.0
+pkg:npm/zod@3.22.0: supply_chain: 0.97, quality: 0.95, maintenance: 0.93, vulnerability: 0.95, license: 1.0
+```
+
+### Threshold matrix (action policy)
+
+| Metric | Range | Severity | Action |
+|--------|-------|----------|--------|
+| `supply_chain` | < 0.50 | 🔴 **P0** | **BLOCK** — escalate to user with metrics |
+| `supply_chain` | 0.50 – 0.74 | 🟠 P1 | WARN — require justification |
+| `supply_chain` | ≥ 0.75 | ✅ | OK |
+| `vulnerability` | < 0.50 | 🔴 **P0** | **BLOCK** |
+| `vulnerability` | 0.50 – 0.79 | 🟠 P1 | WARN |
+| `vulnerability` | ≥ 0.80 | ✅ | OK |
+| `license` | < 0.50 | 🔴 **P0** | **BLOCK** — likely copyleft/unlicensed |
+| `license` | ≥ 0.50 | ✅ | OK |
+| `quality` | < 0.50 | 🟡 P2 | INFO |
+| `maintenance` | < 0.50 | 🟡 P2 | INFO (abandoned) |
+
+### Workflow (agent pseudocode)
+
+```
+for each new or updated package (from package.json diff):
+  result = depscore({ packages: [{ ecosystem: "npm", depname, version }] })
+  metrics = parse(result)
+
+  if metrics.supply_chain < 0.50
+     OR metrics.vulnerability < 0.50
+     OR metrics.license < 0.50:
+    → 🔴 P0 BLOCK
+    → escalate to user: "Package X has critical socket.dev alert: <metric>=<value>. Installation blocked. Confirm explicitly to proceed."
+    → wait for confirmation
+
+  elif any metric in P1 range:
+    → 🟠 P1 WARN
+    → add to Findings with "requires justification" note
+
+  else:
+    → ✅ OK
+    → proceed
+
+record all results in Output Template → Socket.dev Audit table
+```
+
+### When to call `depscore`
+
+| Trigger | Caller |
+|---------|--------|
+| DEV: before `npm install <pkg>` | Senior Full Stack |
+| DEV: before `npm update` or major version bump | Senior Full Stack |
+| REV: when reviewing PR with `package.json` / `package-lock.json` changes | Reviewer |
+| RG: pre-release full audit of all production deps | Reviewer (on Conductor request) |
+
+### Batch optimization
+
+For large diffs (>10 packages) — batch calls into chunks of 10–20 packages per `depscore({ packages: [...] })`. Socket.dev accepts arrays; no need to call one-by-one.
+
+---
+
 ## See also
 - `$security-review` — application security review
 - `$security-baseline-dev` — secure coding patterns
 - `$cloud-infrastructure-security` — CI/CD pipeline security
-- `$tooling-bun-biome` — package manager setup
+- `$tooling-bun-biome` — package manager setup
+- [socket.dev MCP server](https://github.com/SocketDev/socket-mcp) — official repo

package/locales/en/.agents/skills/dependency-supply-chain-review/agents/claude.json

@@ -1,13 +1,13 @@
 {
   "name": "dependency-supply-chain-review",
   "display_name": "Dependency & Supply Chain Review",
-  "description": "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages.",
+  "description": "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation.",
   "default_prompt": "Use $dependency-supply-chain-review when the task matches the \"Dependency & Supply Chain Review\" skill.",
   "triggers": [
     "dependency-supply-chain-review",
     "dependency supply chain review",
     "Dependency & Supply Chain Review",
-    "Dependency review — minimization, updates, vulnerability audit, licenses, prohibition of unsafe packages"
+    "Dependency review with mandatory socket.dev MCP check (depscore) — supply chain, vulnerability, licenses. P0 alerts block installation"
   ],
   "capabilities": [
     "dependency",