## 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
```text
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