# Pathrule Pattern: Dependency Upgrades and Breaking Changes (1.0.0) # ::pathrule:package:dependency-upgrades ### [RULE] Upgrade from official migration evidence (path: /) A version range communicates compatibility claims, but only upstream release evidence explains removed APIs, changed defaults, required codemods, runtime support, and data migration. - Record current and target versions, every crossed major, runtime and toolchain requirements, and the official source for each behavior-sensitive change. - List removed, renamed, defaulted, generated, serialized, and configuration surfaces used by this repository before installing the target. - Avoid mixing unrelated package upgrades unless their compatibility matrix requires them to move together. - 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. See /src for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Treat codemods and generated changes as proposals (path: /src) Codemods recognize syntax, not product intent. They can preserve compilation while changing evaluation order, lifecycle, error behavior, or configuration ownership. - Run the upstream-recommended codemod on a clean, committed baseline and isolate its diff from manual compatibility edits. - Inspect every transformed pattern that affects state, concurrency, rendering, authorization, persistence, or public API behavior. - Regenerate lockfiles, clients, schemas, snapshots, bundles, and code from the repository's pinned tool versions rather than editing derived output. - Delete temporary compatibility shims only after all supported callers and environments have moved; do not hide them inside unrelated cleanup. See /tests/compatibility for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] Upgrade order follows the compatibility graph (path: /) 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. - Map direct dependencies, peers, plugins, adapters, generated artifacts, runtime, compiler, and package-manager constraints involved in the target. - Choose small intermediate targets where official migration guides or compatibility ranges make each step verifiable. - Use temporary branches or commits for mechanical steps but keep the final review history understandable and bisectable. - Resolve peer conflicts through supported version alignment or replacement, not blanket force or legacy resolution flags. See /src for the rule or workflow that puts this decision into practice. --- ### [MEMORY] The lockfile is a toolchain-owned release artifact (path: /) 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. - Declare package manager and version in repository tooling and use the same environment locally and in CI. - Change manifests first, regenerate once, and review direct target movement, unexpected transitive changes, integrity, platform variants, and removed packages. - Do not hand-edit lockfile entries or copy one from another branch without reproducing the manifest and toolchain state. - Run install from a clean cache and immutable or frozen mode in CI to prove the committed graph is sufficient. See /tests/compatibility for the rule or workflow that puts this decision into practice. --- ### [SKILL] plan-breaking-dependency-upgrade (path: /) --- name: plan-breaking-dependency-upgrade description: Plan a dependency upgrade that crosses a major, runtime, compiler, framework, or persistent-data boundary. --- # Plan Breaking Dependency Upgrade 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. 1. Record current and target versions, official migration sources, supported runtimes, peers, plugins, adapters, code generators, and consumers. 2. Search repository usage of removed APIs, changed defaults, configuration keys, serialized formats, generated output, and runtime assumptions. 3. Split the upgrade into mechanical, compatibility, behavior, data, and cleanup steps with a buildable and testable checkpoint after each. 4. Define representative tests, canary or staged rollout, observability, rollback compatibility, and the latest point where data changes remain reversible. 5. List deliberately deferred deprecations and shims with owners and removal conditions so the upgrade does not silently create permanent dual behavior. ## Exit criteria 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. --- ### [SKILL] verify-dependency-upgrade (path: /) --- name: verify-dependency-upgrade description: Verify a dependency upgrade before release. --- # Verify Dependency Upgrade 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. 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. 2. Compare generated code, bundles, manifests, schemas, lockfile, tree shaking, warnings, and startup output against the approved baseline. 3. Exercise changed defaults and APIs with focused tests that fail on the old assumption rather than relying only on broad suites. 4. Deploy a bounded target and watch errors, latency, memory, CPU, dependency calls, data changes, and client compatibility under representative load. 5. Execute rollback or a forward-fix rehearsal against any migrated state and preserve official sources and verification evidence with the upgrade. ## Exit criteria 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.