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

Not specified by the original author.

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."

2. 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.

3. 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.

4. 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.

5. 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

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

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

TL;DR:

Not specified by the original author.

TL;DR: Detect calendar versioning before trusting the version number: if the version looks like a date (2024.10, 24.10.0), treat every bump as potentially breaking and require release-notes review before automerge. Maintain a list of known calver packages in your stack and gate the agent's automerge on it. The version number is a timestamp, not a compatibility promise.

agent auto-merged a "minor" bump that removed a deprecated endpoint  -  the package used calver and the agent treated it as semver

1. Confirm the versioning scheme: check the package's recent versions for date-shaped numbers (year.month) or a documented calver policy in its README. Expected: versions like 2024.10.0, confirming calver.

2. Revert or pin the breaking bump if the removed endpoint is still needed, and fix the call sites to the new API if you are keeping the new version. Expected: the build is green again, on the old or the new API consistently.

3. Add the package to a calver list in the agent's config and disable automerge for it (or require a release-notes check before merge). Expected: future bumps to this package stop and wait for review.

4. Teach the agent a versioning-scheme check: before auto-merging any "minor" or "patch," verify the package follows semver (or is on the known-semver list); date-shaped versions always require notes review. Expected: unknown schemes default to manual review, not automerge.

5. On the next bump of a calver package, confirm the agent posts the release notes excerpt and waits instead of merging. Expected: a human sees what changed before anything merges.

Use this when

• a minor or patch bump removed an API or changed behavior
• the package versions look like dates (2024.10, 25.1.0)
• automerge keeps landing breaking changes from "safe" bumps
• the project's docs mention calendar versioning

Not for this skill when

• the package is true semver and the break was a genuine semver violation (report it upstream; different problem)
• the break came from a 0.x package (see the 0.x skills)
• you already review every bump manually (then automerge was never the risk)

Variant phrasings

• "calver treated as semver broke automerge"
• "minor bump removed deprecated endpoint"
• "how to detect calendar versioning in dependencies"
• "auto-merged breaking change from date-versioned package"
• "package uses calver not semver"

Why it happens

Agents assume semver because most of the ecosystem uses it: minor means features, patch means fixes. Calver uses the version as a release timestamp, so "minor" and "patch" positions carry no compatibility meaning at all - a "patch" can remove an endpoint. Nothing in the version string warns you; only the shape (year.month) or the docs reveal the scheme.

Edge cases

• Some projects mix schemes (calver for the app, semver for the library); check the specific package, not the org.
• A calver package can still document breaking changes clearly in its notes; the rule is "read the notes," not "never automerge."
• Date-shaped versions with a real semver policy exist (uncommon but real); the docs are the tiebreaker, not the shape.
• Deprecated-endpoint removals are the classic calver surprise; grep the notes for "removed" and "deprecated" before approving any calver bump.

Provenance

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

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

Thread query: agent auto-merged a "minor" bump that removed a deprecated endpoint - the package used calver and the agent treated it as semver

TL;DR:

Not specified by the original author.

TL;DR

Check the actual API diff before the agent assigns a version bump. The agent looked at commit messages or at the size of the diff, not at whether public signatures changed, so removals and renames shipped as minor. Fix: diff the public API surface between releases, flag any removal, rename, or signature change as breaking, and require a major bump plus a changelog callout.

The error

docs agent failed: mislabeled breaking change as minor

Steps

1. Diff the public API between the two releases: compare exported functions, classes, parameters, and config keys. Tools like a TypeScript API extractor, cargo public-api, or a simple export list diff work. Expected: a list of removed, renamed, and signature-changed symbols.

2. Confirm the break against the published changelog: find the entry the agent wrote and its version label. Expected: you see the breaking symbol listed under a minor or patch heading.

3. Correct the record: bump to the next major version (or mark the release as breaking) and add an explicit BREAKING CHANGE section naming each removed or renamed symbol and its replacement. Expected: the changelog states plainly what breaks and how to migrate.

4. Teach the agent the rule: any removal, rename, required-parameter addition, default change, or return-type change in the public API is breaking, regardless of what the commit message says. Expected: the agent's version-labeling step consumes the API diff, not just commit text.

5. Add a CI check that fails the release when the API diff shows breaking changes but the planned bump is minor or patch. Expected: mislabeled releases are blocked before publishing.

Use this when

• users report breakage after upgrading a minor or patch release
• the changelog labels a release minor but the API surface shrank or changed
• the agent assigns version bumps from commit messages alone

Not for this skill when

• the version is right but the changelog text is vague (a writing issue)
• the break came from behavior change with identical signatures (harder; needs behavioral diffing)
• you are deciding initial 0.x versioning policy (a policy question)

Variant phrasings

• breaking change shipped as minor release
• agent labeled API removal as non-breaking
• semver mislabeled by docs agent
• changelog says minor but clients break on upgrade

Why it happens

The agent classifies by proxy signals: commit message wording, diff size, or the author's own label. None of those reliably indicate compatibility. Only the public API diff tells the truth, and the agent never computed it.

Edge cases

• Deprecations are not breaks: marking something deprecated is minor; removing it later is major.
• Config key renames and default value changes count as breaking even though no function signature changed.
• 0.x versions: breaking changes may go in minor bumps by convention, but the changelog must still call them out explicitly.

Provenance

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

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

Thread query: docs agent failed: mislabeled breaking change as minor

TL;DR: Check the actual API diff before the agent assigns a version bump. The agent looked at commit messages or at the size of the diff, not at whether public signatures changed, so removals and renames shipped as minor. Fix: diff the public API surface between releases, flag any removal, rename, or signature change as breaking, and require a major bump plus a changelog callout.