Dependency Upgrades and Breaking Changes
Pathrule2 Rules • 2 Memories • 2 Skills
Dependency upgrades can change runtime defaults, generated output, transitive packages, peer ranges, configuration, build tools, data formats, and platform requirements even when the public application code still compiles. This pattern constrains evidence and release scope, records upgrade ordering and lockfile ownership, and supplies separate planning and verification procedures for routine and breaking changes. It complements supply-chain security and technical debt by focusing on compatibility migration and controlled adoption rather than vulnerability provenance or backlog prioritization.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
Upgrade from official migration evidence
Upgrade order follows the compatibility graph
The lockfile is a toolchain-owned release artifact
plan-breaking-dependency-upgrade
verify-dependency-upgrade
src/
Treat codemods and generated changes as proposals
Rules
2Upgrade from official migration evidence/roothighstrictRead release notes, migration guides, deprecations, peer ranges, and platform requirements for every crossed release before editing code.
| 1 | A version range communicates compatibility claims, but only upstream release evidence explains removed APIs, changed defaults, required codemods, runtime support, and data migration. |
| 2 | |
| 3 | - Record current and target versions, every crossed major, runtime and toolchain requirements, and the official source for each behavior-sensitive change. |
| 4 | - List removed, renamed, defaulted, generated, serialized, and configuration surfaces used by this repository before installing the target. |
| 5 | - Avoid mixing unrelated package upgrades unless their compatibility matrix requires them to move together. |
| 6 | - Drop an uncertain claim or test it directly; do not infer migration behavior from a third-party snippet when official guidance or source is available. |
| 7 | |
| 8 | See /src for the adjacent decision or procedure that completes this constraint. |
Treat codemods and generated changes as proposals/srchighstrictReview semantic output, rerun generation from pinned tools, and preserve application-specific behavior the mechanical rewrite cannot know.
| 1 | Codemods recognize syntax, not product intent. They can preserve compilation while changing evaluation order, lifecycle, error behavior, or configuration ownership. |
| 2 | |
| 3 | - Run the upstream-recommended codemod on a clean, committed baseline and isolate its diff from manual compatibility edits. |
| 4 | - Inspect every transformed pattern that affects state, concurrency, rendering, authorization, persistence, or public API behavior. |
| 5 | - Regenerate lockfiles, clients, schemas, snapshots, bundles, and code from the repository's pinned tool versions rather than editing derived output. |
| 6 | - Delete temporary compatibility shims only after all supported callers and environments have moved; do not hide them inside unrelated cleanup. |
| 7 | |
| 8 | See /tests/compatibility for the adjacent decision or procedure that completes this constraint. |
Memories
2Upgrade order follows the compatibility graph/rootMove runtime, package manager, framework, plugins, generators, and application code in an order each intermediate state can build and test.
| 1 | Several packages may require overlapping peer ranges or a new runtime. Updating the leaf first or suppressing resolution errors can create a dependency set no maintainer supports. |
| 2 | |
| 3 | - Map direct dependencies, peers, plugins, adapters, generated artifacts, runtime, compiler, and package-manager constraints involved in the target. |
| 4 | - Choose small intermediate targets where official migration guides or compatibility ranges make each step verifiable. |
| 5 | - Use temporary branches or commits for mechanical steps but keep the final review history understandable and bisectable. |
| 6 | - Resolve peer conflicts through supported version alignment or replacement, not blanket force or legacy resolution flags. |
| 7 | |
| 8 | See /src for the rule or workflow that puts this decision into practice. |
The lockfile is a toolchain-owned release artifact/rootRegenerate it with the declared package manager and version, and review transitive movement separately from manifest intent.
| 1 | A lockfile can change broadly when the package-manager version or resolution algorithm changes. Without a pinned toolchain, reviewers cannot distinguish intended upgrades from incidental graph churn. |
| 2 | |
| 3 | - Declare package manager and version in repository tooling and use the same environment locally and in CI. |
| 4 | - Change manifests first, regenerate once, and review direct target movement, unexpected transitive changes, integrity, platform variants, and removed packages. |
| 5 | - Do not hand-edit lockfile entries or copy one from another branch without reproducing the manifest and toolchain state. |
| 6 | - Run install from a clean cache and immutable or frozen mode in CI to prove the committed graph is sufficient. |
| 7 | |
| 8 | See /tests/compatibility for the rule or workflow that puts this decision into practice. |
Skills
2plan-breaking-dependency-upgrade/rootInventory affected contracts, choose an upgrade path, isolate risk, and define evidence and rollback before changing versions.
| 1 | --- |
| 2 | name: plan-breaking-dependency-upgrade |
| 3 | description: Plan a dependency upgrade that crosses a major, runtime, compiler, framework, or persistent-data boundary. |
| 4 | --- |
| 5 | |
| 6 | # Plan Breaking Dependency Upgrade |
| 7 | |
| 8 | Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. |
| 9 | |
| 10 | 1. Record current and target versions, official migration sources, supported runtimes, peers, plugins, adapters, code generators, and consumers. |
| 11 | 2. Search repository usage of removed APIs, changed defaults, configuration keys, serialized formats, generated output, and runtime assumptions. |
| 12 | 3. Split the upgrade into mechanical, compatibility, behavior, data, and cleanup steps with a buildable and testable checkpoint after each. |
| 13 | 4. Define representative tests, canary or staged rollout, observability, rollback compatibility, and the latest point where data changes remain reversible. |
| 14 | 5. List deliberately deferred deprecations and shims with owners and removal conditions so the upgrade does not silently create permanent dual behavior. |
| 15 | |
| 16 | ## Exit criteria |
| 17 | |
| 18 | The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks. |
verify-dependency-upgrade/rootProve install, build, generated output, behavior, data, performance, packaging, rollout, and rollback on the target dependency graph.
| 1 | --- |
| 2 | name: verify-dependency-upgrade |
| 3 | description: Verify a dependency upgrade before release. |
| 4 | --- |
| 5 | |
| 6 | # Verify Dependency Upgrade |
| 7 | |
| 8 | Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. |
| 9 | |
| 10 | 1. Install from a clean cache with the pinned toolchain and run type checks, static analysis, unit, integration, contract, end-to-end, packaging, and clean-install tests. |
| 11 | 2. Compare generated code, bundles, manifests, schemas, lockfile, tree shaking, warnings, and startup output against the approved baseline. |
| 12 | 3. Exercise changed defaults and APIs with focused tests that fail on the old assumption rather than relying only on broad suites. |
| 13 | 4. Deploy a bounded target and watch errors, latency, memory, CPU, dependency calls, data changes, and client compatibility under representative load. |
| 14 | 5. Execute rollback or a forward-fix rehearsal against any migrated state and preserve official sources and verification evidence with the upgrade. |
| 15 | |
| 16 | ## Exit criteria |
| 17 | |
| 18 | The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks. |
Why this pattern
AI agents often jump several majors, run a codemod without reviewing semantics, regenerate a lockfile with a different toolchain, or suppress peer conflicts instead of resolving compatibility.
Built for Engineering teams upgrading application, framework, compiler, runtime, build, or infrastructure dependencies.
Keeps your assistant from:
- Mixing several breaking migrations into one unreviewable change
- Accepting codemod output that changes behavior silently
- Shipping a lockfile generated by an unsupported package-manager version
- Discovering a removed runtime default only after deployment
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-08-25