/deps-upgrade

name: deps-upgrade
description: 'Use when dependency upgrades need batching for CVEs, a major release, forced compatibility, a scheduled or vulnerability-triggered sweep. Not for PR queue triage: use github-backlog-triage.'

Deps upgrade

Contract

| Field | Bound contract | |---|---| | Trigger | CVE remediation, major upstream release, compatibility-forced sweep, scheduled dependency hygiene, pre-release lockfile audit, or a cadence-driven or vulnerability-triggered dependency sweep. | | Authority | Reversible local: writes only manifests, lockfiles, and compatibility code in the current repository (concern-atomic local commits) plus a temporary lockfile snapshot outside the tree for the pre/post audit; rollback is version control (revert the campaign commits or reset to the recorded pre-campaign HEAD). No remote mutation. | | Side effect | Updates local manifests, lockfiles, and compatibility code; creates concern-atomic local commits. No feature work, no refactors beyond compatibility code, no silent lockfile drift. | | Done | Selected upgrades are locked, tested at the required depth, migration guidance applied for majors, license/SBOM churn checked, and the final vulnerability scan is recorded. For a sweep, each update is classified on the risk ladder and verified, or deferred with a recorded reason. |

Inputs

Must be supplied: a working repository with VCS history; toolchains for each in-scope ecosystem; and operator scope directives: which ecosystems and paths are in scope, the highest tier allowed (patch, minor, or major), and any package allowlist/blocklist. Optional: pinned target versions for specific majors, a CVE scanner choice (defaults to the ecosystem canonical scanner below), a vulnerability report or advisory feed naming affected dependencies, a cadence schedule, and freeze-window or deadline constraints that cap the tier ceiling. A major bump requires explicit human approval supplied at runtime. Before the first mutation, verify each required tool exists (`command -v`) and run the full test suite on the clean tree as the baseline; missing tools or a red baseline stop the run before anything changes.

Procedure

1. **Gate (no mutation yet)**: stop without changing anything if any holds: active feature branch with high churn; pre-release freeze window; mid-incident; the task is an API-break-driven refactor rather than a dependency upgrade. Report which gate tripped. Done when: all gates pass or the tripped gate is reported without mutation. 2. **Bound scope**: fix from the operator directives the ecosystem list, path scope, tier ceiling, and allowlist/blocklist. Never widen during the run; findings outside scope become report items, not work. Done when: all scope fields are frozen. 3. **Baseline**: record the pre-campaign HEAD sha and snapshot every lockfile to a temporary directory; this snapshot is the audit baseline and the rollback anchor. Done when: the HEAD and every lockfile snapshot are recorded. 4. **Inventory**: enumerate manifests and lockfiles across the in-scope ecosystems. Canonical names are often extensionless (`go.mod`, `Gemfile`, `pom.xml`), so filter on filenames, not extensions; `fd` takes one glob per call, so anchor on canonical filenames with one regex:

   fd -t f '^(package(-lock)?\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.(toml|lock)|pyproject\.toml|poetry\.lock|requirements.*\.txt|Pipfile\.lock|go\.(mod|sum)|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|libs\.versions\.toml|gradle\.lockfile|Gemfile(\.lock)?|.*\.gemspec|.*\.opam|dune-project|opam\.locked|mix\.(exs|lock)|composer\.(json|lock))$'

Add ecosystem-specific names the project uses beyond this list (`Pipfile`, `Brewfile`, `flake.nix`, `shard.yml`, `pubspec.yaml`). Done when: every in-scope manifest and lockfile is inventoried. 5. **Scan outdated** with the per-family commands and capture each report (read reports and later CHANGELOGs with `bat -P -p -n`, never `cat`):

| Family | Outdated scan | Upgrade command | Lockfile | |---|---|---|---| | Rust | `cargo outdated`, `cargo audit` | `cargo update`, `cargo upgrade` | `Cargo.lock` | | Python (Poetry) | `poetry show --outdated` | `poetry update`, `poetry add <pkg>@latest` | `poetry.lock` | | Python (pip-tools) | `pip list --outdated`, `pip-audit` | `pip-compile --upgrade`, `pip-sync` | `requirements.txt` | | JavaScript/TypeScript (pnpm) | `pnpm outdated`, `pnpm audit` | `pnpm update`, `pnpm up --latest` | `pnpm-lock.yaml` | | JavaScript/TypeScript (npm) | `npm outdated`, `npm audit` | `npm update`, `ncu -u` | `package-lock.json` | | Go | `go list -u -m all`, `govulncheck` | `go get -u <pkg>@latest`, `go mod tidy` | `go.sum` | | Java/Kotlin (Gradle) | `gradle dependencyUpdates` | edit `libs.versions.toml`, `gradle dependencies --refresh-dependencies` | `gradle.lockfile` | | Java/Kotlin (Maven) | `mvn versions:display-dependency-updates` | `mvn versions:use-latest-releases` | `pom.xml` | | OCaml | `opam list --upgradable` | `opam upgrade <pkg>`, `opam pin <pkg>.<ver>` | `*.opam.locked` |

A family whose scan tool is missing is excluded from scope and reported. Tooling mandates for the whole run: `fd` (not `find`), `difft` (not `diff`), `bat -P -p -n` (not `cat`), `git grep -n -F` (not plain `grep`). Done when: each included family has a captured outdated and advisory report, and exclusions are recorded. 6. **Categorize**: bin every candidate as patch, minor, or major against the tier ceiling; candidates above the ceiling are reported only. Done when: every candidate has a tier and in-scope or report-only disposition. 7. **Patch batch**: bump all patches at once; confirm the diff is lockfile-only; run the full test suite; commit everything including the lockfile diffs as `chore(deps): patch sweep`. Floating ranges that skip the lockfile commit create non-reproducible builds; the lockfile diff is always committed. Done when: the patch batch is committed with a