Dependency Upgrade

Trigger phrases: "upgrade dependencies", "outdated packages", "bump versions", "update packages", "keep dependencies current"

When

Staying on current versions as an ongoing practice, or reacting to a CVE. [[dependency-audit]] tells you what is wrong; this decides what to do about it and does it. It mutates the manifest and the lockfile, so it carries the same shape as [[db-migration]]: detect the tool, classify by risk, gate the dangerous class behind approval, apply, verify, roll back on red.

1 — Ask the three separate questions

They are three different problems with three different answers, and the tooling keeps them separate too.

Question	Node	.NET	Python
What has a known CVE?	npm audit --json	dotnet list package --vulnerable	pip-audit
What is deprecated?	npm view <pkg> deprecated	dotnet list package --deprecated	registry / project notes
What is simply behind?	npm outdated --json	dotnet list package --outdated	pip list --outdated

The three dotnet list package flags cannot be combined — it is three separate runs, not one.

Deprecated is not an upgrade. No version bump fixes it; the package needs a replacement, which is a design change with its own review — never fold it into a routine bump.

2 — Classify every target version before touching anything

The risk is not "how old is it", it is "how far does the jump go".

Class	Rule	Approval
Security patch	fixes a known CVE, within the current major	Do it first, on its own commit — it is the one upgrade whose delay has a cost
Patch (x.y.Z)	bugfix only	Apply, batched
Minor (x.Y.z)	additive, backward compatible by promise	Apply, batched, only if the suite is green afterwards
Major (X.y.z)	breaking by definition	Never automatic. Read the changelog/migration guide, one package per commit, and say what breaks
Pinned / transitive-only	pinned deliberately, or not a direct dependency	Leave it. Find out why it is pinned before unpinning

Semver is a promise, not a guarantee: a minor that breaks you is a bug in the package, and your suite is the only thing that will tell you. That is why the verify step below is not optional.

3 — Apply

• Group by class, one commit per group — a patch batch and a major are not the same change and must not share a commit. A single commit mixing forty bumps is unreviewable and unrevertable.
• Preview first. npm audit fix --dry-run before npm audit fix. Never reach for npm audit fix --force without saying so out loud: it installs semver-major upgrades, which is precisely how this task breaks a build while claiming to be a security fix.
• The lockfile is part of the change. Commit it with the manifest; a manifest bump without its lockfile is a change nobody else reproduces ([[dependency-audit]] axis 5).
• Never hand-edit a lockfile. Let the tool regenerate it.

4 — Verify, then decide

Nothing counts as upgraded until it is observed working — install, build, full test suite, and the project's quality gate. Run the app's real entry path if the change touches runtime, not just unit tests ([[testing]]).

• Green → keep it.
• Red → roll back this group (git checkout -- <manifest> <lockfile> then reinstall), then either pin, split the batch to find the culprit, or move that package to its own major-upgrade task. Do not "fix forward" a routine bump; that turns maintenance into an unplanned feature.
• Re-run [[dependency-audit]] afterwards: an upgrade can introduce a new transitive CVE.

5 — Continuous, without an autonomous loop

"Always current" is a cadence, not an agent that runs by itself — the kit has no timed or self-triggering loops, because every mutation here needs an approval a loop cannot give. Continuity comes from somewhere that already has a human gate at the end:

• A scheduled CI job running the step-1 commands and failing on HIGH/CRITICAL ([[ci-pipeline]]).
• Or a bot (Renovate / Dependabot) opening one PR per group — the kit does not reimplement it; the value added is the policy above deciding which PRs merge on green and which need a human to read a changelog.
• Either way the PR passes through the ordinary gates: build, tests, [[security-scan]], review, approval.

DoD

• Vulnerable, deprecated and outdated were asked as three separate questions, with the command output shown.
• Every applied upgrade is classed patch / minor / major, and no major went in automatically or unexplained.
• Security fixes landed first and separately.
• Manifest and lockfile moved together; no lockfile was hand-edited.
• Build + full suite were observed green after the change, or the group was rolled back and named.
• Deprecated packages are reported as replacement work, not silently bumped.