---
id: 09-ci-security-guide-and-docs
epic: 2026-05-14-ci-security-and-supply-chain
title: CI security guide + CLAUDE.md
type: technical-story
status: in-progress
feature: docs
depends-on:
  [
    01-trace-schema-extensions,
    02-socket-integration,
    03-renovate-adoption,
    04-major-bump-reevaluation,
    05-trace-revalidation-workflow,
    06-codeql-and-audit-signatures,
    07-gitleaks-precommit,
    08-reviewer-prompt-update,
  ]
blocks: []
---

## Goal

Write `docs/guides/ci-security.md` — the human reading-room for the four-pillar stack — and add a Key Conventions bullet to `CLAUDE.md` pointing agents and developers to ADR-023 + the guide.

## Why

Each prior story lands a machine-enforced layer, but no single document explains the composed system to a developer or consumer who hasn't read all nine stories. `docs/guides/ci-security.md` fills that gap: it explains the four pillars, the failure-mode hierarchy, what settings are consumer-toggleable, and gives two worked examples so the mental model is concrete. The CLAUDE.md bullet ensures the enforcement stack is discoverable during every agent session via the startup context.

## Done when

- `docs/guides/ci-security.md` exists and covers:
  - Overview of the four pillars (Renovate + Action SHA pinning, Socket, trace revalidation, GitHub-native gates).
  - Per-pillar section with what the gate does, what it catches, and how to toggle it in a downstream consumer repo.
  - Failure-mode hierarchy table (mirroring ADR-023 §5): pillar, trigger condition, action, label, who resolves.
  - Consumer-toggleable settings list: GitHub native push protection, Socket GitHub App install, branch protection rules requiring `library-policy/*`-labeled checks before merge.
  - Two worked examples: (a) a passing Renovate minor-bump PR (gates pass, auto-merges); (b) a blocked major-bump PR (Renovate opens PR → `check.mjs` requires `lastRevalidated` refresh → agent re-walks `evaluate-library` → trace updated → PR unblocked) + a hard-divergence revalidation issue (weekly cron finds Socket-flagged dep → per-dep `library-policy/re-evaluation` issue opened → agent closes issue after re-walk).
  - Socket GitHub App install instructions for consumers.
  - `gitleaks` installation instructions for developers (OS package manager / brew; hook exits gracefully if binary absent).
  - Note that CodeQL requires GitHub Advanced Security on private repos.
- `CLAUDE.md` Key Conventions section has a bullet: _"CI security + supply-chain enforcement: Renovate for bumps + Action SHA pinning, Socket for supply-chain behavior, weekly trace revalidation, CodeQL + audit signatures + gitleaks. See ADR-023 + `docs/guides/ci-security.md`."_
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass (docs + CLAUDE.md; no executable code).

## In scope

- `docs/guides/ci-security.md` — new guide file.
- `CLAUDE.md` — one bullet addition to Key Conventions.

## Out of scope

- Configuring GitHub branch protection rules — documented as consumer action, not a tracked file change.
- Installing the Socket GitHub App — documented as consumer action in the guide; no config file change.
- Backfilling existing traces with `last-revalidated` — handled by the first revalidation cron run (Story 05).

## Tasks

- [x] Write `docs/guides/ci-security.md` with: four-pillar overview, per-pillar sections, failure-mode hierarchy table (ADR-023 §5), consumer-toggleable settings list, Socket GitHub App + gitleaks install instructions, CodeQL note for private repos, two worked examples (passing minor-bump PR; blocked major-bump PR + hard-divergence revalidation issue); one commit, all gates pass.
- [ ] Add CI security Key Conventions bullet to `CLAUDE.md` referencing ADR-023 + `docs/guides/ci-security.md`; one commit, all gates pass.