A dependency bump is a change to code you did not write, tested by gates you did not design (map: references/family-map.md — a self-contained loop) — which is why "update everything and see" ships breakage. This skill scans first (vulnerable / outdated / unused / duplicated), then upgrades in dependency-ordered waves with gates between each batch, majors strictly one at a time with their migration notes researched before the bump, not after the break.
Arguments
[mode] — light (default) | full | plan (preflight, print, STOP).
[scope] — a manifest path (one workspace) | default: every manifest family in the repo (mixed-monorepo protocol in references/stack-adapters.md).
--ask — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).
Modes
Tier vocabulary and platform mechanics: references/model-tiers.md.
| light (default) | full | |
|---|---|---|
| Scanners | clerk | worker |
| Scan depth | tool output (audit/outdated) + unused check | + duplicate/overlap analysis, license flags, install-script review |
| Migration researcher (majors) | session | session |
| Upgrade implementers | worker | worker |
| Validator per batch — one tier above | session | top |
| Majors attempted | security-driven + user-named only | every major, one at a time |
| Cycles per batch | cap 2 | cap 3 |
Mandates
- Scan before touching anything. The upgrade plan is built from the scan report, confirmed at the plan gate — never "bump and see".
- Majors are isolated. One major per batch, its changelog/migration guide read via docs lookup or web search BEFORE the bump, breaking changes listed in the batch entry. A failing major is reverted whole and recorded as a blocker — never left half-migrated.
- Gates between every batch. The full matching gates table (references/stack-adapters.md) runs after each batch, output verbatim; a red gate stops the wave until fixed or the batch is reverted.
- Lockfile changes ride along; nothing else does. Manifest + lockfile + the minimal source edits a migration requires. No opportunistic refactors.
- Unused ≠ delete on sight. An unused-dep finding carries the grep evidence (zero imports outside the manifest); removal is a batch like any other, gated.
- Install scripts and new transitive trust are findings (full): a dep whose upgrade adds install-time exec or a new git-sourced transitive is flagged before the batch runs.
- No
git add/git commit/git stash. Working tree left for review; the report tells the user to commit per-batch if they want bisectable history.
Artifacts
run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-deps-<slug>/ — fresh per run; on collision append -2, -3, ….
| File | Role |
|---|---|
plan.md |
Manifest inventory, scan summary, batch plan, tiers |
deps.md |
Full scan: D-### findings (vulnerable/outdated/unused/duplicate) with evidence |
progress.md |
Per-batch status, gate outputs, reverts, blockers |
Pipeline
Phase 0 preflight → Phase 1 scan → Phase 2 batch plan (into plan gate) → Phase 3 gated upgrade waves → Phase 4 report (STOP)
Phase 0 + 1 — Preflight and scan
Read references/preflight.md. Resolve manifests and baseline gates (run once — a red baseline is recorded; upgrades are then judged on "no NEW failures"). Scanners run the stack's native tooling (npm audit/pnpm audit, pip-audit, cargo audit, govulncheck, …) plus outdated listings and an unused check (import grep per Mandate 5). Findings → D-### in deps.md: package, current → available, severity (vulns carry their advisory ID), evidence. The plan block prints the scan summary AND the proposed batches, then applies (gate only with --ask) — the scan is cheap and read-only, so it runs before the plan; all writes come after it. A scanner or gate that cannot run at all follows the unblock protocol in references/preflight.md.
Phase 2 — Batch plan
Batches ordered: security patches (any semver distance the advisory requires) → patch/minor bulk per workspace → majors one at a time (Mandate 2), dependency-ordered when majors depend on each other (framework before its plugins). Each major batch carries its researched migration notes: breaking changes, codemods available, affected files grepped in advance.
Phase 3 — Gated upgrade waves
Per batch: implementer applies the bump + the migration edits its notes name → full matching gates (Mandate 3) → fresh validator one tier above verifies gates verbatim, greps for deprecated-API usage the changelog names, checks no NEW type escapes appeared (references/stack-adapters.md table B). Failures → fix cycle (cap per mode) or revert-whole-batch with the blocker recorded in progress.md. Never proceed past a red batch.
Phase 4 — Report (STOP)
Before/after inventory table (package · from → to · batch · status), vulnerabilities closed by advisory ID, blockers with exactly what broke (verbatim), unused deps removed, majors deferred with their migration-note paths for next time. Run stats + artifacts; calibration line appended to .nuke/calibration.log (format in references/preflight.md). Suggest per-batch commits to the user (Mandate 7). STOP.