Pre-launch: pre-commit hook + CI check for protocol version bump

[yyq1025]

Background

packages/protocol/package.json's version is the single source of truth — PROTOCOL_VERSION is read directly from this file at module load, hello/server_info carry the same field, and isProtocolCompatible() uses npm caret semantics.

Problem: today, changing packages/protocol/src/** does not force a version bump. If we forget, two ends running incompatible wire changes will still be judged as the same version, the handshake passes, and things silently break.

While V0 is still on 0.0.x (exact-match) the cost is low, but the moment we move to 0.x.y / 1.x.y, a missed bump becomes very expensive. A hard constraint must be in place before launch.

Expectations

1. Pre-commit hook (local)

• Detect staged changes under packages/protocol/src/** in the current commit
• Detect whether packages/protocol/package.json's version differs from base ref
• Src changed but version not bumped → block the commit with "protocol src changed but version not bumped"
• Escape hatch for doc-only / comment / pure-refactor changes: e.g. [skip-proto-bump] in the commit message, or explicit --no-verify (discouraged by default)

2. CI check (PR stage)

• Same detection logic running in GitHub Actions as a required status check
• More reliable than pre-commit (which can be bypassed with --no-verify)
• On failure, comment on the PR with clear guidance: what version to bump to (patch/minor/major based on the change)

3. Docs

• README or CONTRIBUTING should spell out the bump rules:
  • 0.0.x phase: any wire change → patch bump (exact-match)
  • 0.x.y phase: breaking → minor bump; additive → patch bump
  • ≥1.x phase: standard semver

Timing

Not urgent, but must land before launch (first public .dmg release). Until then, manual bumps during 0.0.x are manageable.

Related

• packages/protocol/package.json — version source
• packages/protocol/src/version.ts — PROTOCOL_VERSION / isProtocolCompatible (defer to code if the filename differs)

[yyq1025]

Implementation note: the compat semantics this issue cites changed in ef760e5 — isProtocolCompatible is now symmetric same-breaking-line, not npm caret. Consequence: 0.0.x is no longer exact-match. Patch bumps are compatible in both directions, which means a forgotten bump — or worse, a breaking change shipped as a patch — passes the handshake today, not just after we leave 0.0.x. That raises this check's priority.

What to enforce:

1. packages/protocol/src/** changed → packages/protocol/package.json version bumped at all (the original ask);
2. a guard that breaking changes bump the minor, not the patch — fully automating this is hard, but the documented trap (adding a case to an existing closed z.enum) is grep-detectable and worth a warning.

Natural home: the GitHub Actions release pipeline that's about to be set up for the menubar — fold this in as a required PR check there.