/ln-42-dependency-upgrader

name: ln-42-dependency-upgrader
description: "Upgrades dependencies in reversible batches with version-specific compatibility and regression checks."

Dependency Upgrader

**Goal:** Upgrade dependencies in small, attributable batches. Preserve manifests, lockfiles, runtime support, and product behavior; do not treat a newer version as valuable without compatibility, security, or maintenance evidence.

**Execution contract:** The checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred tool | Use it when | Fallback | |---|---|---|---| | Package-manager detection | Manifests, lockfiles, workspace files, runtime files, and repository instructions | Always before choosing commands or update scope | Build and CI configuration | | Outdated and vulnerable packages | Native package-manager outdated and audit commands | The manager and registry are available | Official registry, vendor advisory, and lockfile inspection | | Breaking changes and support | Official release notes, migration guides, changelogs, advisories, and runtime support tables | Every consequential minor, major, replacement, or security update | Primary-source repository releases; otherwise mark `UNVERIFIED` | | Usage and blast radius | Language server or host-native code intelligence | An updated API, type, plugin, build tool, or runtime may affect consumers | Targeted import, symbol, configuration, and script search | | Safe version changes | Native package-manager commands | Updating manifests and generated lock state | Do not hand-edit lockfiles or emulate package resolution | | Verification | Repository-defined install, restore, build, lint, type, test, migration, and smoke commands | Before changes and after each batch | CI and script inspection with explicit unverified status | | Diff and rollback | Git status, diff, and isolated commits or worktree | Protecting user changes and reverting only the failed batch | Stop if the batch cannot be isolated safely |

Never publish packages, rotate credentials, deploy, or weaken audit and verification gates. Do not run lifecycle scripts from an untrusted package source without the environment's normal safeguards.

Evidence Rules

• Manifests declare constraints and lockfiles record resolved versions; install metadata proves the active environment when it differs. Registry "latest" does not override runtime or compatibility constraints.
• A vulnerability finding requires the affected version, advisory, reachability or exposure context, and a credible remediation.
• A breaking-change claim requires release or migration evidence matching the exact version transition.
• Keep generated lockfile changes only when produced by the selected native package manager and expected repository version.
• Upgrade success requires repository verification, not only a successful install or restore.

Checklist

1. Discover Scope and Protect the Workspace

• [ ] Detect package managers, manifests, locks, registries, runtime/tool pins, generated state, and dependency-linked workspaces within the requested update scope; expand only for demonstrated compatibility dependencies.
• [ ] Classify each deliverable as an application, library, plugin, CLI, container, or build tool so version ranges, lockfiles, peer constraints, and supported-runtime promises are interpreted correctly.
• [ ] Read repository instructions and determine supported package-manager versions, update commands, lockfile policy, and CI expectations.
• [ ] Inspect Git state and isolate the work so existing user changes cannot be overwritten or mistaken for upgrade output.
• [ ] **Run-owned resources:** Start a run-owned resource ledger with every created absolute path, worktree, process ID, cache, report, and temporary artifact; never register pre-existing resources as cleanup targets.
• [ ] Resolve the requested scope: security-only, routine patch or minor maintenance, selected packages, majors, runtime migration, or complete refresh.
• [ ] Capture install or restore, build, lint, type, test, smoke, and security-audit baseline before editing.
• [ ] Record pre-existing failures, advisories, deprecations, peer conflicts, and unsupported runtime combinations.

2. Research and Plan Batches

• [ ] Use native outdated and audit commands to inventory direct and relevant transitive updates without changing files.
• [ ] Separate removals, security fixes, routine updates, major changes, build-tool changes, and runtime or ecosystem migrations.
• [ ] Check official release notes and migration guides for API changes, configuration changes,