Initial commit

docs/work/epics/ci-security-and-supply-chain/02-socket-integration/_story.md

@@ -0,0 +1,47 @@
+---
+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:21:52.308Z
+---
+
+## 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.