gempilot 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4b895f3da5d0d8866cd13f835dd3c1ca71d8d433571c2d7531735636eeb6ad0
-  data.tar.gz: 878dad31a22bdecdb9ff607ebecf2330432070219edfc3e08b66a5022c205d77
+  metadata.gz: ed510959d35011586d23fc0dcc0baff3a453a2acbd1a2d1c8fb4489cee63e6e0
+  data.tar.gz: 455ba876df7b3fb40df26932737cae4062a6e6e2210f1fd02b18a231566bd23d
 SHA512:
-  metadata.gz: ccfc9410fe3ccd3cc8f49e3ca34f68ef334a50183eb95d0788f09c9a5e972fcb4b1244cdfeee188b9898e25ba1c4542d6c4cf24ee24e54edebd4e8b8e907f6a1
-  data.tar.gz: e7deb74172aa7bcd75d84f41ad2d80022d9befcd7f1b69990c6f8b9fe6002168d8b25581242dbded279bdd601986c24552b1431573ff0ed62bec8316734e50fe
+  metadata.gz: 4ce5185ea5c07adc72435dee47b2f749f4f6146f26a09c8d8c557490e4be1b69b2b048e4c9ab32b8548d043c9a0d393cc32a0d8dd23c94c98cabd3a8737334d9
+  data.tar.gz: 6094227a45e9bb173f0455dc155bd3ac7593698a7c41c7ac1482c5e7c44a59a90c547bb20206d3c7887b87a84977fc1f7ca615b2975fe53dc6a8ab85384a83e8

data/.rubocop.yml

@@ -15,7 +15,6 @@ plugins:
   - rubocop-performance
   - rubocop-rake
   - rubocop-rspec
-  - rubocop-design
 
 AllCops:
   NewCops: enable

data/CLAUDE.md

@@ -35,4 +35,5 @@ A CLI tool for creating and managing Ruby gems, built on CommandKit.
 - RuboCop with framework-specific plugins
 - GitHub Actions CI workflow (`.github/workflows/ci.yml`)
 - `git ls-files`-based gemspec with glob fallback for non-git repos
-- Version lifecycle rake tasks installed via `Gempilot::VersionTask.new` (a `Rake::TaskLib`): `version:current/bump/commit/tag/untag/reset/revert`, composite `version:release`/`version:unrelease`, and `version:github:release/unrelease/list`
+- Version lifecycle rake tasks installed via `Gempilot::VersionTask.new` (a `Rake::TaskLib`): `version:current/bump/commit/tag/untag/reset/revert` and composite `version:release`/`version:unrelease`
+- Publishing rake tasks (mixed into `VersionTask` via `Gempilot::ReleaseTasks`): `release` (all remotes), `release:rubygems`, `release:github`, `release:list:github`, `unrelease`, `unrelease:github`. These override and reuse bundler's `bundler/gem_tasks` release chain; `release:source_control_push` is replaced with `Gempilot::Origin` to push commit+tag idempotently

data/README.md

@@ -86,7 +86,8 @@ gempilot bump major
 
 ### `gempilot release`
 
-Delegates to `rake release` to build and push the gem.
+Delegates to `rake release`, which publishes the current version to all remotes
+(RubyGems + GitHub).
 
 ### `gempilot console`
 
@@ -120,9 +121,12 @@ Generated gems include rake tasks for the full version lifecycle:
 | `rake version:revert` | Revert the last version bump commit |
 | `rake version:release` | Bump, commit, and tag (combined) |
 | `rake version:unrelease` | Untag and reset (combined) |
-| `rake version:github:release` | Push and create a GitHub release |
-| `rake version:github:unrelease` | Delete the GitHub release |
-| `rake version:github:list` | List GitHub releases |
+| `rake release` | Publish the current version to all remotes (RubyGems + GitHub) |
+| `rake release:rubygems` | Build and push the gem to RubyGems |
+| `rake release:github` | Push commit + tag, then create the GitHub release |
+| `rake release:list:github` | List GitHub releases |
+| `rake unrelease` | Delete the release from all remotes that support it |
+| `rake unrelease:github` | Delete the GitHub release and remote tag |
 
 ## Development
 

data/data/templates/gem/dotfiles/rubocop.yml.erb

@@ -25,12 +25,6 @@ AllCops:
   Exclude:
     - bin/*
     - vendor/**/*
-    - lib/core_ext/**/*
-    - rakelib/project.rb
-    - rakelib/project_version.rb
-    - rakelib/version_tag.rb
-    - rakelib/github_release.rb
-    - rakelib/strict_shell.rb
 <% if @hyphenated -%>
     - lib/<%= @gem_name %>.rb
 <% end -%>
@@ -124,17 +118,12 @@ Metrics/BlockLength:
 <% end -%>
   Exclude:
     - "<%= @gem_name %>.gemspec"
-    - "rakelib/**/*"
 
-# Gemspec and rake files use patterns that trigger Claude cops legitimately.
+# Gemspec uses patterns that trigger Claude cops legitimately.
 Claude/NoFancyUnicode:
   Exclude:
     - "<%= @gem_name %>.gemspec"
 
-Claude/MysteryRegex:
-  Exclude:
-    - "rakelib/**/*"
-
 # Zeitwerk loaders are mutable by design — only flag literal mutable values.
 Style/MutableConstant:
   EnforcedStyle: literals

data/docs/superpowers/plans/2026-07-20-release-task-hierarchy.md

@@ -0,0 +1,583 @@
+# Release Task Hierarchy Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move GitHub publishing out of the `version:github:*` namespace into the idiomatic `release` / `unrelease` namespace, and fix GitHub releasing (bundler's `already_tagged?` guard silently skips the git push).
+
+**Architecture:** A new `Gempilot::Origin` object does an idempotent commit+tag push and replaces bundler's buggy `release:source_control_push`. RubyGems publishing reuses bundler's own `build` / `release:guard_clean` / `release:rubygem_push` leaf tasks via prerequisites; GitHub publishing uses the existing (slimmed) `GithubRelease`. All task wiring lives in a new `Gempilot::ReleaseTasks` module mixed into `VersionTask`. Bare `rake release` is a pure prerequisite composite over both remotes — no arguments, no dispatcher code.
+
+**Tech Stack:** Ruby, Rake (`Rake::TaskLib`, `bundler/gem_tasks`), Zeitwerk autoloading, RSpec (unit specs) + Minitest (generator tests), RuboCop (`rubocop-claude`/`-rspec`/`-performance`/`-rake`/`-design`).
+
+**Spec:** `docs/superpowers/specs/2026-07-20-release-task-hierarchy-design.md`
+
+---
+
+## Preconditions
+
+- Branch `release-task-hierarchy` is checked out.
+- `bundle install` works and the baseline is green:
+  - `bundle exec rake spec` → `106 examples, 0 failures`
+  - `bundle exec rake test` → `108 runs, 0 failures`
+  - `bundle exec rubocop` → `no offenses detected`
+- If `bundle install` fails with `Bundler::Plugin::Index::SourceConflict (Source(s) 'vault' ...)`, align the local plugin index to the installed vault plugin version, then reinstall:
+  ```bash
+  ruby -e 'f=".bundle/plugin/index"; File.write(f, File.read(f).gsub("bundler-source-vault-0.1.2","bundler-source-vault-0.1.5"))'
+  bundle install
+  ```
+  (`.bundle/` is not tracked by git — this is a local-environment fix only.)
+
+## Final target — task interface
+
+| Task | Behavior |
+| --- | --- |
+| `rake release` | Publish current version to all remotes (RubyGems + GitHub) |
+| `rake release:rubygems` | Build + push the gem to RubyGems |
+| `rake release:github` | Push commit + tag, then create the GitHub release |
+| `rake release:list:github` | List GitHub releases |
+| `rake unrelease` | Delete the release from all remotes that support it (GitHub) |
+| `rake unrelease:github` | Delete the GitHub release and remote tag |
+
+`version:github:release/unrelease/list` are removed. `version:*` lifecycle tasks and the `version:release`/`version:unrelease` composites are unchanged.
+
+---
+
+## Task 1: `Gempilot::Origin` (idempotent commit + tag push)
+
+**Files:**
+- Create: `lib/gempilot/origin.rb`
+- Test: `spec/gempilot/origin_spec.rb`
+
+This is the bug fix: an always-push, no-guard replacement for bundler's `release:source_control_push`. Mirrors bundler's `git_push` (push the branch ref, then the tag ref, to the branch's configured remote — defaulting to `origin`).
+
+- [ ] **Step 1: Write the failing spec**
+
+Create `spec/gempilot/origin_spec.rb`:
+
+```ruby
+require "spec_helper"
+
+RSpec.describe Gempilot::Origin do
+  subject(:origin) { described_class.new("v1.2.3") }
+
+  around do |example|
+    Dir.mktmpdir("origin_spec") { |dir| Dir.chdir(dir) { example.run } }
+  end
+
+  before do
+    system("git", "init", "--quiet", "-b", "main", ".")
+    system("git", "config", "user.email", "test@test.com")
+    system("git", "config", "user.name", "Test")
+    system("git", "commit", "--allow-empty", "--quiet", "-m", "init")
+  end
+
+  describe "#push" do
+    before { allow(origin).to receive(:sh) }
+
+    it "pushes the current branch, then the tag, to the resolved remote", :aggregate_failures do
+      origin.push
+      expect(origin).to have_received(:sh).with("git", "push", "origin", "refs/heads/main").ordered
+      expect(origin).to have_received(:sh).with("git", "push", "origin", "refs/tags/v1.2.3").ordered
+    end
+  end
+
+  describe "#push against a real remote" do
+    before do
+      system("git", "clone", "--quiet", "--bare", ".", "origin.git")
+      system("git", "remote", "add", "origin", "origin.git")
+      system("git", "tag", "v1.2.3")
+    end
+
+    it "lands the tag on the remote and stays idempotent on re-run", :aggregate_failures do
+      origin.push
+      expect(`git --git-dir=origin.git tag`.strip).to eq("v1.2.3")
+      expect { described_class.new("v1.2.3").push }.not_to raise_error
+    end
+  end
+end
+```
+
+- [ ] **Step 2: Run the spec, verify it fails**
+
+Run: `bundle exec rspec spec/gempilot/origin_spec.rb`
+Expected: FAIL — `uninitialized constant Gempilot::Origin` (or `NameError`).
+
+- [ ] **Step 3: Implement `Gempilot::Origin`**
+
+Create `lib/gempilot/origin.rb`:
+
+```ruby
+require "open3"
+
+module Gempilot
+  ## Pushes the current branch and a release tag to the branch's git remote.
+  ## Backs the +release:source_control_push+ task. Idempotent: pushing an
+  ## already-pushed branch or tag is a no-op, so re-running a release never
+  ## fails on an existing tag (unlike bundler's +already_tagged?+ guard, which
+  ## skips the push entirely once the tag exists locally).
+  class Origin
+    include StrictShell
+
+    attr_reader :tag
+
+    def initialize(tag)
+      @tag = tag
+    end
+
+    def push
+      sh "git", "push", remote, "refs/heads/#{branch}"
+      sh "git", "push", remote, "refs/tags/#{tag}"
+    end
+
+    private
+
+    def branch
+      @branch ||= capture("git", "rev-parse", "--abbrev-ref", "HEAD")
+    end
+
+    def remote
+      @remote ||= configured_remote || "origin"
+    end
+
+    def configured_remote
+      out, status = Open3.capture2("git", "config", "--get", "branch.#{branch}.remote")
+      out.strip if status.success?
+    end
+
+    def capture(*args)
+      out, status = Open3.capture2(*args)
+      raise "Command #{args.join(" ").inspect} failed" unless status.success?
+
+      out.strip
+    end
+  end
+end
+```
+
+- [ ] **Step 4: Run the spec, verify it passes**
+
+Run: `bundle exec rspec spec/gempilot/origin_spec.rb`
+Expected: PASS — `3 examples, 0 failures` (2 `#push` examples across the two describe blocks). RuboCop next.
+
+- [ ] **Step 5: Lint the new files**
+
+Run: `bundle exec rubocop lib/gempilot/origin.rb spec/gempilot/origin_spec.rb`
+Expected: `no offenses detected`. If any offense appears, fix it and re-run.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/gempilot/origin.rb spec/gempilot/origin_spec.rb
+git commit -m "Add Gempilot::Origin for idempotent commit+tag push"
+```
+
+---
+
+## Task 2: Slim `GithubRelease#create`
+
+**Files:**
+- Modify: `lib/gempilot/github_release.rb`
+- Test: `spec/gempilot/github_release_spec.rb`
+
+Pushing is now `Origin`'s job (the `release:source_control_push` prerequisite). `GithubRelease#create` should only call `gh release create`.
+
+- [ ] **Step 1: Update the spec to drop the git-push expectations**
+
+In `spec/gempilot/github_release_spec.rb`, replace the entire `describe "#create"` block:
+
+```ruby
+  describe "#create" do
+    it "creates a release with generated notes" do
+      release.create
+      args = ["gh", "release", "create", "--generate-notes", "--fail-on-no-commits", tag]
+      expect(release).to have_received(:sh).with(*args)
+    end
+  end
+```
+
+(Leave the `#destroy` and `#list` describe blocks unchanged.)
+
+- [ ] **Step 2: Run the spec, verify `#create` now fails**
+
+Run: `bundle exec rspec spec/gempilot/github_release_spec.rb`
+Expected: The `#create` example passes already (it only asserts the `gh` call), but confirm the whole file is green. If green, the current `create` still issues `git push` calls harmlessly. To make the test *drive* the change, also assert no git push:
+
+Add this example inside `describe "#create"`:
+
+```ruby
+    it "does not push git refs itself" do
+      release.create
+      expect(release).not_to have_received(:sh).with("git", any_args)
+    end
+```
+
+Run again: `bundle exec rspec spec/gempilot/github_release_spec.rb`
+Expected: FAIL — `does not push git refs itself` fails because `create` still runs `git push`.
+
+- [ ] **Step 3: Remove the git push from `create`**
+
+In `lib/gempilot/github_release.rb`, change `create` from:
+
+```ruby
+    def create
+      sh "git", "push"
+      sh "git", "push", "--tags"
+      sh "gh", "release", "create",
+         "--generate-notes", "--fail-on-no-commits",
+         tag
+    end
+```
+
+to:
+
+```ruby
+    def create
+      sh "gh", "release", "create",
+         "--generate-notes", "--fail-on-no-commits",
+         tag
+    end
+```
+
+- [ ] **Step 4: Run the spec, verify it passes**
+
+Run: `bundle exec rspec spec/gempilot/github_release_spec.rb`
+Expected: PASS — all examples green.
+
+- [ ] **Step 5: Lint**
+
+Run: `bundle exec rubocop lib/gempilot/github_release.rb spec/gempilot/github_release_spec.rb`
+Expected: `no offenses detected`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/gempilot/github_release.rb spec/gempilot/github_release_spec.rb
+git commit -m "Slim GithubRelease#create: push is now Origin's job"
+```
+
+---
+
+## Task 3: `ReleaseTasks` module + rewire `VersionTask`
+
+**Files:**
+- Create: `lib/gempilot/release_tasks.rb`
+- Modify: `lib/gempilot/version_task.rb`
+- Test: `spec/gempilot/version_task_spec.rb`
+
+The new `release`/`unrelease` task tree, extracted into a module (keeps `VersionTask` under `Metrics/ClassLength`) and `include`d into `VersionTask`.
+
+- [ ] **Step 1: Write the failing spec additions**
+
+In `spec/gempilot/version_task_spec.rb`, add these two `describe` blocks inside the top-level `RSpec.describe Gempilot::VersionTask do ... end` (e.g. after the existing `describe "version:release"` block, before the final `end`):
+
+```ruby
+  describe "release task hierarchy" do
+    it "defines the release and unrelease tasks", :aggregate_failures do
+      %w[release release:rubygems release:github release:list:github unrelease unrelease:github].each do |name|
+        expect(Rake::Task).to be_task_defined(name)
+      end
+    end
+
+    it "removes the old version:github tasks", :aggregate_failures do
+      %w[version:github:release version:github:unrelease version:github:list].each do |name|
+        expect(Rake::Task).not_to be_task_defined(name)
+      end
+    end
+
+    it "composes release from the per-remote tasks" do
+      expect(Rake::Task["release"].prerequisites).to eq(%w[release:rubygems release:github])
+    end
+
+    it "builds release:rubygems from bundler's own tasks" do
+      chain = %w[build release:guard_clean release:source_control_push release:rubygem_push]
+      expect(Rake::Task["release:rubygems"].prerequisites).to eq(chain)
+    end
+
+    it "composes unrelease from the github task" do
+      expect(Rake::Task["unrelease"].prerequisites).to eq(%w[unrelease:github])
+    end
+  end
+
+  describe "release task behavior" do
+    let(:origin) { instance_double(Gempilot::Origin, push: nil) }
+    let(:github) { instance_double(Gempilot::GithubRelease, create: nil, destroy: nil, list: nil) }
+
+    before do
+      allow(Gempilot::Origin).to receive(:new).and_return(origin)
+      allow(Gempilot::GithubRelease).to receive(:new).and_return(github)
+    end
+
+    it "release:source_control_push pushes via Origin" do
+      Rake::Task["release:source_control_push"].invoke
+      expect(origin).to have_received(:push)
+    end
+
+    it "release:github pushes, then creates the release", :aggregate_failures do
+      Rake::Task["release:github"].invoke
+      expect(origin).to have_received(:push)
+      expect(github).to have_received(:create)
+    end
+
+    it "release:list:github lists releases" do
+      Rake::Task["release:list:github"].invoke
+      expect(github).to have_received(:list)
+    end
+
+    it "unrelease:github destroys the release" do
+      Rake::Task["unrelease:github"].invoke
+      expect(github).to have_received(:destroy)
+    end
+  end
+```
+
+- [ ] **Step 2: Run the spec, verify it fails**
+
+Run: `bundle exec rspec spec/gempilot/version_task_spec.rb`
+Expected: FAIL — `release`/`release:github`/etc. are not defined; several examples error with "Don't know how to build task 'release:github'" / `be_task_defined` returns false.
+
+- [ ] **Step 3: Create the `ReleaseTasks` module**
+
+Create `lib/gempilot/release_tasks.rb`:
+
+```ruby
+module Gempilot
+  ## Rake task definitions for publishing a release to RubyGems and GitHub.
+  ## Mixed into VersionTask. Assumes +bundler/gem_tasks+ has been required so the
+  ## +build+, +release:guard_clean+, and +release:rubygem_push+ tasks exist (the
+  ## generated Rakefile guarantees this). Fixes GitHub releasing by replacing
+  ## bundler's +already_tagged?+-guarded +release:source_control_push+ with an
+  ## idempotent push.
+  module ReleaseTasks
+    private
+
+    def define_release_tasks(project)
+      override_source_control_push(project)
+      define_release_namespace(project)
+      define_root_release_task
+      define_unrelease_tasks(project)
+    end
+
+    def override_source_control_push(project)
+      clear_task "release:source_control_push"
+      task("release:source_control_push") { Origin.new(project.version_tag).push }
+    end
+
+    def define_release_namespace(project)
+      namespace :release do
+        define_rubygems_release
+        define_github_release(project)
+        define_release_list(project)
+      end
+    end
+
+    def define_rubygems_release
+      desc "Release the current version to RubyGems"
+      task rubygems: %w[build release:guard_clean release:source_control_push release:rubygem_push]
+    end
+
+    def define_github_release(project)
+      desc "Create a GitHub release for the current version"
+      task github: "release:source_control_push" do
+        GithubRelease.new(project.version_tag).create
+      end
+    end
+
+    def define_release_list(project)
+      namespace :list do
+        desc "List GitHub releases"
+        task(:github) { GithubRelease.new(project.version_tag).list }
+      end
+    end
+
+    def define_root_release_task
+      clear_task "release"
+      desc "Release the current version to all remotes"
+      task release: %w[release:rubygems release:github]
+    end
+
+    def define_unrelease_tasks(project)
+      desc "Delete the current release from all remotes that support it"
+      task unrelease: %w[unrelease:github]
+      define_unrelease_namespace(project)
+    end
+
+    def define_unrelease_namespace(project)
+      namespace :unrelease do
+        desc "Delete the GitHub release for the current version"
+        task(:github) { GithubRelease.new(project.version_tag).destroy }
+      end
+    end
+
+    def clear_task(name)
+      Rake::Task[name].clear if Rake::Task.task_defined?(name)
+    end
+  end
+end
+```
+
+- [ ] **Step 4: Rewire `VersionTask` to use the module**
+
+In `lib/gempilot/version_task.rb`:
+
+First, add the include at the top of the class body (right after `class VersionTask < Rake::TaskLib`):
+
+```ruby
+  class VersionTask < Rake::TaskLib
+    include ReleaseTasks
+
+    attr_reader :project
+```
+
+Then change `define_tasks` from:
+
+```ruby
+    def define_tasks
+      define_version_tasks
+      define_version_composite_tasks
+      define_github_tasks
+    end
+```
+
+to:
+
+```ruby
+    def define_tasks
+      define_version_tasks
+      define_version_composite_tasks
+      define_release_tasks(@project)
+    end
+```
+
+Then delete the entire `define_github_tasks` method (the `namespace "version:github" do ... end` method) — from `def define_github_tasks` through its closing `end`.
+
+- [ ] **Step 5: Run the version_task spec, verify it passes**
+
+Run: `bundle exec rspec spec/gempilot/version_task_spec.rb`
+Expected: PASS — all examples green (existing `version:bump`/`version:release` plus the new hierarchy/behavior examples).
+
+- [ ] **Step 6: Run the full suite + lint**
+
+Run: `bundle exec rake spec && bundle exec rake test && bundle exec rubocop`
+Expected: `rake spec` green, `rake test` green, RuboCop `no offenses detected`. In particular confirm `lib/gempilot/version_task.rb` reports no `Metrics/ClassLength` offense.
+
+- [ ] **Step 7: Sanity-check the task tree renders and old tasks are gone**
+
+Run (from the repo root — gempilot dogfoods its own `VersionTask`):
+```bash
+bundle exec rake -T release ; bundle exec rake -T unrelease ; bundle exec rake -AT | grep -c 'version:github' || true
+```
+Expected: `release`, `release:rubygems`, `release:github`, `release:list:github`, `unrelease`, `unrelease:github` appear; the `version:github` grep count is `0`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add lib/gempilot/release_tasks.rb lib/gempilot/version_task.rb spec/gempilot/version_task_spec.rb
+git commit -m "Move GitHub publishing into idiomatic release/unrelease namespace"
+```
+
+---
+
+## Task 4: Update docs
+
+**Files:**
+- Modify: `README.md`
+- Modify: `CLAUDE.md`
+
+No tests — documentation only. Make the exact edits below.
+
+- [ ] **Step 1: Update the README `gempilot release` note**
+
+In `README.md`, replace:
+
+```markdown
+Delegates to `rake release` to build and push the gem.
+```
+
+with:
+
+```markdown
+Delegates to `rake release`, which publishes the current version to all remotes
+(RubyGems + GitHub).
+```
+
+- [ ] **Step 2: Update the README task table**
+
+In `README.md`, replace these three rows:
+
+```markdown
+| `rake version:github:release` | Push and create a GitHub release |
+| `rake version:github:unrelease` | Delete the GitHub release |
+| `rake version:github:list` | List GitHub releases |
+```
+
+with:
+
+```markdown
+| `rake release` | Publish the current version to all remotes (RubyGems + GitHub) |
+| `rake release:rubygems` | Build and push the gem to RubyGems |
+| `rake release:github` | Push commit + tag, then create the GitHub release |
+| `rake release:list:github` | List GitHub releases |
+| `rake unrelease` | Delete the release from all remotes that support it |
+| `rake unrelease:github` | Delete the GitHub release and remote tag |
+```
+
+(The `rake version:release` and `rake version:unrelease` rows stay.)
+
+- [ ] **Step 3: Update CLAUDE.md**
+
+In `CLAUDE.md`, replace this bullet:
+
+```markdown
+- Version lifecycle rake tasks installed via `Gempilot::VersionTask.new` (a `Rake::TaskLib`): `version:current/bump/commit/tag/untag/reset/revert`, composite `version:release`/`version:unrelease`, and `version:github:release/unrelease/list`
+```
+
+with:
+
+```markdown
+- Version lifecycle rake tasks installed via `Gempilot::VersionTask.new` (a `Rake::TaskLib`): `version:current/bump/commit/tag/untag/reset/revert` and composite `version:release`/`version:unrelease`
+- Publishing rake tasks (mixed into `VersionTask` via `Gempilot::ReleaseTasks`): `release` (all remotes), `release:rubygems`, `release:github`, `release:list:github`, `unrelease`, `unrelease:github`. These override and reuse bundler's `bundler/gem_tasks` release chain; `release:source_control_push` is replaced with `Gempilot::Origin` to push commit+tag idempotently
+```
+
+- [ ] **Step 4: Verify no stale references remain**
+
+Run: `grep -rn "version:github" README.md CLAUDE.md`
+Expected: no output.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add README.md CLAUDE.md docs/superpowers/specs/2026-07-20-release-task-hierarchy-design.md
+git commit -m "Docs: document release/unrelease task hierarchy"
+```
+
+---
+
+## Task 5: Full verification
+
+**Files:** none (verification only).
+
+- [ ] **Step 1: Run the complete default suite**
+
+Run: `bundle exec rake`
+Expected: `task default: [:test, :spec, :rubocop]` runs all three — Minitest green (`0 failures`), RSpec green (`0 failures`), RuboCop `no offenses detected`.
+
+- [ ] **Step 2: Verify Zeitwerk naming for the new files**
+
+Run: `bundle exec rake zeitwerk:validate`
+Expected: `Zeitwerk: All files loaded successfully.` (confirms `lib/gempilot/origin.rb` → `Gempilot::Origin` and `lib/gempilot/release_tasks.rb` → `Gempilot::ReleaseTasks` load cleanly under eager load).
+
+- [ ] **Step 3: Confirm the working tree is clean and review the branch**
+
+Run: `git status` and `git log --oneline master..HEAD`
+Expected: clean working tree; commits for Origin, GithubRelease slim, release/unrelease move, and docs.
+
+---
+
+## Self-review notes (traceability to spec)
+
+- **Task hierarchy** (spec §"Task interface"/"Task definitions") → Task 3 (module + rewire) + Task 3 Step 1 structure specs.
+- **Bug fix — idempotent push replacing `already_tagged?`** (spec §"Problem"/`Origin`) → Task 1 (`Origin`, incl. real-remote idempotency regression test) + Task 3 `override_source_control_push`.
+- **`GithubRelease` slimmed** (spec §"Components") → Task 2.
+- **RubyGems reuses bundler leaf tasks** (spec §"Decisions") → Task 3 `define_rubygems_release` + prerequisite spec.
+- **`unrelease:rubygems` errors naturally** (spec §"Error handling") → covered by not defining it; documented, no code.
+- **Docs** (spec §"Docs") → Task 4.
+- **`Rakefile.erb` unchanged** (spec §"Out of scope") → no task; load order already correct.

data/docs/superpowers/specs/2026-07-20-release-task-hierarchy-design.md

@@ -0,0 +1,229 @@
+# Release task hierarchy — design
+
+**Issue:** `2C8EF3C8-83E9-11F1-9256-FE6CB9572C2F` — "gh release tasks need adjusting in task hierarchy"
+
+**Date:** 2026-07-20
+
+## Problem
+
+Gempilot installs GitHub release tasks under a bespoke `version:github:*` namespace
+(`version:github:release/unrelease/list`). Two things are wrong:
+
+1. **Wrong hierarchy.** GitHub publishing should live in the standard `release` /
+   `unrelease` namespace alongside RubyGems publishing, not in a custom
+   `version:github:*` corner.
+2. **GitHub releasing is broken.** The release flow bumps + commits + tags *locally*
+   via `version:release` (`version:tag` runs `git tag vX`). When the actual publish
+   runs through bundler's `release` task, bundler's `already_tagged?` guard sees the
+   tag already exists locally, prints *"Tag vX has already been created."*, and
+   **skips `release:source_control_push` entirely** — so the commit and tag never
+   reach the remote, and `gh release create vX` has nothing to attach to. This is the
+   "tags have already been pushed / doesn't work at all" symptom in the issue.
+
+This is an approved **breaking change**. No backwards compatibility for the old
+`version:github:*` tasks.
+
+## Decisions
+
+- **Namespace-only interface. No `[remote]` argument.** Target selection lives in the
+  task name (`release:github`), not an argument. This is the idiomatic Rake convention
+  (task name = what to do; argument = a value), and it avoids a direct collision:
+  `bundler/gem_tasks` already defines `task "release", [:remote]` where `remote` means
+  the *git remote name* (`origin`) passed to `git push`. Overloading that same word to
+  mean "publish target" is exactly what made the original `release[remote]` idea
+  confusing. So the final interface uses no argument at all.
+- **Bare `rake release` publishes to all remotes** (RubyGems + GitHub), expressed as a
+  pure prerequisite composite — no dispatcher code.
+- **Reuse bundler's building blocks for RubyGems.** `release:rubygems` composes
+  bundler's existing `build`, `release:guard_clean`, and `release:rubygem_push` leaf
+  tasks via prerequisites. No new object wraps them — this preserves `allowed_push_host`
+  (private gem servers), MFA/OTP prompts, and `gem_push=no`.
+- **Fix the bug by overriding the one task that is wrong.** Replace bundler's
+  `release:source_control_push` with an idempotent push (no `already_tagged?` guard),
+  done the same idiomatic way bundler does it: an explicit `git push <remote> <branch>`
+  then `git push <remote> <tag>`. Both remotes share this single task as a prerequisite,
+  so both get the fix and the push runs exactly once per release.
+- **Keep the local version lifecycle as-is.** `version:release` / `version:unrelease`
+  (local bump → commit → tag) are unchanged. The `version:` namespace and the top-level
+  `release` do not collide in Rake.
+
+## Task interface
+
+| Task | Behavior |
+| --- | --- |
+| `rake release` | Publish current version to all remotes (RubyGems + GitHub) |
+| `rake release:rubygems` | Build + push the gem to RubyGems |
+| `rake release:github` | Push commit + tag, then create the GitHub release |
+| `rake release:list:github` | List GitHub releases |
+| `rake unrelease` | Delete the release from all remotes that support it (GitHub) |
+| `rake unrelease:github` | Delete the GitHub release and remote tag |
+
+`rake unrelease:rubygems` is intentionally undefined — Rake fails with "Don't know how
+to build task", which is the correct signal that RubyGems yanking is out of scope.
+
+## Task definitions
+
+Defined in `Gempilot::VersionTask`, replacing the current `define_github_tasks`. Runs
+after `require "bundler/gem_tasks"` (guaranteed by the generated `Rakefile` and by
+gempilot's own `Rakefile`), so bundler's tasks exist when we override them. Each
+override is guarded with `task_defined?` so the definitions also work when bundler's
+gem tasks are absent (e.g. gempilot's own spec suite).
+
+```ruby
+# THE FIX: idempotent push, replacing bundler's already_tagged?-guarded task.
+Rake::Task["release:source_control_push"].clear if Rake::Task.task_defined?("release:source_control_push")
+task "release:source_control_push" do
+  Origin.new(project.version_tag).push
+end
+
+namespace :release do
+  desc "Release the current version to RubyGems"
+  task rubygems: %w[build release:guard_clean release:source_control_push release:rubygem_push]
+
+  desc "Create a GitHub release for the current version"
+  task github: "release:source_control_push" do
+    GithubRelease.new(project.version_tag).create
+  end
+
+  namespace :list do
+    desc "List GitHub releases"
+    task(:github) { GithubRelease.new(project.version_tag).list }
+  end
+end
+
+Rake::Task["release"].clear if Rake::Task.task_defined?("release")
+desc "Release the current version to all remotes"
+task release: %w[release:rubygems release:github]
+
+desc "Delete the current release from all remotes that support it"
+task unrelease: %w[unrelease:github]
+
+namespace :unrelease do
+  desc "Delete the GitHub release for the current version"
+  task(:github) { GithubRelease.new(project.version_tag).destroy }
+end
+```
+
+## Components
+
+### `Gempilot::Origin` (new — `lib/gempilot/origin.rb`)
+
+A small domain object (same style as the existing `GithubRelease` / `VersionTag`) that
+pushes the current branch and a given tag to the branch's configured git remote. This
+backs `release:source_control_push` and is the bug fix.
+
+- `initialize(tag)` — the version tag string (e.g. `"v1.0.0"`).
+- `#push` — runs, via `StrictShell#sh`:
+  - `git push <remote> refs/heads/<branch>`
+  - `git push <remote> refs/tags/<tag>`
+- `<branch>` = `git rev-parse --abbrev-ref HEAD`; `<remote>` = the branch's configured
+  remote (`git config --get branch.<branch>.remote`), defaulting to `origin` — mirroring
+  bundler's own `current_branch` / `default_remote` logic.
+- Idempotent: pushing an already-pushed branch/tag exits 0 ("Everything up-to-date"),
+  so re-running a release never fails on the tag. This is the property bundler's guard
+  broke.
+
+### `Gempilot::GithubRelease` (modified — `lib/gempilot/github_release.rb`)
+
+- `#create` drops its two internal `git push` / `git push --tags` lines. Pushing is now
+  `Origin`'s job (the `release:source_control_push` prerequisite runs first). `create`
+  becomes purely: `gh release create --generate-notes --fail-on-no-commits <tag>`.
+- `#destroy` and `#list` are unchanged.
+
+### `Gempilot::ReleaseTasks` (new — `lib/gempilot/release_tasks.rb`)
+
+The release / unrelease task definitions above, extracted into a focused module that is
+`include`d into `VersionTask`. This is a separate concern from the local version
+lifecycle, and extracting it keeps `VersionTask` under RuboCop's `Metrics/ClassLength`
+(the combined class would otherwise exceed the 100-line limit). All methods are private
+and parameterized by `project` (no reliance on the host's ivars beyond the single
+`define_release_tasks(project)` entry point).
+
+### `Gempilot::VersionTask` (modified — `lib/gempilot/version_task.rb`)
+
+- `include ReleaseTasks`.
+- Remove `define_github_tasks`; replace its call in `define_tasks` with
+  `define_release_tasks(@project)`.
+- `version:*` local lifecycle tasks and `version:release` / `version:unrelease`
+  composites are untouched.
+
+There is **no** `RubygemsRelease` object. RubyGems publishing is bundler-task
+composition only.
+
+## Data flow
+
+- `rake release:github` → `release:source_control_push` (push commit + tag) →
+  `gh release create`.
+- `rake release:rubygems` → `build` → `release:guard_clean` →
+  `release:source_control_push` (push commit + tag) → `release:rubygem_push` (gem push).
+- `rake release` → `release:rubygems` (which pushes during its chain), then
+  `release:github`. Rake invokes `release:source_control_push` once, so the git push
+  happens a single time, before both publishes.
+- `rake unrelease` → `unrelease:github` → `gh release delete --yes --cleanup-tag`
+  (removes the GitHub release and the remote tag).
+
+## Error handling
+
+- **Unsupported unrelease target** (`rake unrelease:rubygems`): undefined task → Rake's
+  native "Don't know how to build task" error. No custom code.
+- **Shell failures**: every git / gh / gem command runs through `StrictShell#sh`, which
+  already raises on non-zero exit.
+- **Tag / commit not pushable**: if the local tag does not exist, the `git push
+  refs/tags/<tag>` fails loudly via `StrictShell` — the correct signal to run
+  `version:release` first. No separate guard task is added (deliberate: the
+  `version:release` flow is responsible for producing a clean, tagged commit; adding a
+  bundler-independent `guard_clean` is out of scope).
+
+## Testing (TDD)
+
+Written before implementation.
+
+**`spec/gempilot/origin_spec.rb` (new)**
+- `#push` issues `git push <remote> <branch>` then `git push <remote> <tag>` in order
+  (stub `sh`, assert ordered calls; assert branch/remote resolution).
+- **Regression / integration**: in a tmpdir, create a real repo with a bare "origin"
+  remote and a tag, run `Origin#push`, assert the commit + tag land on origin; run it a
+  **second** time and assert it still succeeds (idempotent) — directly proving the bug
+  (bundler's guarded skip) is fixed.
+
+**`spec/gempilot/github_release_spec.rb` (modified)**
+- `#create` no longer calls `git push` / `git push --tags`; it calls only
+  `gh release create --generate-notes --fail-on-no-commits <tag>`.
+- `#destroy` and `#list` specs unchanged.
+
+**`spec/gempilot/version_task_spec.rb` (extended)**
+- **Structure**: `release`, `release:rubygems`, `release:github`, `release:list:github`,
+  `unrelease`, `unrelease:github` are defined; `version:github:release`,
+  `version:github:unrelease`, `version:github:list` are **not**.
+- **Composites by prerequisite** (no invocation needed): `release` prerequisites ==
+  `%w[release:rubygems release:github]`; `release:rubygems` prerequisites ==
+  `%w[build release:guard_clean release:source_control_push release:rubygem_push]`;
+  `unrelease` prerequisites == `%w[unrelease:github]`.
+- **Behavior by invocation** (stub `Origin` / `GithubRelease` constructors):
+  - `release:source_control_push` invokes `Origin#push`.
+  - `release:github` runs the push, then `GithubRelease#create`.
+  - `release:list:github` invokes `GithubRelease#list`.
+  - `unrelease:github` invokes `GithubRelease#destroy`.
+  - `release:rubygems` is asserted by prerequisites only (its bundler prerequisites are
+    absent in the spec's fresh Rake app, so it is not invoked there).
+
+## Docs
+
+- `README.md` — replace the three `version:github:*` rows in the tasks table with the
+  new `release` / `unrelease` tasks; update the `gempilot release` note to reflect that
+  bare `rake release` now publishes to all remotes.
+- `CLAUDE.md` — update the "Version lifecycle rake tasks" bullet: drop
+  `version:github:release/unrelease/list`, add `release` / `release:rubygems` /
+  `release:github` / `release:list:github` / `unrelease` / `unrelease:github`.
+
+## Out of scope
+
+- `data/templates/gem/Rakefile.erb` needs no change — it already requires
+  `bundler/gem_tasks` before `Gempilot::VersionTask.new`, which the override relies on.
+- The stale `rakelib/*` excludes in `data/templates/gem/dotfiles/rubocop.yml.erb`
+  (including `rakelib/github_release.rb`) belong to a separate open issue about internal
+  concerns leaking to gem users (`B45C988A`). Not touched here.
+- RubyGems yanking (`unrelease:rubygems`).
+- The `gempilot release` CLI command keeps proxying to `rake release`; its behavior
+  changes only because bare `rake release` now targets all remotes.
+- Any change to the local `version:*` lifecycle tasks.

data/issues.rec

@@ -101,7 +101,7 @@ Id: 0411D4DA-4323-11F1-847C-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 12:55:09 -0400
 Title: rubocop config should not exclude rakelib
 Description: it is supplied by gempilot. Should not be eliminating author files
-Status: open
+Status: closed
 
 Id: C72CD130-4324-11F1-ACAE-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 13:07:46 -0400
@@ -164,7 +164,51 @@ Description: Has to do with how the ENV var RM_INFO is being interpreted
 Status: open
 
 Id: 8D847572-7273-11F1-B508-FE6CB9572C2E
-Updated: Sat, 27 Jun 2026 18:00:04 -0400
+Updated: Fri, 03 Jul 2026 22:38:22 +0000
 Title: Gem extensions are broken
 Description: when using gempilot on a gem extension, like 'foo-support', using idiomatic ruby patterns for dir structure, gempilot Project class throws an error
-Status: open
+Status: closed
+
+Id: B45C988A-83C3-11F1-A32B-FE6CB9572C2F
+Updated: Sun, 19 Jul 2026 18:46:39 -0400
+Title: Gempilot internal concerns leak to gemusers
+Description: Gempilot fresh install leaks  the following in .rubocop.yml:
++ 
++ AllCops:
++   1   NewCops: enable
++   2   TargetRubyVersion: 4.0
++   3   Exclude:
++   4     - bin/*
++   5     - vendor/**/*
++   6     - lib/core_ext/**/*
++   7     - rakelib/project.rb
++   8     - rakelib/project_version.rb
++   9
+Status: closed
+
+Id: 2C8EF3C8-83E9-11F1-9256-FE6CB9572C2F
+Updated: Sun, 19 Jul 2026 23:14:52 -0400
+Title: gh release tasks need adjusting in task heirarchy
+Description: the github release related tasks are invoked as follows:
++ ```
++ rake version:github:release
++ rake version:github:list
++ rake version:github:unrelease
++ 
++ ```
++ they should instead be under the main idiomatic release namespace:
++ 
++ ```
++ rake release[remote] # release to the remote, e.g. rubygems/github
++ rake release:github # alternative to rake release[github]
++ rake unrelease[remote] # currently only supported for github, not rubygems
++ rake unrelease:github # alternative to rake unrelease[github]
++ rake release:list:github # list GitHub releases
++ rake release:
++ ```
++ where remote is "github"
++ 
++ Note that this is a breaking change, and it is approved. Do not provide backwards compatibility for the old tasks. Move forward
++ 
++ Also, there is an issue that prevents github releasing from working at all via the old tasks. I get an error every time saying that "tags have already been pushed" or something along those lines. Ensure that is fixed as well
+Status: closed

data/lib/gempilot/github_release.rb

@@ -10,8 +10,6 @@ module Gempilot
     end
 
     def create
-      sh "git", "push"
-      sh "git", "push", "--tags"
       sh "gh", "release", "create",
          "--generate-notes", "--fail-on-no-commits",
          tag

data/lib/gempilot/origin.rb

@@ -0,0 +1,52 @@
+require "open3"
+
+module Gempilot
+  ## Pushes the current branch and a release tag to the branch's git remote.
+  ## Backs the +release:source_control_push+ task. Idempotent: pushing an
+  ## already-pushed branch or tag is a no-op, so re-running a release never
+  ## fails on an existing tag (unlike bundler's +already_tagged?+ guard, which
+  ## skips the push entirely once the tag exists locally).
+  class Origin
+    include StrictShell
+
+    attr_reader :tag
+
+    def initialize(tag)
+      @tag = tag
+    end
+
+    def push
+      sh "git", "push", remote, "refs/heads/#{branch}"
+      sh "git", "push", remote, "refs/tags/#{tag}"
+    end
+
+    private
+
+    def branch
+      @branch ||= resolve_branch
+    end
+
+    def resolve_branch
+      name = capture("git", "rev-parse", "--abbrev-ref", "HEAD")
+      raise "Cannot push from a detached HEAD; check out a branch first" if name == "HEAD"
+
+      name
+    end
+
+    def remote
+      @remote ||= configured_remote || "origin"
+    end
+
+    def configured_remote
+      out, status = Open3.capture2("git", "config", "--get", "branch.#{branch}.remote")
+      out.strip if status.success?
+    end
+
+    def capture(*args)
+      out, status = Open3.capture2(*args)
+      raise "Command #{args.join(" ").inspect} failed (exit #{status.exitstatus})" unless status.success?
+
+      out.strip
+    end
+  end
+end

data/lib/gempilot/release_tasks.rb

@@ -0,0 +1,73 @@
+module Gempilot
+  ## Rake task definitions for publishing a release to RubyGems and GitHub.
+  ## Mixed into VersionTask. Assumes +bundler/gem_tasks+ has been required so the
+  ## +build+, +release:guard_clean+, and +release:rubygem_push+ tasks exist (the
+  ## generated Rakefile guarantees this). Fixes GitHub releasing by replacing
+  ## bundler's +already_tagged?+-guarded +release:source_control_push+ with an
+  ## idempotent push.
+  module ReleaseTasks
+    private
+
+    def define_release_tasks(project)
+      override_source_control_push(project)
+      define_release_namespace(project)
+      define_root_release_task
+      define_unrelease_tasks(project)
+    end
+
+    def override_source_control_push(project)
+      clear_task "release:source_control_push"
+      task("release:source_control_push") { Origin.new(project.version_tag).push }
+    end
+
+    def define_release_namespace(project)
+      namespace :release do
+        define_rubygems_release
+        define_github_release(project)
+        define_release_list(project)
+      end
+    end
+
+    def define_rubygems_release
+      desc "Release the current version to RubyGems"
+      task rubygems: %w[build release:guard_clean release:source_control_push release:rubygem_push]
+    end
+
+    def define_github_release(project)
+      desc "Create a GitHub release for the current version"
+      task github: "release:source_control_push" do
+        GithubRelease.new(project.version_tag).create
+      end
+    end
+
+    def define_release_list(project)
+      namespace :list do
+        desc "List GitHub releases"
+        task(:github) { GithubRelease.new(project.version_tag).list }
+      end
+    end
+
+    def define_root_release_task
+      clear_task "release"
+      desc "Release the current version to all remotes"
+      task release: %w[release:rubygems release:github]
+    end
+
+    def define_unrelease_tasks(project)
+      desc "Delete the current release from all remotes that support it"
+      task unrelease: %w[unrelease:github]
+      define_unrelease_namespace(project)
+    end
+
+    def define_unrelease_namespace(project)
+      namespace :unrelease do
+        desc "Delete the GitHub release for the current version"
+        task(:github) { GithubRelease.new(project.version_tag).destroy }
+      end
+    end
+
+    def clear_task(name)
+      Rake::Task[name].clear if Rake::Task.task_defined?(name)
+    end
+  end
+end

data/lib/gempilot/version.rb

@@ -1,3 +1,3 @@
 module Gempilot
-  VERSION = "0.2.3".freeze
+  VERSION = "0.2.4".freeze
 end

data/lib/gempilot/version_task.rb

@@ -4,6 +4,8 @@ require_relative "../gempilot"
 module Gempilot
   ## Rake tasks for version lifecycle management.
   class VersionTask < Rake::TaskLib
+    include ReleaseTasks
+
     attr_reader :project
 
     def initialize(root: Dir.pwd)
@@ -17,7 +19,7 @@ module Gempilot
     def define_tasks
       define_version_tasks
       define_version_composite_tasks
-      define_github_tasks
+      define_release_tasks(@project)
     end
 
     def define_version_tasks
@@ -89,20 +91,5 @@ module Gempilot
         project.refresh_version!
       end
     end
-
-    def define_github_tasks
-      project = @project
-
-      namespace "version:github" do
-        desc "Create a GitHub release for the current version"
-        task(:release) { GithubRelease.new(project.version_tag).create }
-
-        desc "Delete the GitHub release for the current version"
-        task(:unrelease) { GithubRelease.new(project.version_tag).destroy }
-
-        desc "List GitHub releases"
-        task(:list) { GithubRelease.new(project.version_tag).list }
-      end
-    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gempilot
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - David Gillis
@@ -106,6 +106,8 @@ files:
 - data/templates/gem/test/zeitwerk_test.rb.erb
 - data/templates/new/.keep
 - data/templates/new/command.rb.erb
+- docs/superpowers/plans/2026-07-20-release-task-hierarchy.md
+- docs/superpowers/specs/2026-07-20-release-task-hierarchy-design.md
 - exe/gempilot
 - issues.rec
 - lib/core_ext/string/inflection_methods.rb
@@ -124,8 +126,10 @@ files:
 - lib/gempilot/cli/generator.rb
 - lib/gempilot/gem_constant.rb
 - lib/gempilot/github_release.rb
+- lib/gempilot/origin.rb
 - lib/gempilot/project.rb
 - lib/gempilot/project/version.rb
+- lib/gempilot/release_tasks.rb
 - lib/gempilot/strict_shell.rb
 - lib/gempilot/version.rb
 - lib/gempilot/version_tag.rb
@@ -151,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A toolkit for creating, managing, and releasing your own rubygems
 test_files: []