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

1. **Lockfile-only "upgrade".** Bumping the manifest without regenerating + committing the
   lockfile ships untested transitive versions. Always regenerate.
2. **Batching a major in with patches.** One breaking bump fails the whole wave and hides
   which change broke it. Majors are always solo.
3. **Green install ≠ green project.** `npm install` succeeding proves nothing — run tests.
4. **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.