---
id: 02-socket-integration
epic: ci-security-and-supply-chain
title: Socket integration (skill + CI)
type: technical-story
status: done
feature: tooling
depends-on: [01-trace-schema-extensions]
blocks: [08-reviewer-prompt-update]
created: 2026-05-14T18:59:12+02:00
updated: 2026-05-14T19:16:52.691Z
---

## Goal

Wire Socket.dev into two enforcement layers: (1) the `evaluate-library` skill gains Filter 9 (supply-chain behavior) using `socket-cli`, and (2) `ci.yml` gains a `socket-cli scan` step that fails on `critical` severity findings.

## Why

CVE databases are lagging indicators — `event-stream`, `ua-parser-js`, and `tj-actions/changed-files` all shipped malware before any CVE existed. Socket detects behavioral signals (new network calls, new post-install scripts, maintainer-account changes) in real time. Placing it as the 9th filter in `evaluate-library` + as a CI gate closes the behavior-compromise surface that CVE scanning misses.

**External dependency:** library-evaluation epic story 04 (evaluate-library skill) must be complete — the skill's SKILL.md must exist and have the 8-filter structure. That epic is marked done.

## Done when

- `.claude/skills/evaluate-library/SKILL.md` has a "Filter 9 — Supply-chain behavior (Socket)" section. The skill's fail-fast logic positions Socket as expensive (network call), running it after the cheap structural filters. The section documents the `socket-cli` verification command and the JSON output fields used to classify `clean` / `flagged` / `<finding-summary>`. The trace's `socket-risk` field in `filter-results` is set from this output.
- `.socket.json` exists at repo root: `{ "issueRules": { "critical": "error", "high": "warn", "medium": "ignore", "low": "ignore" } }`.
- `ci.yml`'s `validate` job has a step that runs `socket-cli scan` against the lockfile, filtered to PRs that touch `package.json` or `pnpm-lock.yaml` (via `paths:` condition). The step exits non-zero on any `critical` finding.
- `docs/guides/ci-security.md` Socket App install instructions are deferred to Story 09 (the human guide). This story ships only the machine-enforced layers.
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.

## In scope

- `.claude/skills/evaluate-library/SKILL.md` — Filter 9 section addition.
- `.socket.json` — repo-root config file.
- `.github/workflows/ci.yml` — one new step in the `validate` job (with `paths:` filter).

## Out of scope

- Paid Socket Team plan or server-side PR-block enforcement — explicitly out of PRD scope.
- Socket GitHub App install — consumer-facing instructions live in Story 09's guide.
- Backfilling existing traces with `socket-risk` — Story 05 (revalidation cron handles this).

## Tasks

- [x] Add `.socket.json` at repo root and extend `.claude/skills/evaluate-library/SKILL.md` with a "Filter 9 — Supply-chain behavior (Socket)" section: position Socket after cheap filters, document `socket-cli` as the verification command, specify how `clean`/`flagged`/`<finding-summary>` maps to the trace's `socket-risk` field; one commit, all gates pass.
- [x] Add a `socket-cli scan` step to `ci.yml`'s `validate` job, scoped to PRs touching `package.json` or `pnpm-lock.yaml` via a `paths:` condition; step exits non-zero on any `critical` finding; one commit, all gates pass.