Plan: Fix auto-version-bump via ruleset bypass

Objective

Restore the direct-push version bump workflow by reverting PR #284's PR-based changes, removing the version guard bot exemption, and documenting the required GitHub ruleset bypass so github-actions[bot] can push directly to main.

Implement

Read and implement all steps in the plan at docs/plans/fix-version-bump-ruleset-bypass.html — Restore direct-push version bump with ruleset bypass

File fix-version-bump-ruleset-bypass.html

Path docs/plans/fix-version-bump-ruleset-bypass.html

Acceptance criteria 0 / 4 done

Context

The auto-version-bump.yml workflow runs after merges to main that touch kit/plugins/**. It computes the correct semver bump and updates marketplace.json, but cannot land the change because the repo's branch ruleset requires all changes go through a pull request. PR #284 changed the workflow to create PRs instead, but github-actions[bot] lacks permission to create PRs. The simplest fix is to add github-actions[bot] as a bypass actor in the branch ruleset and revert to the original direct-push workflow. The [skip ci] commit prefix and ci(versions): guard already prevent infinite loops.

Files to Modify

agentics/

.github/workflows/

auto-version-bump.yml modified revert to direct-push approach
version-guard.yml modified remove bot exemption condition

docs/GITHUB_SETUP.md new document ruleset bypass configuration

Steps

todo Revert auto-version-bump.yml to direct-push approach

The PR-based approach fails without additional repo/token configuration; direct push with a ruleset bypass is simpler and has fewer moving parts.

Verify

Diff against the pre-PR#284 version; the only differences should be the original "Commit and push" step and contents: write permission (no pull-requests: write).

todo Revert version-guard.yml to remove the bot exemption

With direct push (no bot-authored PRs), the version guard never sees a bot PR, so the exemption is dead code. Removing it keeps the guard unconditional.

Verify

The job block has no if: condition; it runs for every PR that changes the guarded paths.

todo Add docs/GITHUB_SETUP.md documenting the required ruleset bypass

This is a manual repo configuration step that can't be automated via code; documenting it prevents the next maintainer from hitting the same wall.

Verify

The file exists at docs/GITHUB_SETUP.md, names the exact Settings path, and references both the workflow file and the loop guards.

todo Test the workflow end-to-end after ruleset bypass is configured

The workflow has failed on every run since the branch ruleset was added; this confirms the fix actually works.

Verify

gh run list --workflow auto-version-bump.yml --limit 1 shows conclusion: success; git log --oneline -1 origin/main shows a ci(versions): commit.

Tests

Tier 2 — Non-code plan

Objective Version bump workflow runs to completion

File: N/A (manual verification via CI run)

Type: smoke test

Asserts: The auto-version-bump workflow runs to completion with conclusion: success after a plugin change is merged to main, and marketplace.json on main reflects the bumped version.

Run: Merge a trivial plugin change, then: gh run list --repo shawn-sandy/agentics --workflow auto-version-bump.yml --limit 1 --json conclusion

Acceptance Criteria

auto-version-bump.yml pushes directly to main (no PR creation, no pull-requests: write permission)
version-guard.yml has no bot-exemption if: condition — it runs unconditionally for all PRs
docs/GITHUB_SETUP.md documents the ruleset bypass requirement with the exact Settings navigation path
After the ruleset bypass is configured, the next plugin merge triggers a successful version bump workflow run

Verification

Read auto-version-bump.yml — confirm it has a "Commit and push" step that runs git push directly, no gh pr create, and permissions list only contents: write.
Read version-guard.yml — confirm the job has no if: condition.
Read docs/GITHUB_SETUP.md — confirm it documents the bypass actor configuration.
After the repo owner adds github-actions[bot] to the ruleset bypass list, merge any feat(kit/plugins/*) or fix(kit/plugins/*) change and confirm the workflow run succeeds.

Completion Checklist

Required

All step TODOs marked as done
All acceptance criteria verified and checked off
Plan status updated to completed

Completion Report

No items to report — all requirements met.

Next Steps

Backfill pending version bumps

Paste this prompt into Claude to execute this follow-up:

Check the last 5 failed auto-version-bump workflow runs in the agentics repo. For each, identify which plugin(s) were supposed to be bumped and what the target version should have been. Run the bump script locally with --dry-run to verify, then apply the missing bumps manually by running: node scripts/auto-bump-version.mjs. Commit as a single fix(versions) commit and push to main (after confirming the ruleset bypass is configured).

Unresolved Questions

Bypass scope — should the bypass be "Always" or scoped to specific rules?

The branch ruleset for main may have multiple rules (require PR, require status checks, require linear history, etc.). Should github-actions[bot] bypass ALL rules or only "Require a pull request before merging"? Check the current ruleset configuration for the shawn-sandy/agentics repo using gh api repos/shawn-sandy/agentics/rulesets and recommend the minimum bypass scope that allows the version bump push without exempting the bot from other protections like status checks.