Thanks to visit codestin.com
Credit goes to github.com

Skip to content

fix(main): recover version drift, fix stale test, document learnings#678

Merged
tmchow merged 3 commits into
mainfrom
tmchow/revert-claude-plugin-version-drift
Apr 24, 2026
Merged

fix(main): recover version drift, fix stale test, document learnings#678
tmchow merged 3 commits into
mainfrom
tmchow/revert-claude-plugin-version-drift

Conversation

@tmchow
Copy link
Copy Markdown
Collaborator

@tmchow tmchow commented Apr 24, 2026

Summary

main's CI has been red since four direct-to-main merges bumped plugins/compound-engineering/.claude-plugin/plugin.json past the other plugin manifests (3.0.3 to 3.0.7) without syncing the cursor, codex, release-please manifest, or linked cli files. This PR unblocks CI by forward-syncing everything to 3.0.7, repairs a stale test assertion that was hiding behind the release-validate failure, and ships a recovery playbook so this class of drift doesn't eat hours of investigation next time.

Drift recovery

Forward-sync rather than revert because anyone running compound-engineering from a local main checkout already has 3.0.7 in their plugin cache. Reverting to 3.0.3 would orphan those caches and trip version-regression warnings in tooling that treats the version field as monotonic. Forward-sync preserves semver monotonicity with zero regression for any current install.

The 5 version fields now agree at 3.0.7:

File Field
plugins/compound-engineering/.cursor-plugin/plugin.json $.version
plugins/compound-engineering/.codex-plugin/plugin.json $.version
.github/.release-please-manifest.json plugins/compound-engineering
.github/.release-please-manifest.json . (cli, via linked-versions)
package.json $.version (cli extra-file)

The release-please manifest edit is intentional. Release-please's own docs call out manual manifest edits as the correct recovery pattern for out-of-band releases. Without it, the next release-please run would compute the next version from 3.0.3 and overwrite extra-files downward, regressing any user on 3.0.7.

Stale test fix

Commit 1f20c384 feat(lfg): add ce-commit-push-pr step and remove ralph-loop renumbered steps in lfg/SKILL.md but did not update two assertions in tests/review-skill-contract.test.ts. Fix: "step 6" becomes "step 5" (residual handoff is the chronologically-next step after persisting autofixes), and the now-over-broad not.toContain("ce-commit-push-pr") becomes a positive assertion on step 5's "do not load any confirmation-driven PR update skill" phrase. The intent the broad check was trying to express is preserved; step 7's legitimate use of ce-commit-push-pr no longer trips it.

Recovery playbook

New doc at docs/solutions/workflow/release-please-version-drift-recovery.md captures:

  • The file-relationship map (extra-files + manifest + linked-versions)
  • How release-please reads the manifest and writes extra-files
  • The recovery decision tree: forward-sync vs. backward-revert vs. release-as pin, with user-install impact as the tiebreaker
  • When manifest manual edits are legitimate (out-of-band recovery only)
  • The 2026-04-24 incident as a worked example

Root AGENTS.md gains a Merge policy bullet making the "all changes via PR" rule explicit. Plugin AGENTS.md "Versioning Requirements" gets a one-line pointer to the new playbook so anyone hitting release:validate drift lands on the recovery doc first.

Verification

bun run release:validate: in sync. bun test: 906 / 906.

Follow-up

Kieran: please enable branch protection on main requiring the test status check before merge, with admin bypass off or reserved for emergencies. The new Merge policy rule is honor-system without branch protection, which this incident showed is not enough. The drift crept in across 1f20c384, f8720da3, 22d493b1, and 47350c3e, all direct merges.


Compound Engineering
Claude Code

`.claude-plugin/plugin.json` was manually bumped 3.0.3 → 3.0.4 → 3.0.5
→ 3.0.6 → 3.0.7 across recent feature commits (1f20c38, f8720da,
22d493b, 47350c3) without corresponding bumps to `.cursor-plugin`,
`.codex-plugin`, the release-please manifest, or the linked cli
package.json. AGENTS.md "Versioning Requirements" explicitly forbids
manual bumps here — release-please owns all three plugin.json files via
extra-files in .github/release-please-config.json, and the linked-versions
plugin keeps cli and compound-engineering in lockstep.

Drift broke `release:validate` on every PR's CI (PR #677 surfaced it).

Recovery uses the "forward" path (sync everything to 3.0.7) instead of
reverting .claude-plugin to 3.0.3, because developers running
compound-engineering from a local main checkout already have 3.0.7
installed. Reverting would orphan their cache dirs and trigger
version-regression warnings in tooling that treats the field as
monotonic. Forward-sync preserves semver monotonicity with zero
regression for any current install.

Changes:
- .cursor-plugin/plugin.json: 3.0.3 → 3.0.7 (compound-engineering extra-file)
- .codex-plugin/plugin.json: 3.0.3 → 3.0.7 (compound-engineering extra-file)
- .github/.release-please-manifest.json: compound-engineering 3.0.3 → 3.0.7
- .github/.release-please-manifest.json: . (cli, linked-versions) 3.0.3 → 3.0.7
- package.json: 3.0.3 → 3.0.7 (cli extra-file, linked to compound-engineering)

`bun run release:validate` now reports in-sync metadata. The next
release-please run will compute 3.0.8+ from a coherent starting point.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@tmchow tmchow force-pushed the tmchow/revert-claude-plugin-version-drift branch from ba76ec9 to 9117c68 Compare April 24, 2026 21:41
@tmchow tmchow changed the title fix(release): revert manual version bumps on .claude-plugin/plugin.json fix(release): forward-sync all version fields to 3.0.7 Apr 24, 2026
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9117c68fd9

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

Comment thread .github/.release-please-manifest.json
Commit 1f20c38 (feat(lfg): add ce-commit-push-pr step and remove ralph-loop)
renumbered the steps in lfg/SKILL.md when it removed the optional
ralph-loop step 1 and added ce-commit-push-pr as step 7. Two assertions
in tests/review-skill-contract.test.ts weren't updated:

1. The "Do not proceed to step 6" assertion now reads "step 5" in the
   skill, because residual handoff is the chronologically-next step
   after persisting autofixes.
2. The broad `not.toContain("ce-commit-push-pr")` assertion was
   tripping on step 7's legitimate use of the skill for the post-work
   commit/PR-open step. The intent was to verify the residual handoff
   doesn't route through confirmation-driven PR updates, which is
   already covered by the positive `gh pr edit` assertion. Replaced
   the broad check with a positive assertion on the exact "do not load
   any confirmation-driven PR update skill" phrase from step 5.

Running bun test after this and the release-metadata sync above now
reports 906/906 passing on this branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@tmchow tmchow changed the title fix(release): forward-sync all version fields to 3.0.7 fix(main): sync plugin versions + update stale lfg test assertions Apr 24, 2026
Captures the learnings from the direct-to-main drift incident so future
investigations don't have to rediscover the file relationships, the
decision tree, or why manifest manual edits are sometimes legitimate.

New solution doc `docs/solutions/workflow/release-please-version-drift-recovery.md`:
- File relationship map showing extra-files, manifest, and linked-versions
- How release-please reads manifest and writes extra-files
- Recovery decision tree (forward-sync vs backward-revert vs release-as pin)
- When manifest manual edits are legitimate (out-of-band recovery)
- The 2026-04-24 incident as worked example

Root AGENTS.md Working Agreement gains a `Merge policy` bullet making
explicit that all changes go through PRs, branch protection enforces
the `test` check, and direct merges have caused real damage. This is
the rule the incident implied but the doc never stated.

Plugin AGENTS.md Versioning Requirements gets a pointer to the recovery
doc so anyone hitting `release:validate` drift finds the playbook on
first stop instead of having to investigate the file relationships
from scratch.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@tmchow tmchow changed the title fix(main): sync plugin versions + update stale lfg test assertions fix(main): recover version drift, fix stale test, document learnings Apr 24, 2026
@tmchow tmchow merged commit bc8ae1a into main Apr 24, 2026
2 checks passed
@github-actions github-actions Bot mentioned this pull request Apr 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant