agent misread a 0.0.x version as stable and auto-merged; the API changed twice that week

TL;DR: Treat 0.0.x as experimental: never automerge it, pin to the exact version, and re-check the API surface on every bump. A 0.0.x version is the author saying "this will change without warning," so the agent's job is to surface each change for review, not to merge it silently. Pin, review the diff, then bump deliberately.

agent misread a 0.0.x version as stable and auto-merged; the API changed twice that week

1. Assess the damage: diff the API surface you use against the new 0.0.x version and list what changed (renamed, removed, or reshaped exports).

Expected: a short list of concrete API changes, not a vague "it broke."

1. Pin the dependency to the exact last-known-good 0.0.x version so nothing floats further while you fix.

Expected: installs are deterministic again.

1. Fix your code against the pinned version's actual API, then bump to the newest 0.0.x deliberately and fix again if needed.

Expected: green build on a version you chose, with eyes open.

1. Change the agent's policy: 0.0.x versions never automerge; every bump requires a human review of the API diff.

Expected: future 0.0.x bumps arrive as review requests, not silent merges.

1. Set a revisit cadence (weekly or per sprint) to check the 0.0.x package deliberately, instead of letting the agent drip-feed breaking bumps.

Expected: upgrades happen on your schedule, batched and reviewed.

Use this when

• a 0.0.x dependency changed its API after an auto-merge
• the agent treats 0.0.x like any other version
• the package is brand new and churning fast
• you see breaking changes days apart from the same package

Not for this skill when

• the package is 0.x (not 0.0.x); the rules are slightly looser there (see the 0.x skill)
• the API change was actually documented and reviewed (then the process worked)
• you are the package author (then the fix is to cut a 0.1.0 or 1.0.0, not to work around it)

Variant phrasings

• "0.0.x treated as stable broke build"
• "auto-merged experimental version"
• "how to handle 0.0.x dependencies"
• "API changed twice in a week 0.0.x"
• "should I automerge 0.0.x bumps"

Why it happens

Version numbers get read left to right as "bigger is more stable," and 0.0.x looks like just another small number. In reality the second zero is doing important work: semver reserves 0.0.x for "anything goes, no compatibility implied." Agents that only check "is this a patch or minor" miss the leading zeros entirely and apply post-1.0 safety assumptions to pre-stability code.

Edge cases

• Some 0.0.x packages are stable in practice (a cautious author who never cuts 1.0); allowlist those by name, but re-verify the allowlist quarterly.
• Pinning 0.0.x exactly can block security fixes that only ship on newer 0.0.x; the revisit cadence is what keeps the pin from rotting.
• A 0.0.x dependency of a dependency (transitive) can still break you; check the tree, not just your manifest.
• If the package finally cuts 1.0.0, celebrate and move it to the normal semver policy.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_koS2zaC-b0uS9rYspk0UEg