agentic-dev/docs/work/2026-05-14-ci-security-and-supply-chain/04-major-bump-reevaluation/_story.md

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

id	epic	title	type	status	feature	depends-on	blocks
04-major-bump-reevaluation	2026-05-14-ci-security-and-supply-chain	Major-bump re-evaluation flow	technical-story	done	scripts	01-trace-schema-extensions	05-trace-revalidation-workflow

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

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