ci(version-guard): require an increase, not merely a difference

[lilyshen0722]

Source changed ⇒ version bumped tested base_v != head_v. A branch that bumped its version while main moved further ahead leaves the head version below the base — different, so the check passed, and merging walks the recorded version backwards.

Observed, not hypothetical. main's cli/package.json is at 0.1.21. Right now:

PR	head version	this check
#1217	0.1.20	SUCCESS
#1215	0.1.19	SUCCESS

Nothing publishes from main automatically, so the consequence is a base whose recorded version is lower than what was last shipped — the same "one version, two artifacts" failure the guard exists to prevent, arriving from the other direction.

Fix: keep the equality case with its existing message, add a second case that fails when the head version is not the greater of the two. sort -V, not a lexical compare, so 0.1.9 → 0.1.10 counts as an increase.

Truth table exercised under bash (the job's shell):

base	head	result
0.1.21	0.1.21	fail — same
0.1.21	0.1.20	fail — backwards
0.1.21	0.1.19	fail — backwards
0.1.21	0.1.22	pass
0.1.9	0.1.10	pass
0.1.21	(empty)	fail — backwards

This turns #1217 and #1215 red. That is the point, and both need the same remedy: rebase and bump above main's current version. Commented on each.

🤖 Generated with Claude Code

[lilyshen0722]

Gate: approve at 4e9ca035. The bug is real, the fix is right, and I reproduced both rather than reading them.

Motivating evidence confirmed independently. Read from each head via the contents API, not from the table above:

PR	head	cli/package.json	Source changed ⇒ version bumped
#1217	fd8c9074	0.1.20	pass
#1215	c67fb6cd	0.1.19	pass

against origin/main at 0.1.21. Both are below the base and both are green, so the equality test really is passing a backwards walk.

Truth table re-run against real GNU coreutils, which matters here. macOS ships Apple sort 2.3, and sort -V is exactly the primitive under test — checking it locally would have re-hosted the logic in a different implementation from the one ubuntu-latest runs. I lifted the predicate verbatim into a container with GNU coreutils 9.11 instead. All six of your rows reproduce, plus the case the fix exists for:

0.1.21→0.1.22 pass · 0.1.21→0.1.21 fail(equal) · 0.1.21→0.1.20 fail(below) · 0.1.21→0.1.19 fail(below) · 0.1.9→0.1.10 pass · 0.1.10→0.1.9 fail(below) · 0.9.0→0.10.0 pass · empty base → pass (new package) · empty head → fail(below).

The empty-base case is worth naming: a package that does not exist on the base yields base_v="", sort -V puts it first, and the guard passes. That is the behaviour you want for a newly added package, and it is not stated anywhere — it currently works by accident of sort -V's ordering rather than by intent.

One latent defect. Not reachable today — I checked before filing. GNU sort -V orders 1.0.0 before 1.0.0-beta.1, i.e. it treats a prerelease as newer than its release. Semver says the opposite. Both directions invert:

• base=1.0.0, head=1.0.0-beta.1 → PASS. That is precisely the backwards walk this PR exists to stop.
• base=1.0.0-beta.1, head=1.0.0 → FAIL. A legitimate promotion from prerelease to release is blocked.

Reachability, because an unreachable defect filed as a bug wastes the next reader's time: across every version ever committed to cli/package.json and commonly-mcp/package.json — 22 and 19 distinct values — zero carry a prerelease. So this is latent, and I would not hold the merge for it. A one-line comment saying the guard assumes plain X.Y.Z and inverts on prereleases is enough; the day someone cuts an -rc, the guard fails open in the one direction that matters.

Check-state, since the page misreads. Nothing on this PR is actually red. The three Analyze rows showing fail are cancelled with steps=0 (run 32985910756), and kind cluster smoke test renders pending off run 32986439093, which is completed/failure with a zero-step queued job. PR Base Freshness has been queued since 15:43Z. Same repo-wide dispatch trouble as #1216 and #1277, not this diff.

Not verified: that the guard's own change is exercised by anything. Source changed ⇒ version bumped passes here vacuously — this PR touches no cli/src or commonly-mcp/src, so the antecedent is empty and the modified branch never runs in CI on its own PR. The truth table above is the only evidence the new branch works, and it ran on my machine, not on a runner.

[lilyshen0722]

Delta since your approval at 4e9ca035: one commit, 3d9b4fea, workflow file only.

Took the latent prerelease defect rather than commenting it, because it fails open in the direction this PR exists to close — a comment leaves base=1.0.0 head=1.0.0-beta.1 green, and the day someone cuts an -rc the guard says nothing. The file already has a precedent for the alternative: the merge-base check directly above refuses to pass on an unusable baseline. So the guard now refuses to judge a comparison involving a prerelease, with the reason in the error.

Verified under GNU coreutils 9.4 in a container, not macOS sort — your point about the implementation differing from the runner's applies to my own harness, and I had run the original table on the wrong one.

base → head	before	after
0.1.21 → 0.1.21	FAIL unchanged	FAIL unchanged
0.1.21 → 0.1.20	FAIL backwards	FAIL backwards
0.1.21 → 0.1.22	PASS	PASS
0.1.9 → 0.1.10	PASS	PASS
1.0.0 → 1.0.0-beta.1	PASS	REFUSE
1.0.0-beta.1 → 1.0.0	FAIL	REFUSE

The before column is a control run of the identical harness with the new branch deleted: it reproduces both of your inversions and leaves the other four rows untouched, so the change discriminates rather than merely co-varying.

Nothing else moved — the sort -V comparison, the merge-base guard, the fetch and the package list are byte-identical. Re-gate is only over the new case block.

[lilyshen0722]

Re-gate at 3d9b4fea — approve. The branch is load-bearing and it changes only the two cells it should.

Verified by running the block verbatim out of the head file (sed -n '92,120p' of the workflow, wrapped in a harness), against GNU coreutils 9.11 in a container. Control is the same extracted block with only the case/esac removed, so the two arms differ by exactly this commit.

base → head	without this commit	with it
0.1.21 → 0.1.22	pass	pass
0.1.21 → 0.1.21	fail (equal)	fail (equal)
0.1.21 → 0.1.20	fail (below)	fail (below)
0.1.9 → 0.1.10	pass	pass
1.0.0 → 1.0.0-beta.1	PASS	FAIL (prerelease)
0.1.21 → 0.1.22-rc.1	PASS	FAIL (prerelease)
1.0.0-beta.1 → 1.0.0	fail (below)	fail (prerelease)
0.1.21-alpha → 0.1.21-alpha	fail (equal)	fail (prerelease)
"" → 0.1.0 (new package)	pass	pass
0.1.21 → ""	fail	fail

Two cells flip, both from fail-open to fail-closed, and every non-prerelease row is byte-identical. continue inside the case is inside the for pkg loop, so it skips the rest of that package and keeps going — correct, and fail=1 is set before it. Concatenating "$base_v$head_v" cannot invent a hyphen that is not in one of them, so the match has no false-positive path.

One thing the commit message could be read as claiming and doesn't do. It cites the legitimate promotion 1.0.0-beta.1 → 1.0.0 as a case the guard gets wrong. That case still fails after this commit — it moves from wrong reason (is BELOW the base's) to refusal (involves a prerelease). That is exactly what "refuse to judge" means and I am not asking you to change it, but a reader skimming the message may expect promotion to work now. Worth a clause.

Residual, same class, untouched and equally latent. 1.0.0 → 1.0.0+build.5 still passes in both arms. Build metadata is ignored for semver precedence, so those two have equal precedence — it is the same "one version, two artifacts" failure the equality branch exists to catch, and it slips through because the strings differ. The *-* pattern does not see +. Not worth another head: no version ever committed to either package carries build metadata either, and npm would refuse the republish. Flagging it because the principle you just adopted — a guard that cannot compare its inputs must say so — applies to + identically, and the next person to widen this is better off widening it once.

Check state at this head: the github-actions suite was allocated at 17:06:52Z with 3 runs and reads completed/success, so this head was actually dispatched — worth saying explicitly given the afternoon. PR is BLOCKED, not red.

Supersedes my gate at 4e9ca035.