Initial commit

docs/work/epics/ci-security-and-supply-chain/04-major-bump-reevaluation/_story.md

@@ -0,0 +1,49 @@
+---
+id: 04-major-bump-reevaluation
+epic: ci-security-and-supply-chain
+title: Major-bump re-evaluation flow
+type: technical-story
+status: done
+feature: scripts
+depends-on: [01-trace-schema-extensions]
+blocks: [05-trace-revalidation-workflow]
+created: 2026-05-14T18:59:12+02:00
+updated: 2026-05-14T19:21:52.308Z
+---
+
+## Goal
+
+Extend `scripts/library-decisions/check.mjs` with a major-bump detection mode: when invoked on a Renovate PR, parse the lockfile diff to find bumped deps, classify each as major/minor/patch, and for any feature- or core-tier major bump require the trace's `lastRevalidated` field to be fresh (set today); exit non-zero with a pointer to the `evaluate-library` skill if not.
+
+## Why
+
+ADR-022 closes the adoption-time gate; ADR-023 closes the drift gate for major-version changes. A Renovate PR that bumps `@sentry/node` from `7.x → 8.x` is effectively a new adoption decision — the original trace may have evaluated a very different API surface and risk profile. Requiring a fresh `lastRevalidated` ensures the trace is re-walked before the bump merges. Minor and patch bumps don't trigger re-evaluation (backwards-compatible by semver contract).
+
+**External dependency:** library-evaluation epic story 02 (pre-commit check script) must be complete — `scripts/library-decisions/check.mjs` must exist. That epic is marked done.
+
+## Done when
+
+- `check.mjs` has a new mode (invocable as `node scripts/library-decisions/check.mjs --renovate-pr`) that:
+  - Detects Renovate PRs via `renovate/` branch prefix (from `GITHUB_HEAD_REF` or `--branch` arg).
+  - Parses the lockfile diff (from `git diff origin/main -- pnpm-lock.yaml` or a `--diff` arg) to extract bumped deps with from/to versions.
+  - Classifies each bump as major / minor / patch using semver comparison.
+  - For each feature- or core-tier major bump: reads the corresponding trace from `docs/library-decisions/`, checks `lastRevalidated` equals today's ISO date. If not fresh, exits non-zero with a message referencing the `evaluate-library` skill and the trace path.
+  - App-tier deps: pass unconditionally (ADR-022 exemption).
+  - Non-Renovate branch: pass unconditionally (the rule is scoped to Renovate PRs only).
+  - Multiple bumps in one PR: validated per-dep independently (PRD Q3).
+- Integration tests in `check.test.mjs` (or equivalent) cover: minor bump on feature-tier dep → pass; major bump + fresh `lastRevalidated` → pass; major bump + stale `lastRevalidated` → fail with clear pointer; major bump on app-tier dep → pass; patch bump in Renovate branch → pass; non-Renovate branch with major bump → pass.
+- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` all pass.
+
+## In scope
+
+- `scripts/library-decisions/check.mjs` — new `--renovate-pr` mode only; existing modes unchanged.
+- `scripts/library-decisions/check.test.mjs` — integration tests for the new mode (use fixture trace files + fixture lockfile diffs; no network calls).
+
+## Out of scope
+
+- Auto-closing `library-policy/re-evaluation` issues when `lastRevalidated` is refreshed — Story 05 (revalidation cron) handles this.
+- The CI step that invokes this check on Renovate PRs — the script is the unit; wiring it into CI workflows is part of Story 09's guide and/or the reviewer prompt in Story 08.
+
+## Tasks
+
+- [x] Extend `scripts/library-decisions/check.mjs` with a `--renovate-pr` mode: detect Renovate branch prefix, parse lockfile diff for bumped deps, classify semver deltas, require fresh `lastRevalidated` on feature/core-tier major bumps (fail with `evaluate-library` pointer if stale), pass app-tier + non-Renovate + minor/patch unconditionally; write integration tests in `check.test.mjs` with fixture trace files and lockfile diffs covering all six cases; one commit, all gates pass.