Absolute Upgrade

> Start your first response with the ⬆️ emoji.

Absolute Upgrade

Bring dependencies current — safely, in risk-ranked waves, with tests green after each.

Not a blind npm update: outdated and vulnerable deps are grouped by blast radius

(patch/minor → safe wave; major/breaking → gated, one at a time, changelog-read), applied

incrementally, and verified against the project's own test suite.

Runs the shared engine in references/health-engine.md — read it for the

DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT loop and the safety contract. This file

covers only what's specific to dependency upgrades.

When to use

• Routine "bring deps up to date" / "upgrade our dependencies".
• A specific bump: "upgrade React to 19", "move off the deprecated X package".
• Clearing npm outdated / Dependabot backlog without 40 separate PRs.

Not for: adding a *new* dependency (that's a work/feature decision), or auditing

*vulnerabilities* specifically → use /absolute audit (it triages CVEs; upgrade

moves versions).

What it scans

Per ecosystem, list outdated deps with current → wanted → latest and the jump type:

| Ecosystem | Detect outdated | Lockfile / manifest |

|---|---|---|

| npm | npm outdated --json | package-lock.json |

| pnpm | pnpm outdated --format json | pnpm-lock.yaml |

| yarn | yarn outdated --json | yarn.lock |

| Python (pip) | pip list --outdated --format=json | requirements*.txt |

| Python (poetry/uv) | poetry show --outdated / uv pip list --outdated | pyproject.toml + lock |

| Go | go list -u -m -json all | go.mod / go.sum |

Also flag: deps with known deprecations, duplicate/multiple versions of the same package,

and direct vs transitive (only direct deps are upgrade targets; transitives follow).

Risk ranking (TRIAGE)

Group the upgrade plan into waves by semver jump — safest first:

| Wave | Jump | Default |

|---|---|---|

| 1 | patch (x.y.Z) | batch together, fix now |

| 2 | minor (x.Y.z) | batch by package family, fix now |

| 3 | major (X.y.z) / pre-1.0 minor | one at a time, gated — read the changelog/migration guide first, list breaking changes |

For every major bump: locate breaking changes (CHANGELOG, release notes, codemod if the

package ships one), inventory call sites that touch the changed API, and state the

migration before applying. Peer-dependency conflicts get resolved in the same wave as

their driver.

Fix & verify

• Apply a wave, regenerate the lockfile, run the project's full test + build (a passing

install is not a passing upgrade).

• Majors: apply the version bump *and* the required code migration in the same wave, or the

build breaks. Use the package's codemod where one exists.

• A wave that can't go green within reason → revert it, report it as blocked with the error,

keep the green waves. Never --force / --legacy-peer-deps to mask a real conflict.

Gotchas

• Lockfile-only "upgrade". Bumping the manifest without regenerating + committing the

lockfile ships untested transitive versions. Always regenerate.

• Batching a major in with patches. One breaking bump fails the whole wave and hides

which change broke it. Majors are always solo.

• Green install ≠ green project. npm install succeeding proves nothing — run tests.
• Pinning around a failure. If a bump breaks something, fix or defer it; don't pin the

dependency tree to dodge it silently.

Companion commands

• /absolute audit — if the goal is fixing *vulnerabilities*, start there; it'll route

back here for the version moves.

• /absolute deflake — flaky tests can mask whether an upgrade truly passed.
• /absolute work — if an upgrade needs real feature-level migration work, hand off.