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