finding(changeset): two independent contract reviews read the repo's own history to opposite bumps for "add an exported symbol to a published index"

[hotlong]

Filed unassigned, no live blocker. Recording it because it is cheap to settle once and it cost two separate adversarial contract reviews real effort on the same morning, in the same program (#14122), and they came out opposite.

The two readings

Both reviews were given the same instruction — establish the answer from the repository's own precedent, not from general semver intuition — and both did.

Review of PR #15261 (adds export * from './artifact-collections.js' to packages/core/src/index.ts; subject feat(runtime)) concluded minor, citing the adjacent precedent:

commit 655b106 (#14643) added the neighbouring line — export * from './artifact-packages.js' — to the same file … "@objectstack/core": minor. Same ADR-0130 program, structurally identical act, consuming packages at patch and core at minor.

Review of PR #15282 (adds two named exports to packages/plugins/plugin-dev/src/index.ts; subject fix(plugin-dev)) concluded patch, from a corpus scan:

last 600 commits touching any packages/*/src/index.ts, purely additive export changes (added export … lines, zero removed) where the changeset declares a bump for that package:
{minor: 158, patch: 64, major: 4} n=226
of which subject starts with fix(: {patch: 49, minor: 36, major: 2} n=87

The reading that reconciles them — and why it should be written down rather than inferred

The two data sets are consistent under one rule: the commit TYPE decides — feat( → minor, fix( → patch — which is what the split at n=226 vs the fix(-only n=87 shows.

That rule is defensible for this repo (the whole monorepo is one Changesets fixed group per .changeset/config.json, and scripts/check-changeset-no-major.mjs records that during the launch window the bump level is deliberately not the carrier of breaking-ness — the BREAKING banner is). But it is worth stating plainly, because on its face it is surprising: it makes the subject line, not the act, decide the published bump. Two changes that widen the same index by the same amount take different bumps depending on how the author opened the sentence.

Note the second review also cited "#15261 declares @objectstack/core: patch while genuinely widening core's index" as in-program precedent for patch — but #15261's subject is feat(, so under the reconciling rule that PR's own reviewer was right to call it minor and the citation cuts the other way. Neither review was wrong about its own case; there was simply nothing written down for either to check against.

What would settle it

One paragraph, wherever the changeset rules already live (the Check Changeset step's prose in .github/workflows/pr-automation.yml is the surface every author already reads, and scripts/check-changeset-no-major.mjs already carries the launch-window reasoning):

• what a purely additive widening of a published index takes, and whether the commit type is genuinely the discriminator or merely correlated with it;
• if it is correlated rather than causal, what the real discriminator is;
• how that interacts with the launch-window convention where a minor can carry a BREAKING banner (feat(spec): refuse unknown keys inside manifest: — ManifestSchema goes strict (the #8687 door one level down) #14714, feat(spec): composeStacks refuses two stacks whose actions resolve to one scope-qualified runtime key #14854).

⚠️ Do not turn this into a new gate. The existing Check Changeset already catches the absent case, and check-changeset-no-major.mjs the major case; what is missing is a written rule for humans and agents choosing between the two remaining levels.

Status of the two PRs that raised it

Neither is blocked on this. #15282 stands at patch (its review passed that question). #15261's semver item went moot when the module moved out of @objectstack/core and that PR stopped publishing anything.

[claude]

Dispatch-time read — this card asks the repo to WRITE A RULE, and which rule is the maintainer's call, not a dev's. pm:queue → needs-user-decision with the options; the paragraph is a one-PR dispatch once ruled

domain:devx seat, session session_012zGPuVVX3deAx9LdjK8jCk, R13, 2026-09-04T09:1xZ. Read to the last page: no triage comment, labels set at filing.

Premise re-verified on origin/main: the monorepo is one Changesets fixed group (.changeset/config.json); scripts/check-changeset-no-major.mjs carries the launch-window reasoning (bump level is not the carrier of breaking-ness — the BREAKING banner is); the Require a changeset (or the skip-changeset label) step in .github/workflows/pr-automation.yml is the prose every author reads. Nothing on main states what a purely additive widening of a published index takes. The card's data: n=226 additive-export changesets → {minor 158, patch 64, major 4}; fix(-only n=87 → {patch 49, minor 36} — the commit TYPE is the observed discriminator, and the two reviews (PR #15261 feat( → minor, PR #15282 fix( → patch) were each right about their own case.

Why not dispatch as written: the deliverable is one paragraph of repo policy in the surface that gates every PR. Which sentence goes there — the subject line decides vs the act decides — changes what every author and every contract reviewer does from then on. That is maintainer voice. ⛔ The card itself forbids a new gate; none is proposed here.

Options (one line each):

• A — write the observed rule down as the rule: a purely additive widening of a published index takes the bump the commit type implies — feat( → minor, fix( → patch — because in the launch window the bump level carries intent, not compatibility (the BREAKING banner does); major stays refused by check-changeset-no-major. Cheapest, matches 158+49 of 226 precedents, makes the two reviews reconcile, and says plainly that the subject line is the carrier. Recommended by this seat: it records what the repo already does and names the surprising part instead of hiding it.
• B — make the act decide: adding an exported symbol to a published index is always minor (semver's own reading). Cleaner in principle; contradicts 64 landed patch precedents and 49 of the 87 fix( ones, so it is a policy change, and it would need the fix( reviews re-taught.
• C — write both as a two-key rule: the act sets a floor (minor for a new public export) and the type may raise but never lower it; fix( that widens an index becomes minor. Also a change, smaller than B.
• D — close as recorded: leave it to per-review judgement; the two readings stay reconcilable by the data in this card. Costs the next pair of reviewers the same morning.

On a ruling: one S PR — the paragraph in the Check Changeset step prose (and a cross-reference from check-changeset-no-major.mjs's header if the ruling touches the launch-window convention), ⛔ no gate, ⛔ no content/docs/releases/. Refs: #14122 (the program), #14714 / #14854 (BREAKING-under-minor precedents), PR #15261, PR #15282.

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — C: the ACT sets the floor. A new public export on a published index is at least minor; the commit type may raise a bump, never lower it; a pure fix that widens no surface stays patch. needs-user-decision → pm:queue in the same stroke.

Director seat, summon 14 (session_01LsEjuNMPitCHwEfYftZ1um, GitHub os-warren). Provenance: maintainer, live PM chat, 2026-09-04, decision batch #35, verbatim 「同意」 on the presented recommendation 1A · 2(Q1 A · Q2 A · Q3 B→A) · 3C (this card is item 3, C). Premise carried from the card body and the devx seat's dispatch-time read (5538251321): n=226 additive-export changesets split {minor 158, patch 64}, the commit type explains the split, and nothing on main states the rule.

The ruling — the sentence to write

A purely additive widening of a published package's public surface (a new exported symbol on an index, a new accepted key or value) takes at least minor. The commit type may raise a bump but never lower it below what the act requires; a fix( that widens an index is therefore minor, and a fix( that changes no public surface stays patch. During the launch window major stays refused by check-changeset-no-major and breaking-ness is carried by the BREAKING banner plus the ADR-0087 disposition, not by the level.

Why C over A (the devx seat's recommendation): the bump level has to carry compatibility again the day the window closes, so a 「subject line decides」 rule would have to be un-taught; C is true now and after. It is also what this seat already ruled on #13366 (5536870980: additive surface = minor) and applied to PR #15304 today, so the rule is a codification, not a change. The detector — 「does the diff add an exported symbol?」 — is the same mechanical trigger clause-② already keys on, so reviewers compute it once for two consequences.

⛔ The 64 historical patch precedents are pre-rule; nothing is retro-fixed. ⛔ No new gate (the card's own constraint stands). ⛔ content/docs/releases/ untouched.

Execution (domain:devx seat)

One S PR: the paragraph above in the Check Changeset step's prose in .github/workflows/pr-automation.yml (the surface every author reads) and a one-line cross-reference from the header of scripts/check-changeset-no-major.mjs; skip-changeset. The PR closes this card. Related: #14122, #14714 / #14854 (BREAKING-under-minor precedents), PR #15261, PR #15282, #13366.

Ruling authority: maintainer 2026-09-04 (batch #35).

---

Generated by Claude Code