chore(release): require version bumps for runtime changes - #112
Conversation
Why: - Runtime and plugin surface updates should not ship with stale marketplace/proofpack version metadata. - Local skill overrides were removed, so installed Signum should resolve through the plugin/marketplace path instead of a symlinked development checkout. What changed: - Bump Signum metadata and proofpack examples from 4.21.7 to 4.21.8 across root, Codex, and Claude overlay surfaces. - Add a deterministic stdlib version-bump checker for runtime/plugin-sensitive diffs and wire it into top-level deterministic tests. - Fetch full checkout history in deterministic CI so the checker can compare against the base ref. Testing: - python3 -m py_compile scripts/check_version_bump.py - bash tests/test-version-bump-required.sh - bash tests/test-ci-workflow.sh - bash tests/test-metadata-consistency.sh - bash tests/test-codex-plugin-metadata.sh - bash tests/test-proofpack-validation.sh - bash tests/test-signum-command-renderer.sh - bash tests/test-signum-fragment-parity.sh - bash scripts/run-deterministic-tests.sh Risk: - narrow - The guard can require a version bump for some broad runtime-sensitive paths, but this is intentional release hygiene and can be adjusted with tests if the sensitive set proves too wide. Signed-off-by: Vitaly D. <netmin@pm.me>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 96b7f32880
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
|
|
||
| def changed_files(repo_root: Path, base_ref: str) -> list[str]: | ||
| result = run_git(repo_root, ["diff", "--name-only", base_ref, "--"]) |
There was a problem hiding this comment.
changed_files() uses git diff --name-only <base_ref>, which compares the current tree directly to the base tip instead of the branch merge-base. When the branch is behind main (or when CI checks out PR head instead of the merge ref), files changed only on the base branch appear as differences and can be flagged as sensitive, causing a false version.bump_required failure for docs-only PRs. Use merge-base semantics (e.g., git diff --name-only --merge-base <base_ref>) so only changes introduced by the current branch trigger the gate.
Useful? React with 👍 / 👎.
| result = run_git(repo_root, ["rev-parse", "--verify", f"{env_ref}^{{commit}}"], check=False) | ||
| return (env_ref, None) if result.returncode == 0 else (env_ref, "base_ref_unavailable") | ||
|
|
||
| for ref in ("origin/main", "HEAD^"): |
There was a problem hiding this comment.
When origin/main is unavailable, resolve_base_ref() falls back to HEAD^, which only compares the latest commit. That misses earlier runtime/plugin changes in multi-commit branches (for example: commit 1 changes lib/, commit 2 changes docs; running the checker then reports no sensitive changes and passes without a version bump). Use a true branch base (merge-base against the default branch or an explicit base ref) instead of a single-parent fallback.
Useful? React with 👍 / 👎.
| result = run_git(repo_root, ["rev-parse", "--verify", f"{env_ref}^{{commit}}"], check=False) | ||
| return (env_ref, None) if result.returncode == 0 else (env_ref, "base_ref_unavailable") | ||
|
|
||
| for ref in ("origin/main", "HEAD^"): |
There was a problem hiding this comment.
The default base ref preference (origin/main) makes the guard ineffective on push builds to main: after checkout/fetch, origin/main points at the same commit as HEAD, so git diff --name-only origin/main -- is empty even when that pushed commit changed sensitive runtime/plugin paths without a version bump. Since .github/workflows/ci.yml runs on push and pull_request, this creates a false-negative path for direct pushes; use an event-aware base (e.g., the pre-push SHA) for push runs.
Useful? React with 👍 / 👎.
1 participant
Linked intent
Link the Issue or Discussion this PR implements.
For non-trivial changes, open an Issue or Discussion before code review. Direct PRs are intended only for typo/docs fixes, small test-only changes, clearly scoped bug fixes, or maintainer-approved work.
Problem
Signum runtime/plugin updates could pass with stale plugin metadata, leaving Codex/Claude marketplace installs and proofpack examples pointing at an older release version.
Why now
The local development symlink path was removed so Signum should be consumed through the installed plugin/marketplace path. That makes version hygiene more important: runtime/plugin surface changes need a visible release bump before adoption.
Existing options checked
Existing metadata consistency tests verified that current files agree with each other, but did not compare the branch against a base ref to require a version increase when runtime/plugin-sensitive files changed.
Alternatives considered
No-code alternative
Documenting the requirement would help maintainers, but would not prevent another stale version from passing deterministic tests.
Why code is needed
A deterministic checker can inspect changed paths against the base ref and fail PR tests when runtime/plugin-sensitive diffs do not increase
.claude-plugin/plugin.jsonsemver.Summary
4.21.7to4.21.8across root, Codex, and Claude overlay surfaces./signumcommand metadata and proofpack fixtures to4.21.8.scripts/check_version_bump.pyandtests/test-version-bump-required.sh.Type
Mark all that apply.
libScope
In:
4.21.8.Out:
Risk areas
Mark anything touched in this PR.
commands/signum.mdcommands/init.mdagents/*lib/*lib/schemas/*.github/workflows/*Docs impact
README.mdorQUICKSTART.mdupdatedAGENTS.mdupdateddocs/how-it-works.mdordocs/reference.mdupdateddocs/SECURITY.mdupdatedDocs / rationale:
v4.21.8.Validation / proof
Commands run:
Relevant results:
DCO / authorship
git commit -s) and complies withDCO.mdReviewer notes
scripts/check_version_bump.pyintentionally treatscommands/,agents/,lib/,scripts/, Codex plugin surfaces, and Claude overlay runtime/plugin surfaces as version-sensitive.v4.21.8tag exists.