agentic-dev/docs/work/2026-05-14-ci-security-and-supply-chain/09-ci-security-guide-and-docs/_story.md

id, epic, title, type, status, feature, depends-on, blocks

id	epic	title	type	status	feature	depends-on	blocks
09-ci-security-guide-and-docs	2026-05-14-ci-security-and-supply-chain	CI security guide + CLAUDE.md	technical-story	in-progress	docs	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

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

• 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.