| 1 | --- |
| 2 | name: dependency-maintenance |
| 3 | description: Dependency maintenance. Use when adding, moving, or upgrading dependencies, changing pnpm or JavaScript runtimes, updating TypeScript or build/test tools, or changing native-build policy, patches, or test images. |
| 4 | --- |
| 5 | |
| 6 | Treat an upgrade as a synchronization task, not a lockfile refresh. Derive |
| 7 | versions, commands, and compatibility points from the current repository. |
| 8 | |
| 9 | ## Discover |
| 10 | |
| 11 | 1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions, |
| 12 | workflows, test configuration, and compatibility documentation. |
| 13 | 2. Search for the dependency and every current version, range, runtime input, |
| 14 | image, engine constraint, patch, and compatibility claim. |
| 15 | 3. Record each match as a development version, tested version, peer range, |
| 16 | engine minimum, advertised minimum, or intentionally different constraint. |
| 17 | 4. When adding or moving a manifest entry, read |
| 18 | [manifest-roles.md](manifest-roles.md) before selecting its role. |
| 19 | 5. Select the package-local or coordinated branch and its validation matrix. |
| 20 | |
| 21 | Discovery is complete when every match and affected validation surface is |
| 22 | accounted for. |
| 23 | |
| 24 | ## Package-local branch |
| 25 | |
| 26 | Use this branch only for one dependency in one workspace package when runtime, |
| 27 | compiler, package-manager, image, patch, native-build, and shared-tooling policy |
| 28 | are unchanged. |
| 29 | |
| 30 | Update only the owning manifest and keep peer compatibility independent from |
| 31 | the development version tested here. If any coordinated surface appears, |
| 32 | switch branches. |
| 33 | |
| 34 | This branch is complete when the manifest and lockfile agree, focused checks |
| 35 | pass, and every search result is intentionally unchanged or package-local. |
| 36 | |
| 37 | ## Coordinated branch |
| 38 | |
| 39 | Read [coordinated-upgrades.md](coordinated-upgrades.md), select every applicable |
| 40 | row, and update all listed synchronization points before installing. Apply root |
| 41 | workflow and generated-file requirements before editing those surfaces, then |
| 42 | return here to finish matrix and lockfile review. |
| 43 | |
| 44 | ## Install and finish |
| 45 | |
| 46 | Run root `pnpm install` after all selected edits. Inspect warnings and the |
| 47 | semantic lockfile diff for specifiers, resolutions, duplicate transitives, peer |
| 48 | changes, integrity, patch hashes, lifecycle scripts, and `allowBuilds` effects. |
| 49 | A successful install alone does not complete this review. |
| 50 | |
| 51 | Run the narrowest correctness and performance checks that cover every selected |
| 52 | matrix row. |
| 53 | Apply the root changeset routing after implementation and focused validation. |
| 54 | |
| 55 | The task is complete when repeated repository searches find no unclassified |
| 56 | synchronization point, manifest roles and compatibility ranges are intentional, |
| 57 | the lockfile has no unexplained churn, and every selected check passes or is |
| 58 | reported as not runnable. |