docs: introduce CI security + supply-chain stack (ADR-023 + PRD)

- ADR-023 codifies the four-pillar enforcement stack: Renovate for
  bumps + Action SHA pinning via pinGitHubActionDigests, Socket.dev
  as a 9th hard filter in evaluate-library (free App + self-hosted
  socket-cli + reviewer-prompt enforcement), weekly trace
  revalidation cron with two-tier divergence action (rolling
  dashboard issue + per-dep re-evaluation issues), and the baseline
  GitHub-native gates (CodeQL, pnpm audit signatures, gitleaks
  pre-commit + native push protection). Failure-mode hierarchy is
  the single source of truth referenced by the sandcastle reviewer.
- Section 6 amends ADR-022 in place: major-bump re-evaluation
  trigger (minor/patch bumps skip), last-revalidated frontmatter
  field (preserves original date for adoption provenance), and
  Socket as the 9th hard filter. ADR-022 stays unedited; both ADRs
  read as a composed policy.
- PRD at docs/work/prds/2026-05-14-ci-security-and-supply-chain.prd.md
  seeds the implementation epic; explicit sequencing -- depends on
  the in-flight library-evaluation epic's stories 01/02/04/06
  landing first.
- Glossary gains "Trace revalidation" + "Major-bump re-evaluation"
  entries referenced by both ADRs.

Catalyst: 2026-05-14 audit confirmed zero security tooling in the
repo + GitHub Actions pinned to major-version tags (the tj-actions/
changed-files attack class). ADR-022 closes the adoption-time gate;
ADR-023 closes the post-adoption drift gate.
This commit is contained in:
2026-05-14 18:47:25 +02:00
parent bb9983f10b
commit 90341ff475
4 changed files with 892 additions and 1 deletions

View File

@@ -302,6 +302,12 @@ A per-decision artifact at `docs/library-decisions/<YYYY-MM-DD>-<package-name>.m
**Pre-shipped trace**:
A library trace emitted by `pnpm turbo gen core-package <name>` for each direct runtime dep of a pre-curated optional core. Pre-approved by the template's ADRs (015 events / 016 realtime / 018 audit). Generated alongside the core's frozen snapshot so optional cores satisfy the library-evaluation policy by default.
**Trace revalidation**:
The weekly + on-demand CI job (`.github/workflows/trace-revalidation-weekly.yml`) that re-runs every approved trace's `verification-commands` block and detects drift in license / maintenance / CVE / EU-residency / Socket-risk signals that don't show up as version bumps. Two-tier divergence action: **soft divergence** appends to a rolling dashboard issue; **hard divergence** (license changed, named-consumer gone, critical CVE disclosed, EU residency flipped, Socket-flagged) opens a per-dep issue labeled `library-policy/re-evaluation` for the dispatch loop to pick up. Never auto-edits the trace — the re-walk needs the `evaluate-library` skill, not a mechanical edit. Records the most-recent successful pass in the trace's `last-revalidated` frontmatter field (separate from the original adoption `date`).
**Major-bump re-evaluation**:
The Renovate-triggered re-walk of `evaluate-library` when a runtime dep's major version bumps (semver-major, distinct from minor/patch). Updates the existing trace in-place (refreshes `version`, `filter-results`, `verification-commands`, `last-revalidated`), preserves the original `date`. Catches license / maintenance / transitive-surface changes that semver-encodes as "breaking." Minor + patch bumps do not trigger re-evaluation.
## Modes
**Production mode**: