gempilot 0.3.1 → 0.3.2

data/docs/superpowers/plans/2026-09-23-land-betterleaks-jruby.md

@@ -0,0 +1,262 @@
+# Land the betterleaks-jruby Branch 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:** Bring `origin/betterleaks-jruby` — which already implements issues `986E0100` (MRI-only dev gems) and `3FFE7616` (betterleaks integration), with its own approved design spec and plan committed on the branch — onto today's master, and get it merged. Nothing is re-planned here; the feature work is done.
+
+**Architecture:** The branch is 10 commits from 2026-07-26 (design spec, plan, `platforms :mri` block in gempilot's Gemfile, `Gempilot::BetterleaksTask`, hook and `secrets.yml` templates, `--[no-]betterleaks` on `create`, a `gempilot setup betterleaks` retrofit command, dogfooding, issue closures) plus one Aug 7 commit filing issue `F7C6A9AA`. Master moved since (dev-version-bump merge, the `json` pin), so merging master into the branch produces exactly one conflict (`CLAUDE.md`; `issues.rec` auto-merges), and master's own `json`-ordering regression must be fixed for the gate to go green. The branch's published history is never rewritten and nothing in this plan pushes. Verified 2026-09-23 in a scratch copy: after the merge, that one-line fix, and Task 3, the full gate is `122 runs, 0 failures`, `205 examples, 0 failures`, `69 files inspected, no offenses`.
+
+**Tech Stack:** git rebase, GNU recutils (`recset`, `recsel`, `recfix`) for `issues.rec`, `bundle exec rake default`.
+
+**Issues:** `986E0100-88F4-11F1-B718-FE6CB9572C2D`, `3FFE7616-88F5-11F1-8D3B-FE6CB9572C2D` (both closed by the branch's own `issues.rec` commit).
+
+## Global Constraints
+
+- Do not redesign anything on the branch; its spec (`docs/superpowers/specs/2026-07-26-betterleaks-and-jruby-design.md` on the branch) is marked approved. Notable decisions it made: the hook and `rake betterleaks` skip with an install hint when the binary is missing (fail open; CI enforces), CI is a separate `secrets.yml` using `go install github.com/betterleaks/betterleaks@latest`, and Issue A scopes `platforms :mri` to gempilot's own Gemfile only.
+- Master's uncommitted working-tree change to `issues.rec` (closing `2360FFA4`) is separate from this branch; commit it on master before or after, never inside the rebase.
+- Commit messages: plain imperative sentences, no conventional-commit prefixes.
+- `bundle install` cannot materialize master's lockfile on machines without the author's vault (rake 13.4.3); run the gate where the bundle already works.
+
+---
+
+### Task 1: Restore alphabetical order in the Gemfile template
+
+**Files:**
+- Modify: `data/templates/gem/Gemfile.erb:5-7`
+
+**Interfaces:**
+- Produces: a template whose `gem` lines are sorted; four master tests go green (`test_gemfile_gems_are_alphabetically_ordered`, its rspec twin, and both `*_default_rake_task_passes` integration tests, which fail today because the generated gem's RuboCop reports `Gemfile:6 Bundler/OrderedGems`).
+
+- [ ] **Step 1: See the failures on master**
+
+Run: `bundle exec ruby -Itest -Ilib test/gempilot/cli/create_command_test.rb -n "/gemfile/i"`
+Expected: `4 runs, ... 2 failures`, actual list starting `["json", "gempilot", "irb", ...]`.
+
+- [ ] **Step 2: Move the json line**
+
+Replace the top of `data/templates/gem/Gemfile.erb` (everything above the first `<% if` line) with:
+
+```erb
+source "https://rubygems.org"
+
+gemspec
+
+gem "gempilot", require: false
+gem "irb"
+gem "json", "~> 2.21" # temporary json 3.0.0 is currently breaking everything
+```
+
+- [ ] **Step 3: Verify and commit on master**
+
+Run: `bundle exec ruby -Itest -Ilib test/gempilot/cli/create_command_test.rb`
+Expected: `53 runs, 0 failures`.
+
+```bash
+git add data/templates/gem/Gemfile.erb
+git commit -m "Restore alphabetical order in the Gemfile template"
+```
+
+(Open this as its own one-commit PR, or fold it in as the first commit of the rebased branch; either way it must precede Task 3's gate.)
+
+---
+
+### Task 2: Merge master into the branch
+
+No rebase and no force-push: the branch's published history stays as it is, master is merged in, and the merge commit is what gets pushed later, normally.
+
+**Files:**
+- Conflict to resolve: `CLAUDE.md` (once). `issues.rec` auto-merges.
+
+**Interfaces:**
+- Consumes: `origin/betterleaks-jruby`, master with Task 1.
+- Produces: local branch `betterleaks-jruby` = its 11 commits + one merge commit, no conflict markers, `recfix` clean.
+
+- [ ] **Step 1: Start the merge**
+
+```bash
+git fetch origin
+git checkout betterleaks-jruby
+git merge master
+```
+
+Expected: `Auto-merging issues.rec` succeeds; `Automatic merge failed` only because of `CLAUDE.md` (`git diff --name-only --diff-filter=U` prints exactly `CLAUDE.md`).
+
+- [ ] **Step 2: Check the auto-merged issues.rec**
+
+```bash
+recfix issues.rec
+recsel -e "Status = 'open'" -P Id issues.rec
+```
+
+Expected: `recfix` is silent; the open list no longer contains `986E0100` or `3FFE7616` and does contain `F7C6A9AA` (the branch's new issue, "gempilot new class WebSocket::Server should respect zeitwerk inflectors if present") alongside master's issues.
+
+- [ ] **Step 3: Resolve CLAUDE.md**
+
+The conflict is the Commands list. Keep master's `gempilot bump` line (it mentions `tiny/dev`; the branch's copy is stale) and the branch's new `gempilot setup` line, so the resolved lines read:
+
+```markdown
+- `gempilot setup` — Retrofit an integration (e.g. betterleaks) into an existing gem
+- `gempilot bump` — Bump version in `version.rb` (patch default, or minor/major/tiny/dev)
+```
+
+Remove the conflict markers and the stale `(patch default, or minor/major)` line. `grep -c "gempilot bump" CLAUDE.md` must print `1`.
+
+- [ ] **Step 4: Commit the merge**
+
+```bash
+git add CLAUDE.md
+git commit -m "Merge master into betterleaks-jruby"
+```
+
+Expected: `git log --oneline master..HEAD | wc -l` prints `12` (11 branch commits + the merge); `git diff master -- CLAUDE.md issues.rec` shows only the `gempilot setup` bullet and the branch's Generated Gem Features additions, the two status flips, and the `F7C6A9AA` record.
+
+---
+
+### Task 3: Port three mechanics from the September spike
+
+The branch's design stands. Three details verified in the September rework are strictly better and small enough to land in the same PR (verified 2026-09-23 on the rebased branch: gate `122 runs`, `205 examples`, `69 files`, all green):
+
+1. `rake betterleaks` runs `betterleaks git` unconditionally, so in a gem scaffolded with `--no-git` it dies with `fatal: not a git repository`. Fall back to `betterleaks dir` outside a work tree, and pass `--no-banner`.
+2. `secrets.yml` compiles betterleaks from source on every CI run (`actions/setup-go` + `go install ...@latest`, a floating version). Install the pinned 1.8.1 release tarball and verify it against the release's `checksums.txt` instead (download + checksum verified locally; the linux_x64 binary runs on GitHub's ubuntu runners).
+3. The task spec only covers the "not installed" skip path. Add real-scan examples: a clean history passes, a randomly generated GitHub token fails the task, and a non-git directory scans without crashing.
+
+**Files:**
+- Modify: `lib/gempilot/betterleaks_task.rb`
+- Modify: `data/templates/gem/dotfiles/github/workflows/secrets.yml`, `.github/workflows/secrets.yml`
+- Test: `spec/gempilot/betterleaks_task_spec.rb`
+
+**Interfaces:**
+- Consumes: `Gempilot::BetterleaksTask` as defined on the branch (`task :betterleaks`, `warn_missing`).
+- Produces: the same task name; `scan` chooses `git` or `dir` mode; both workflow files share one install step.
+
+- [ ] **Step 1: Add the failing spec examples**
+
+In `spec/gempilot/betterleaks_task_spec.rb` add `require "securerandom"` after `require "spec_helper"`, and before the file's final `end` add:
+
+```ruby
+  describe "a real scan" do
+    around { |example| Dir.mktmpdir("betterleaks_task_spec") { |dir| Dir.chdir(dir) { example.run } } }
+
+    before { skip "betterleaks is not installed" unless system("betterleaks", "version", out: File::NULL) }
+
+    def commit_file(name, content)
+      system("git", "init", "--quiet", "-b", "main", ".")
+      system("git", "config", "user.email", "test@test.com")
+      system("git", "config", "user.name", "Test")
+      File.write(name, content)
+      system("git", "add", name)
+      system("git", "commit", "--quiet", "-m", "Add #{name}")
+    end
+
+    it "passes on a history without secrets" do
+      commit_file("app.rb", "puts 'hi'\n")
+      expect { Rake::Task["betterleaks"].invoke }.not_to raise_error
+    end
+
+    it "fails when the history contains a secret" do
+      commit_file("config.rb", %(github_token = "ghp_#{SecureRandom.alphanumeric(36)}"\n))
+      expect { Rake::Task["betterleaks"].invoke }.to raise_error(RuntimeError, /betterleaks/)
+    end
+
+    it "scans the working tree when the gem is not a git repository" do
+      File.write("app.rb", "puts 'hi'\n")
+      expect { Rake::Task["betterleaks"].invoke }.not_to raise_error
+    end
+  end
+```
+
+(The token is random on purpose: betterleaks filters keyboard-walk "example" strings, so a fixed fake key is not detected.)
+
+- [ ] **Step 2: Run it to verify the last example fails**
+
+Run: `bundle exec rspec spec/gempilot/betterleaks_task_spec.rb --no-color`
+Expected: `5 examples, 1 failure` — "scans the working tree when the gem is not a git repository" raises `Command failed with status (1)` because `betterleaks git` errors outside a repository; the secret example already fails the task as expected.
+
+- [ ] **Step 3: Choose the scan mode**
+
+In `lib/gempilot/betterleaks_task.rb` replace `scan` and `betterleaks_available?` with:
+
+```ruby
+    def scan
+      return warn_missing unless betterleaks_available?
+
+      sh "betterleaks", mode, "--no-banner", "--redact", "--verbose", "."
+    end
+
+    # git mode walks the whole commit history; outside a work tree (a gem
+    # scaffolded with --no-git) dir mode scans the files on disk instead of
+    # failing on the missing repository.
+    def mode
+      git_work_tree? ? "git" : "dir"
+    end
+
+    def git_work_tree?
+      system("git", "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL)
+    end
+
+    def betterleaks_available?
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+        binary = File.join(dir, "betterleaks")
+        File.file?(binary) && File.executable?(binary)
+      end
+    end
+```
+
+- [ ] **Step 4: Pin the CI install**
+
+In both `data/templates/gem/dotfiles/github/workflows/secrets.yml` and `.github/workflows/secrets.yml`, replace the three steps `Set up Go`, `Install betterleaks`, `Scan for secrets` with:
+
+```yaml
+    - name: Install betterleaks
+      env:
+        BETTERLEAKS_VERSION: 1.8.1
+      run: |
+        cd "$(mktemp -d)"
+        base="https://github.com/betterleaks/betterleaks/releases/download/v${BETTERLEAKS_VERSION}"
+        asset="betterleaks_${BETTERLEAKS_VERSION}_linux_x64.tar.gz"
+        curl -sSfL -O "${base}/${asset}" -O "${base}/checksums.txt"
+        grep "  ${asset}\$" checksums.txt | sha256sum --check
+        tar -xzf "${asset}" betterleaks
+        sudo install -m 0755 betterleaks /usr/local/bin/betterleaks
+    - name: Scan for secrets
+      run: betterleaks git --no-banner --redact --verbose
+```
+
+The `checkout` step keeps `fetch-depth: 0`. No test references the Go steps (`grep -rn "go install\|setup-go" test spec` prints nothing).
+
+- [ ] **Step 5: Run the spec and rubocop, then commit**
+
+Run: `bundle exec rspec spec/gempilot/betterleaks_task_spec.rb --no-color && bundle exec rubocop lib/gempilot/betterleaks_task.rb spec/gempilot/betterleaks_task_spec.rb`
+Expected: `5 examples, 0 failures`; `2 files inspected, no offenses detected`.
+
+```bash
+git add lib/gempilot/betterleaks_task.rb spec/gempilot/betterleaks_task_spec.rb data/templates/gem/dotfiles/github/workflows/secrets.yml .github/workflows/secrets.yml
+git commit -m "Scan non-git gems in dir mode and pin the CI betterleaks install"
+```
+
+---
+
+### Task 4: Gate, push, PR
+
+**Files:**
+- None modified.
+
+- [ ] **Step 1: Full gate**
+
+Run: `bundle exec rake default 2>&1 | tail -12`
+Expected: minitest `122 runs, 0 failures`, RSpec `205 examples, 0 failures`, RuboCop `69 files inspected, no offenses detected`. (The branch's `rake betterleaks` is not part of `default`; with the binary absent its spec prints the install hint and passes.)
+
+- [ ] **Step 2: Smoke the retrofit and the scaffold**
+
+From a scratch directory, with `<repo>` your checkout:
+
+```bash
+<repo>/exe/gempilot create --author A --email a@b.c --summary s --ruby-version 4.0.6 --test minitest --no-exe --git --branch master --betterleaks hooked_gem
+cd hooked_gem && git config core.hooksPath && ls -l .githooks/pre-commit .github/workflows/secrets.yml
+```
+
+Expected: `.githooks`, an executable hook, and the workflow file. Then in any older generated gem, `<repo>/exe/gempilot setup betterleaks` twice: the second run reports `skip` for every step.
+
+- [ ] **Step 3: Stop and hand off**
+
+The plan ends here. Do not push. PR #21 ("Add betterleaks secret scanning + make dev gems JRuby-safe", opened 2026-07-26) already tracks this branch; the merge commit and the Task 3 commit are fast-forward additions to it, so a plain `git push origin betterleaks-jruby` by David updates the PR with no history rewrite. An agent executing this plan reports the green gate and leaves the push to him.

data/docs/superpowers/plans/2026-09-23-multi-gem-rubygems-push.md

@@ -0,0 +1,318 @@
+# Multi-Gem RubyGems Push 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:** Make `rake release:rubygems` push every gem in `pkg/` that belongs to the version being released (the plain gem plus any platform gems), and abort when there is none, instead of inheriting bundler's `release:rubygem_push`, which pushes exactly one file.
+
+**Architecture:** gempilot takes ownership of `release:rubygem_push` the same way it already owns `release:source_control_push`: `ReleaseTasks` clears bundler's task and redefines it (still depending on `build`) to call a new `Gempilot::RubygemsRelease`, a small `StrictShell` collaborator in the style of `GithubRelease`/`Origin`. `RubygemsRelease` derives the package list from what `Project` already knows (`name`, `version_value`, `root`) with a version-scoped brace glob, so `my_gem-1.2.30.gem` and `my_gem-1.2.3.1.gem` left over in `pkg/` are never re-pushed. The prerequisite chain of `release:rubygems` (`build`, `release:guard_clean`, `release:source_control_push`, `release:rubygem_push`) is unchanged.
+
+**Tech Stack:** Ruby 4.0, Rake (`Rake::Task#clear`, task prerequisites), `Pathname#glob` with `{a,b}` braces, RSpec with `instance_double` and `have_received(...).ordered`.
+
+**Issue:** `F6C6EB04-8DA4-11F1-91EF-FA41C3164F3A` — "release:rubygem_push only handles one gem per version".
+
+## Global Constraints
+
+- Ruby `>= 4.0`; `it` block parameter is fine.
+- Double-quoted strings (`Style/StringLiterals: double_quotes`); NO `# frozen_string_literal:` comments; trailing commas in multiline literals/arguments.
+- rdoc doc blocks in canonical form (a bare `##` line, then `# ...` lines; never a comment line that reads like code — `Claude/NoCommentedCode`).
+- Zeitwerk: new file `lib/gempilot/rubygems_release.rb` MUST define `Gempilot::RubygemsRelease` (`spec/zeitwerk_spec.rb` eager-loads gempilot).
+- Out of scope, deliberately: bundler's `gem_push=no` environment switch and its `--key`/`--host` options are not reproduced (gempilot's `release:github` is the way to skip RubyGems; nothing in the templates sets `allowed_push_host`).
+- `gem push` needs an interactive OTP prompt when `rubygems_mfa_required` is set; `StrictShell#sh` runs through `Kernel#system`, so stdin is inherited and the prompt works.
+- Verification: `bundle exec rspec <files>` for focused runs, `bundle exec rubocop <files>` per task, `bundle exec rake default` for the full gate.
+- Baseline (verified 2026-09-23): RSpec `192 examples, 0 failures`; RuboCop no offenses; minitest `109 runs, 4 failures` — the 4 are the Gemfile-template ordering regression fixed by Task 1 of `docs/superpowers/plans/2026-09-23-land-betterleaks-jruby.md`; apply that one-line change first for a fully green gate. Final state after this plan: RSpec `199 examples, 0 failures`, minitest unchanged.
+- Commit messages: plain imperative sentences, no conventional-commit prefixes.
+
+---
+
+### Task 1: `Gempilot::RubygemsRelease`
+
+**Files:**
+- Create: `lib/gempilot/rubygems_release.rb`
+- Test: `spec/gempilot/rubygems_release_spec.rb`
+
+**Interfaces:**
+- Consumes: `Gempilot::StrictShell#sh` (raises on non-zero exit), `Project#name`, `Project#version_value`, `Project#root` (Pathname).
+- Produces: `Gempilot::RubygemsRelease.new(project) -> RubygemsRelease`, `#push -> void` (runs `gem push <path>` for each package in sorted order; raises `RuntimeError` "No packages for <name> <version> found in pkg/; run rake build first" when there is none). Task 2 relies on `RubygemsRelease.new(project).push`.
+
+- [ ] **Step 1: Write the failing spec**
+
+Create `spec/gempilot/rubygems_release_spec.rb`:
+
+```ruby
+require "spec_helper"
+
+RSpec.describe Gempilot::RubygemsRelease do
+  let(:project) { Gempilot::Project.new(Dir.pwd) }
+  let(:release) { described_class.new(project) }
+  let(:no_packages_error) { %r{No packages for my_gem 1\.2\.3 found in pkg/; run rake build first} }
+
+  around do |example|
+    Dir.mktmpdir("rubygems_release_spec") { |dir| Dir.chdir(dir) { example.run } }
+  end
+
+  before do
+    Pathname("lib/my_gem").mkpath
+    File.write "lib/my_gem.rb", "module MyGem; end\n"
+    File.write "lib/my_gem/version.rb", <<~RUBY
+      module MyGem
+        VERSION = "1.2.3".freeze
+      end
+    RUBY
+    allow(release).to receive(:sh)
+  end
+
+  def package(*names)
+    Pathname("pkg").mkpath
+    names.each { FileUtils.touch("pkg/#{it}") }
+  end
+
+  def pkg(name)
+    project.root.join("pkg", name).to_s
+  end
+
+  describe "#push" do
+    it "pushes the plain gem of the current version" do
+      package "my_gem-1.2.3.gem"
+      release.push
+      expect(release).to have_received(:sh).with("gem", "push", pkg("my_gem-1.2.3.gem"))
+    end
+
+    it "pushes every gem of the current version in sorted order", :aggregate_failures do
+      package "my_gem-1.2.3.gem", "my_gem-1.2.3-x86_64-linux.gem", "my_gem-1.2.3-arm64-darwin.gem"
+      release.push
+      expect(release).to have_received(:sh).with("gem", "push", pkg("my_gem-1.2.3-arm64-darwin.gem")).ordered
+      expect(release).to have_received(:sh).with("gem", "push", pkg("my_gem-1.2.3-x86_64-linux.gem")).ordered
+      expect(release).to have_received(:sh).with("gem", "push", pkg("my_gem-1.2.3.gem")).ordered
+    end
+
+    context "when pkg also holds other versions and other gems" do
+      before { package "my_gem-1.2.3.gem", "my_gem-1.2.30.gem", "my_gem-1.2.3.1.gem", "other-1.2.3.gem" }
+
+      it "pushes only the gems of the current version", :aggregate_failures do
+        release.push
+        expect(release).to have_received(:sh).with("gem", "push", pkg("my_gem-1.2.3.gem"))
+        expect(release).to have_received(:sh).once
+      end
+    end
+
+    it "raises without pushing when pkg holds no gem of the current version", :aggregate_failures do
+      package "my_gem-1.2.30.gem"
+      expect { release.push }.to raise_error(RuntimeError, no_packages_error)
+      expect(release).not_to have_received(:sh)
+    end
+
+    it "raises when pkg does not exist" do
+      expect { release.push }.to raise_error(RuntimeError, no_packages_error)
+    end
+  end
+end
+```
+
+(The error regex is a named `let` because `Claude/MysteryRegex` rejects long inline regexes.)
+
+- [ ] **Step 2: Run it to verify it fails**
+
+Run: `bundle exec rspec spec/gempilot/rubygems_release_spec.rb --no-color`
+Expected: FAIL to load — `NameError: uninitialized constant Gempilot::RubygemsRelease`.
+
+- [ ] **Step 3: Create the class**
+
+Create `lib/gempilot/rubygems_release.rb`:
+
+```ruby
+module Gempilot
+  ##
+  # Pushes every gem of the version being released to RubyGems. Backs the
+  # +release:rubygem_push+ task in place of bundler's, which pushes only the
+  # single gem its own +build+ task produced. A project that builds several
+  # gems per version (platform gems carrying a compiled executable alongside
+  # the plain ruby gem) needs all of them pushed, so this globs +pkg/+ for the
+  # packages of that version: <tt>name-version.gem</tt> and
+  # <tt>name-version-platform.gem</tt>. The glob is scoped to the exact version
+  # because +pkg/+ is never emptied between releases; a looser
+  # <tt>name-version*.gem</tt> would also sweep up <tt>name-1.2.30.gem</tt> and
+  # <tt>name-1.2.3.1.gem</tt> and re-push versions already on RubyGems. Finding
+  # no package at all aborts the release, since a release that published
+  # nothing must not report success.
+  class RubygemsRelease
+    include StrictShell
+
+    attr_reader :project
+
+    def initialize(project)
+      @project = project
+    end
+
+    def push
+      paths = packages
+      raise "No packages for #{name_and_version} found in pkg/; run rake build first" if paths.empty?
+
+      paths.each { sh "gem", "push", it.to_s }
+    end
+
+    private
+
+    def name_and_version
+      "#{project.name} #{project.version_value}"
+    end
+
+    def packages
+      stem = "#{project.name}-#{project.version_value}"
+      project.root.glob("pkg/{#{stem}.gem,#{stem}-*.gem}").sort
+    end
+  end
+end
+```
+
+`Pathname#glob` delegates to `Dir.glob`, which expands `{a,b}` braces by default (verified: for stem `foo-0.3.0` the pattern matches `foo-0.3.0.gem` and `foo-0.3.0-x86_64-linux.gem` and not `foo-0.3.10.gem` or `foo-0.3.0.1.gem`). `Project#root` is a `Pathname`, so the results are absolute `Pathname`s; `sh` gets them as strings. Keep the `.sort`: `Dir.glob` returns the first brace alternative's matches before the second's, so without it the plain gem would come first and the sorted-order example would fail. A missing `pkg/` directory simply globs to `[]`, which is why "raises when pkg does not exist" needs no extra code.
+
+- [ ] **Step 4: Run the spec and rubocop**
+
+Run: `bundle exec rspec spec/gempilot/rubygems_release_spec.rb spec/zeitwerk_spec.rb --no-color && bundle exec rubocop lib/gempilot/rubygems_release.rb spec/gempilot/rubygems_release_spec.rb`
+Expected: `6 examples, 0 failures`; `2 files inspected, no offenses detected`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/gempilot/rubygems_release.rb spec/gempilot/rubygems_release_spec.rb
+git commit -m "Add RubygemsRelease to push every gem of a version"
+```
+
+---
+
+### Task 2: Own `release:rubygem_push`
+
+**Files:**
+- Modify: `lib/gempilot/release_tasks.rb`
+- Test: `spec/gempilot/version_task_spec.rb`
+
+**Interfaces:**
+- Consumes: `RubygemsRelease.new(project).push` (Task 1), `ReleaseTasks#clear_task`, Rake DSL `task`.
+- Produces: task `release:rubygem_push` with prerequisites exactly `["build"]`, whose action is `RubygemsRelease.new(project).push`; bundler's action for that task is cleared. `release:rubygems`'s prerequisite chain is unchanged.
+
+- [ ] **Step 1: Add the failing examples**
+
+In `spec/gempilot/version_task_spec.rb`, inside `describe "release task hierarchy"`, after the example "builds release:rubygems from bundler's own tasks", add:
+
+```ruby
+    it "builds before pushing to RubyGems" do
+      expect(Rake::Task["release:rubygem_push"].prerequisites).to eq(["build"])
+    end
+```
+
+Inside `describe "release task behavior"`, extend the doubles:
+
+```ruby
+    let(:origin) { instance_double(Gempilot::Origin, push: nil) }
+    let(:github) { instance_double(Gempilot::GithubRelease, create: nil, destroy: nil, list: nil) }
+    let(:rubygems) { instance_double(Gempilot::RubygemsRelease, push: nil) }
+
+    before do
+      allow(Gempilot::Origin).to receive(:new).and_return(origin)
+      allow(Gempilot::GithubRelease).to receive(:new).and_return(github)
+      allow(Gempilot::RubygemsRelease).to receive(:new).and_return(rubygems)
+    end
+```
+
+and, after the example "release:source_control_push pushes via Origin", add:
+
+```ruby
+    it "release:rubygem_push pushes every package via RubygemsRelease" do
+      Rake::Task["release:rubygem_push"].execute
+      expect(rubygems).to have_received(:push)
+    end
+```
+
+(`execute` rather than `invoke`: this spec does not load `bundler/gem_tasks`, so the `build` prerequisite does not exist in its Rake application; `execute` runs the action without prerequisites.)
+
+- [ ] **Step 2: Run to verify the new examples fail**
+
+Run: `bundle exec rspec spec/gempilot/version_task_spec.rb --no-color`
+Expected: `16 examples, 2 failures` — "builds before pushing to RubyGems" fails with `Don't know how to build task 'release:rubygem_push'` (no such task without bundler), and the behavior example fails the same way.
+
+- [ ] **Step 3: Define the task in ReleaseTasks**
+
+In `lib/gempilot/release_tasks.rb`, replace the module doc block and `define_release_tasks`, and add `define_rubygem_push` right after `override_source_control_push`:
+
+```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+ and +release:guard_clean+ tasks exist (the generated Rakefile
+  # guarantees this). Replaces two of bundler's release steps: its
+  # +already_tagged?+-guarded +release:source_control_push+ with an idempotent
+  # push, and its single-gem +release:rubygem_push+ with RubygemsRelease, which
+  # pushes every gem in +pkg/+ built for the released version.
+  module ReleaseTasks
+    private
+
+    def define_release_tasks(project)
+      override_source_control_push(project)
+      define_rubygem_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_rubygem_push(project)
+      clear_task "release:rubygem_push"
+      task("release:rubygem_push" => "build") { RubygemsRelease.new(project).push }
+    end
+```
+
+Everything from `define_release_namespace` down is unchanged. `Rake::Task#clear` drops bundler's prerequisites and action but keeps the task registered, so redefining it with `=> "build"` yields the same single prerequisite the spec pins.
+
+- [ ] **Step 4: Run the spec and rubocop, then the full gate**
+
+Run: `bundle exec rspec spec/gempilot/version_task_spec.rb spec/gempilot/rubygems_release_spec.rb --no-color && bundle exec rubocop lib/gempilot/release_tasks.rb spec/gempilot/version_task_spec.rb`
+Expected: `21 examples, 0 failures`; `2 files inspected, no offenses detected`.
+
+Run: `bundle exec rake default 2>&1 | tail -8`
+Expected: RSpec `199 examples, 0 failures`, RuboCop no offenses, minitest as in the baseline.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/gempilot/release_tasks.rb spec/gempilot/version_task_spec.rb
+git commit -m "Push every gem of the released version to RubyGems"
+```
+
+---
+
+### Task 3: Documentation
+
+**Files:**
+- Modify: `README.md` (Version Management Tasks table)
+- Modify: `CLAUDE.md` (Generated Gem Features, publishing bullet)
+
+**Interfaces:**
+- Consumes: final behaviour of Tasks 1–2. No code.
+
+- [ ] **Step 1: README**
+
+Change the `rake release:rubygems` row to:
+
+```markdown
+| `rake release:rubygems` | Build, then push every gem in `pkg/` for the current version to RubyGems |
+```
+
+- [ ] **Step 2: CLAUDE.md**
+
+Replace the publishing bullet (the one starting "Publishing rake tasks") with:
+
+```markdown
+- 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, and `release:rubygem_push` is owned by gempilot (`Gempilot::RubygemsRelease`) and pushes every `pkg/<name>-<version>{,-*}.gem` rather than bundler's single built gem
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md CLAUDE.md
+git commit -m "Document the version-scoped RubyGems push"
+```