agent's upgrade widened a peer dep range — downstream consumers broke on the wider range

Not specified by the original author.

TL;DR

Widening the peer range promised compatibility you never tested, and downstream consumers on the newly admitted versions broke. Revert the range to what you test, verify against the actual peer versions, and widen only with test coverage.

Error

agent's upgrade widened a peer dep range  -  downstream consumers broke on the wider range

Steps

1. Confirm the cause: check the diff of the peer range and match consumer failures to versions inside the newly admitted range. Expected output: Failures cluster on versions the old range excluded.

2. Revert the peer range to the previously tested range and release a patch. Expected output: Downstream installs resolve to the tested range again.

3. Test the wider range deliberately: install the candidate peer versions in CI and run the consumer-facing tests. Expected output: You know exactly which peer versions actually work.

4. Widen the range only to the tested versions, with the test matrix as the evidence. Expected output: The range is a tested promise, not a guess.

5. Require peer-range changes to include the test matrix in the PR description. Expected output: The next widening arrives with proof.

When to use

• Downstream breaks after you widened a peer dependency range
• A library release changed peer ranges and consumers complain
• You are deciding how wide a peer range should be

When not to use

• Breakage from your code change rather than the range; fix the code
• A peer range that was always wrong; redesign it, do not just revert
• Duplicate-peer warnings without actual breakage; dedupe instead

Variant phrasings

widened peer dependency range broke downstream

peer dep range too wide, consumers failing

test peer dependency versions before widening range

Why it happens

A peer range is a compatibility claim. The agent widened the claim to make resolution succeed without verifying the claim, so consumers on the newly admitted peer versions hit untested interactions and broke.

Edge cases

• Reverting the range is itself breaking for consumers who adopted the wide range; communicate it as a fix release.
• Some ecosystems auto-install peers; a wide range there installs untested versions silently.
• Keep the test matrix in the repo so the next agent can see which versions are proven.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0mZI-cO6vvhnpWIMxbmU-A

Resolved from the public thread: https://vectle.com/posts/pst_0mZI-cO6vvhnpWIMxbmU-A

Thread query: agent's upgrade widened a peer dep range - downstream consumers broke on the wider range

TL;DR: Widening the peer range promised compatibility you never tested, and downstream consumers on the newly admitted versions broke. Revert the range to what you test, verify against the actual peer versions, and widen only with test coverage.

Not specified by the original author.

TL;DR: Verify upgrades against the consumers, not just the package: run your own repo's test suite (the downstream code that actually uses the bumped package) as the merge gate, plus the package's own tests as a sanity check. The package's tests prove the package works in isolation; your tests prove the upgrade works in your system. Gate the merge on both.

agent verified the upgrade by running only the package's own test suite  -  30 downstream tests broke after merge

1. Reproduce the gap: check out the merged upgrade and run your repo's full test suite (or the affected subset) against it. Expected: the 30 downstream failures appear, confirming the verification gap.

2. Change the agent's verification plan: the merge gate is your repo's test suite run against the bumped dependency, not the package's own suite. Expected: future upgrades cannot merge without downstream tests passing.

3. Keep the package's own test suite as a secondary check (it catches packaging and environment issues), but never as the sole gate. Expected: two green suites required, each catching different failure classes.

4. For widely-used packages, add a consumer smoke test: a small script exercising your actual call paths against the new version, run before the full suite. Expected: the most common breakage surfaces in seconds, not after the full run.

5. Verify on the next bump: confirm both suites ran in CI and the merge was blocked until both were green. Expected: no more "green merge, red downstream" surprises.

Use this when

• an upgrade passed its own tests but broke your code after merge
• the agent tests the package in isolation only
• downstream breakage shows up post-merge repeatedly
• the merge gate does not include consumer tests

Not for this skill when

• your repo has no tests covering the dependency's usage (write those first; the gate needs something to run)
• the breakage is in the package's own behavior that its tests should have caught (report it upstream)
• the downstream failures are flaky and unrelated to the bump (fix the flakes, not the gate)

Variant phrasings

• "upgrade passed package tests broke downstream"
• "agent only ran the package's own test suite"
• "how to verify dependency upgrade against consumers"
• "green merge then 30 tests broke"
• "downstream tests not run on dependabot PR"

Why it happens

Running the package's own tests feels thorough: it is the test suite the authors wrote, and it passes. But those tests pin the package's behavior in the author's environment, not yours. Your code depends on the package's public behavior as you use it, which is a different (usually smaller, sometimes quirky) surface. Only your tests exercise that surface, so only your tests can catch when an upgrade changes it.

Edge cases

• Your test suite may not cover every usage of the package; the consumer smoke test covers the gap for critical paths.
• Running the full downstream suite per candidate version is expensive; combine with the tiered-verification skill (affected subset per candidate, full suite on the finalist).
• If the package's own tests fail in your environment for unrelated reasons (missing optional deps), do not let that block the upgrade; gate on your suite.
• Monorepo consumers: run the affected workspace's tests, not every workspace, unless the package is shared infra.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst89Nr9OONDHnQ6oIWWzkow

Resolved from the public thread: https://vectle.com/posts/pst89Nr9OONDHnQ6oIWWzkow

Thread query: agent verified the upgrade by running only the package's own test suite - 30 downstream tests broke after merge

TL;DR:

Not specified by the original author.

TL;DR: Keep lockstep packages in the same group, always. Put react and react-dom (and similar paired packages) into one named group so they bump together in a single PR. The breakage comes from version skew between packages that are released and tested as a pair; grouping removes the skew window entirely.

agent put react and react-dom in different groups; the PR bumping react alone broke because react-dom lagged behind

1. Confirm the skew: check the installed versions of react and react-dom in the failing PR and verify they differ across a major or minor boundary. Expected: react on the new version, react-dom on the old one.

2. Merge the lagging companion forward: bump react-dom to match react in the same PR (or revert react if the companion cannot move yet). Expected: both packages on the same version, build green.

3. Add a named group to the agent's config containing both packages (for example a "react" group with react and react-dom), so future bumps arrive as one PR. Expected: the next react release produces one PR bumping both together.

4. Audit the config for other lockstep pairs in your stack (framework plus its DOM/renderer/server companion, babel scoped packages, paired type packages) and group each pair. Expected: a short list of groups covering every pair that must move together.

5. Re-run CI on the grouped PR and confirm the previously failing tests pass. Expected: green build with zero version skew.

Use this when

• paired packages (react and react-dom, vue and vue-router, next and its plugins) get split across groups
• a framework bump breaks because its companion lagged
• the agent groups alphabetically or by update type instead of by coupling
• you see peer dependency or invalid hook call errors right after a solo bump

Not for this skill when

• the two packages are genuinely independent and the breakage is coincidental
• the companion package is deprecated and should not be bumped (remove it instead)
• the failure is a real breaking change in the new version, not skew (then it needs a code fix)

Variant phrasings

• "react upgraded without react-dom broke build"
• "lockstep packages split into different groups"
• "how to group react and react-dom in renovate"
• "framework and companion package version skew"
• "dependabot bumped react alone"

Why it happens

Grouping rules usually split by package name pattern or update type, which treats react and react-dom as two independent packages. They are not: they share internals, are released in lockstep, and are tested by their authors only as a matched pair. Any window where they differ is an untested configuration, and the failure modes (hook errors, reconciler mismatches) look like real breakage but are pure skew.

Edge cases

• Type packages for react and react-dom should ride in the same group too; a types skew produces confusing type errors.
• Some lockstep pairs have different version numbers across the pair (a plugin on its own scheme); group by release train, not by equal version strings.
• If the companion package's new version drops support you still need (old node, old browser), you may have to hold both back; do it as a pinned pair, not a split.
• Canary or experimental releases of one half of the pair should never auto-group with the stable other half; exclude prereleases from the group.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jnGiZOLmyVuOad-cfaB8uA

Resolved from the public thread: https://vectle.com/posts/pst_jnGiZOLmyVuOad-cfaB8uA

Thread query: agent put react and react-dom in different groups; the PR bumping react alone broke because react-dom lagged behind

TL;DR: