gempilot 0.2.4 → 0.3.1

data/docs/superpowers/specs/2026-08-09-dev-version-bump-design.md

@@ -0,0 +1,163 @@
+# Dev version bump semantics — design
+
+**Issue:** `2360FFA4-9388-11F1-8474-FE6CB9572C2F` — "rake version:bump[dev] goes backward rather than forward"
+
+**Date:** 2026-08-09
+
+## Problem
+
+`Gempilot::Project::Version#bump(:dev)` appends `.dev1` to the *current* version
+(`0.2.0` → `0.2.0.dev1`). RubyGems treats any version with a letter segment as a
+**prerelease of the version it names** (`Gem::Version` rdoc: "Prereleases sort
+between real releases (newest to oldest): 1.0 > 1.0.b1 > 1.0.a.2 > 0.9"), so
+`0.2.0.dev1 < 0.2.0` — the bump moves the project *backward*. Two related gaps:
+
+1. `bump(:patch)` from `X.Y.Z.devN` produces `X.Y.(Z+1)`, overshooting the
+   `X.Y.Z` the dev cycle was working toward.
+2. There is no way to bump a fourth integer (`0.2.0` → `0.2.0.1`), the
+   rubygems-legal *non-prerelease* shape for tiny follow-up fixes on a released
+   version (the Rails security-release pattern, `6.0.3.1`).
+
+## Decisions
+
+- **Dev versions preview the next patch.** `bump(:dev)` from a release version
+  yields the next patch's first dev prerelease (`0.2.0` → `0.2.1.dev1`); from a
+  dev version it increments the counter (`0.2.1.dev1` → `0.2.1.dev2`). This is
+  the only reading consistent with rubygems ordering, and matches ecosystem
+  practice (Rails `7.1.0.beta1` precedes `7.1.0`; Bundler's in-repo `.dev`).
+- **One rule governs every bump: move to the smallest version of the requested
+  shape that is strictly greater than the current version.** Consequences:
+  numeric bumps from a dev version *finalize* the cycle (`0.2.1.dev3` +
+  `patch` → `0.2.1`, not `0.2.2`), and `minor`/`major` redirect it
+  (`0.2.1.dev3` + `minor` → `0.3.0`).
+- **New `tiny` segment for the fourth integer.** `bump(:tiny)`: `0.2.0` →
+  `0.2.0.1` → `0.2.0.2`. Name chosen by elimination: semver's "build metadata"
+  is precedence-ignored (and the `Gem::Version` rdoc uses "build" for the third
+  integer); `micro` is Python's third digit; `patchlevel` is Ruby-historical but
+  long and confusable with `patch`. `tiny` reads as "smaller than patch", which
+  is where it sorts. (Old Rails used TINY for the third digit; accepted.)
+- **No dev target argument** (`bump[dev,minor]` → `0.3.0.dev1`) — YAGNI. The
+  shape rule already finalizes hand-edited `M.m.0.devN` / `M.0.0.devN` states
+  correctly, so a targeted form can be layered on later without breaking
+  anything.
+- **Dev GitHub releases are prereleases.** `release:github` passes
+  `--prerelease` to `gh release create` when the tag names a prerelease
+  version, so `v0.2.1.dev2` does not become the repo's "Latest" release.
+- **Strict version parsing.** `Version#bump` recognizes exactly three forms —
+  `M.m.p`, `M.m.p.N`, `M.m.p.devN` — and raises `ArgumentError` for anything
+  else, instead of today's silent first-three-integers coercion.
+
+## Semantics
+
+Accepted version forms: release `M.m.p`, tiny release `M.m.p.N`, dev prerelease
+`M.m.p.devN` (parse: `/\A(\d+)\.(\d+)\.(\d+)(?:\.(\d+)|\.dev(\d+))?\z/`).
+
+Full transition table (rows marked * arise only by hand-editing; the rule is
+total over all three forms regardless of how the version got there):
+
+| from ↓ bump → | `major` | `minor` | `patch` | `tiny`    | `dev`        |
+| ------------- | ------- | ------- | ------- | --------- | ------------ |
+| `1.2.3`       | `2.0.0` | `1.3.0` | `1.2.4` | `1.2.3.1` | `1.2.4.dev1` |
+| `1.2.3.1`     | `2.0.0` | `1.3.0` | `1.2.4` | `1.2.3.2` | `1.2.4.dev1` |
+| `1.2.4.dev2`  | `2.0.0` | `1.3.0` | `1.2.4` | `1.2.4.1` | `1.2.4.dev3` |
+| `1.3.0.dev2`* | `2.0.0` | `1.3.0` | `1.3.0` | `1.3.0.1` | `1.3.0.dev3` |
+| `2.0.0.dev2`* | `2.0.0` | `2.0.0` | `2.0.0` | `2.0.0.1` | `2.0.0.dev3` |
+
+All 25 transitions verified strictly increasing under `Gem::Version` (checked
+2026-08-09 against ruby's installed rubygems).
+
+Branch logic per segment, where the numeric core is `M.m.p` and `dev?` means
+the current version is a dev prerelease:
+
+- `major`: `dev? && m == 0 && p == 0` → `M.0.0` (finalize); else `(M+1).0.0`
+- `minor`: `dev? && p == 0` → `M.m.0` (finalize); else `M.(m+1).0`
+- `patch`: `dev?` → `M.m.p` (finalize); else `M.m.(p+1)`
+- `tiny`:  `M.m.p.(N+1)` where `N` is the current fourth integer, else 0.
+  (From a dev version this yields `M.m.p.1` — it implicitly finalizes the
+  target and adds a tiny level; forward-moving, documented edge case.)
+- `dev`:   `dev?` → `M.m.p.dev(N+1)`; else `M.m.(p+1).dev1`
+
+## Components
+
+### `Gempilot::Project::Version` (modified — `lib/gempilot/project/version.rb`)
+
+- Stays `Data.define(:path, :value)` — `write_version!`, `VersionTag`, and all
+  call sites are untouched. Parsing is internal to `bump`.
+- `bump(segment)` accepts `:major, :minor, :patch, :tiny, :dev` (symbol or
+  string), implements the table above. Unknown segment → `ArgumentError`
+  naming the valid segments (as today, plus `tiny`). Unparseable value →
+  `ArgumentError` naming the value.
+- `next_version` alias retained; its behavior follows the new `patch` default
+  (`0.0.4.dev3` → `0.0.4`, previously `0.0.5`).
+
+### `Gempilot::GithubRelease` (modified — `lib/gempilot/github_release.rb`)
+
+- `#create` appends `--prerelease` when the tag (sans leading `v`) parses as a
+  prerelease per `Gem::Version#prerelease?`. Self-contained — the
+  `initialize(tag)` signature and all call sites are unchanged. `#destroy` /
+  `#list` untouched.
+
+### `Gempilot::VersionTask` (modified — `lib/gempilot/version_task.rb`)
+
+- Behavior unchanged (it forwards the segment). Only the `version:bump` desc
+  string updates: "Bump version (patch default; segments: major, minor, patch,
+  tiny, dev)".
+
+### `Gempilot::CLI::Commands::Bump` (modified — `lib/gempilot/cli/commands/bump.rb`)
+
+- Allowed segments become `%w[patch minor major tiny dev]`; error message,
+  argument desc, command description, and `examples` updated to match.
+
+## Testing (TDD — written before implementation)
+
+**`spec/gempilot/project/version_spec.rb` (rewritten)**
+
+- The full 5×5 transition table above, each cell an example.
+- A monotonicity property spec: for every table cell,
+  `Gem::Version.new(new) > Gem::Version.new(old)` — the direct regression spec
+  for this issue.
+- Segment as string; unknown segment `ArgumentError`; unparseable value
+  (`"1.2"`, `"1.2.3.beta1"`) `ArgumentError`; `next_version` follows patch
+  semantics (`0.0.4.dev3` → `0.0.4`).
+
+**`spec/gempilot/version_task_spec.rb` (expectations updated)**
+
+Fixture starts at `1.0.0.dev3`:
+- `version:bump` (default patch) → `1.0.0` (finalize; was `1.0.1`).
+- `version:bump[dev]` → `1.0.0.dev4` (unchanged).
+- `version:bump[tiny]` → `1.0.0.1` (new example).
+- `version:release[dev]` → commit "Bump version to 1.0.0.dev4", tag
+  `v1.0.0.dev4` (unchanged).
+
+**`spec/gempilot/github_release_spec.rb` (extended)**
+
+- `create` with `v1.2.4.dev1` includes `--prerelease`; with `v1.2.4` and
+  `v1.2.3.1` it does not.
+
+**`test/gempilot/cli/bump_command_test.rb` (extended)**
+
+- `tiny` accepted as a segment; unknown-segment error message lists it.
+
+## Docs
+
+- `README.md` — `gempilot bump` section gains `tiny` and `dev` examples with a
+  one-line explanation of dev semantics; the rake tasks table row for
+  `version:bump` mentions the segments.
+- `CLAUDE.md` — version lifecycle bullet: "(patch default, or
+  minor/major/tiny/dev)".
+
+## Migration
+
+A repo sitting on an old-style dev version (e.g. `0.2.0.dev1` created *after*
+`0.2.0` shipped) is already in the broken state this fixes; `bump(:patch)`
+would finalize to the already-released `0.2.0` (and `version:tag` would then
+fail on the existing tag). Recovery is a one-time hand edit of `version.rb`
+past the last published version. Noted in the README dev-example line.
+
+## Out of scope
+
+- Targeted dev cycles (`bump[dev,minor]`) — compatible later extension.
+- Other prerelease markers (`pre`, `rc`, `beta`) — `dev` sorts before all of
+  them, so they remain addable later.
+- RubyGems prerelease yanking; `data/templates/gem/Rakefile.erb` (no change
+  needed — it just instantiates `Gempilot::VersionTask`).

data/issues.rec

@@ -95,7 +95,7 @@ Id: 4EB6E51C-4322-11F1-B1B2-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 12:50:05 -0400
 Title: Existing git repo on gempilot create needs new commit message
 Description: Currently it commits "Initial commit". Inappropriate for a git repo that already has a history
-Status: open
+Status: closed
 
 Id: 0411D4DA-4323-11F1-847C-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 12:55:09 -0400
@@ -112,19 +112,19 @@ Description: e.g.
 +   end
 + 
 + 
-Status: open
+Status: closed
 
 Id: 5618BB20-4325-11F1-BF5A-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 13:11:46 -0400
 Title: Move zeitwerk check task into gempilot
 Description: Can't iterate on it when its not managed by gempilot. A new feature needs to be added
-Status: open
+Status: closed
 
 Id: 6BE168E4-4325-11F1-BE0F-FE6CB9572C2F
 Updated: Tue, 28 Apr 2026 13:12:22 -0400
 Title: Add zeitwerk:all task
 Description: Add rake task that runs LOADER.all_expected_cpaths and prints in a nice table, similar to rails routes
-Status: open
+Status: closed
 
 Id: 56DB9634-4327-11F1-8D0F-FE6CB9572C2F
 Updated: Fri, 05 Jun 2026 00:00:00 -0400
@@ -155,13 +155,13 @@ Description: When doing `gempilot new Reversal::Server`, in a project called "re
 +         create  test/reversal/store_test.rb
 + 
 + The test file is incorrectly named. Should be server_test.rb
-Status: open
+Status: closed
 
 Id: F5486B48-71DB-11F1-980F-FE6CB9572C2E
 Updated: Fri, 26 Jun 2026 23:54:55 -0400
 Title: Rubymine <=> Minitest usage causes "no reporters allowed error"
 Description: Has to do with how the ENV var RM_INFO is being interpreted
-Status: open
+Status: closed
 
 Id: 8D847572-7273-11F1-B508-FE6CB9572C2E
 Updated: Fri, 03 Jul 2026 22:38:22 +0000
@@ -212,3 +212,91 @@ Description: the github release related tasks are invoked as follows:
 + 
 + 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
+
+Id: 986E0100-88F4-11F1-B718-FE6CB9572C2D
+Updated: Sun, 26 Jul 2026 09:19:13 -0400
+Title: Make rbs and the other gems GP installs mri only
+Description: This tool is also used with jruby, and it fails irb install due to rbs
+Status: open
+
+Id: 3FFE7616-88F5-11F1-8D3B-FE6CB9572C2D
+Updated: Sun, 26 Jul 2026 09:23:54 -0400
+Title: Add betterleaks to gem setup
+Description: Ensure betterleaks is integrated into the commit and build pipelines, via commit hooks, rake tasks, and/or whatever the idiomatic way is to integrate betterleaks into a rubyproject
+Status: open
+
+Id: F6C6EB04-8DA4-11F1-91EF-FA41C3164F3A
+Updated: Sat, 01 Aug 2026 12:31:47 +0000
+Title: release:rubygem_push only handles one gem per version
+Description: rake release:rubygems can publish only one gem per version. A project that publishes several -- platform gems each carrying a compiled executable, say -- either publishes one of them and silently leaves the rest, or, once it replaces the push task with a pkg glob, tries to re-push versions already on rubygems and stops halfway through the release.
++ 
++ MECHANISM
++ 
++ gempilot, lib/gempilot/release_tasks.rb: ReleaseTasks#define_rubygems_release wires release:rubygems to [build, release:guard_clean, release:source_control_push, release:rubygem_push], and, as the module's own rdoc says, expects bundler/gem_tasks to have supplied build, release:guard_clean and release:rubygem_push.
++ 
++ bundler 4.0.17, lib/bundler/gem_helper.rb: GemHelper#install_tasks defines
++ 
++   task "release:rubygem_push" => "build" do
++     rubygem_push(built_gem_path) if gem_push?
++   end
++ 
++ built_gem_path is the single .gem that #build_gem produced. One build, one gem, one push. Nothing in that chain can carry a second gem, so a project publishing more than one has to replace both build and release:rubygem_push itself.
++ 
++ There is no glob in gempilot's own source to go looking for. The glob is what a downstream project ends up writing once it takes over the push, and it is wrong in a way gempilot's own version:bump triggers.
++ 
++ REPRODUCE
++ 
++ 1. A gem publishing more than one gem per version. aws-session-manager on gempilot 0.3.0 publishes five: x86_64-linux, aarch64-linux, x86_64-darwin and arm64-darwin, each carrying a compiled session-manager-plugin executable, plus the plain ruby gem.
++ 2. It replaces build, and replaces the push with the obvious implementation:
++      task(:rubygem_push) { PACKAGES.glob("*.gem").each { sh "gem", "push", it.to_s } }
++ 3. rake build && rake release:rubygems -- 0.0.1 publishes.
++ 4. rake version:bump && rake build -- pkg/ now holds both 0.0.1 and 0.0.2 gems. Nothing empties pkg/ between versions; bundler never has, and gempilot's version tasks do not either.
++ 5. rake release:rubygems -- gem push rejects the 0.0.1 gems ("Repushing of gem versions is not allowed"), sh raises on the non-zero status, and the release aborts with part of 0.0.2 published and the rest not. Re-running repeats the failure, because the stale gems are still there.
++ 
++ FIX APPLIED DOWNSTREAM
++ 
++ aws-session-manager stopped globbing and took the list from the specifications its build packages, so that gem:build and the push share one source of truth:
++ 
++   PACKAGED = [*BUILDS.map { it.package.to_s }, GENERIC_PACKAGE].freeze
++ 
++   namespace :gem do
++     task build: PACKAGED
++   end
++ 
++   namespace :release do
++     task(:rubygem_push) { PACKAGED.each { sh "gem", "push", it } }
++   end
++ 
++ FIX SUGGESTED HERE
++ 
++ gempilot should own release:rubygem_push rather than inherit bundler's, and push every gem in pkg belonging to the version being released. It cannot know how a project builds, but it knows the name and the version, which is enough:
++ 
++   def define_rubygem_push(project)
++     clear_task "release:rubygem_push"
++     task "release:rubygem_push" => "build" do
++       packages(project).each { sh "gem", "push", it.to_s }
++     end
++   end
++ 
++   def packages(project)
++     stem = "#{project.name}-#{project.version_value}"
++     project.root.glob("pkg/{#{stem}.gem,#{stem}-*.gem}")
++   end
++ 
++ Project#name, #version_value and #root already exist in lib/gempilot/project.rb.
++ 
++ Two details worth keeping:
++ 
++ - The brace glob matches gempilot-0.3.0.gem and gempilot-0.3.0-x86_64-linux.gem, and does not match gempilot-0.3.10.gem. A bare "#{stem}*.gem" would match the latter and push the wrong version.
++ - An empty result should abort. Otherwise a project whose build writes gems elsewhere gets a release that reports success having published nothing, which is worse than the bug being fixed.
++ 
++ Single-gem projects are unaffected: pkg holds one gem for the current version, and it gets pushed, as today. Multi-gem projects stop having to reinvent the push.
++ 
++ If gempilot would rather not own the task, then the ReleaseTasks rdoc should state the contract instead: a project that replaces build must also replace release:rubygem_push, and must scope the push to the version being released rather than globbing pkg.
+Status: open
+
+Id: 2360FFA4-9388-11F1-8474-FE6CB9572C2F
+Updated: Sat, 08 Aug 2026 20:20:34 -0400
+Title: rake version:bump[dev] goes backward rather than forward
+Description: rubygems treats 0.2.0.dev as an *older* version than 0.2.0. The way gempilot handles dev version needs to be rethought. Additionally, how does a user trigger a bump on the fourth integer, e.g. 0.2.0.1?
+Status: open

data/lib/gempilot/cli/commands/bump.rb

@@ -8,18 +8,19 @@ module Gempilot
         include GemContext
 
         usage "[options] [SEGMENT]"
-        description "Bump the gem version (patch by default, or minor/major/dev)"
+        description "Bump the gem version (patch by default, or minor/major/tiny/dev)"
 
         examples [
           "",
           "patch",
           "minor",
           "major",
+          "tiny",
           "dev",
         ]
 
         argument :segment, required: false,
-                           desc: "Version segment to bump: patch (default), minor, major, or dev"
+                           desc: "Version segment to bump: patch (default), minor, major, tiny, or dev"
 
         def run(segment = "patch")
           detect_gem_context
@@ -31,9 +32,9 @@ module Gempilot
 
         def validate_segment(segment)
           segment = segment.downcase
-          return segment if %w[patch minor major dev].include?(segment)
+          return segment if %w[patch minor major tiny dev].include?(segment)
 
-          puts colors.red("Unknown segment '#{segment}'. Use patch, minor, major, or dev.")
+          puts colors.red("Unknown segment '#{segment}'. Use patch, minor, major, tiny, or dev.")
           exit 1
         end
 

data/lib/gempilot/cli/gem_builder.rb

@@ -97,9 +97,21 @@ module Gempilot
         cd @gem_name do
           sh "git", "init", "-q", "-b", @branch
           sh "git", "add", "."
-          sh "git", "commit", "-q", "-m", "Initial commit."
+          sh "git", "commit", "-q", "-m", commit_message
         end
       end
+
+      # "Initial commit." is wrong when scaffolding into a directory that is
+      # already a repository with history (e.g. a cloned remote), so name the
+      # commit after the gem in that case.
+      def commit_message
+        existing_history? ? "Add #{@gem_name} gem scaffolding." : "Initial commit."
+      end
+
+      def existing_history?
+        system("git", "rev-parse", "--verify", "--quiet", "HEAD",
+               out: File::NULL, err: File::NULL)
+      end
     end
   end
 end

data/lib/gempilot/gem_constant.rb

@@ -30,18 +30,14 @@ module Gempilot
 
     ## Path to the constant's source file, e.g. +lib/my_gem/services/auth.rb+.
     def lib_path
-      "#{File.join("lib", *path_segments)}.rb"
+      path_for("lib", ".rb")
     end
 
     ## Path to the constant's test file for +framework+ (+:rspec+ or
-    ## +:minitest+); correct for multi-segment (hyphenated) gem modules.
+    ## +:minitest+). Mirrors +lib_path+ so the test always tracks the source,
+    ## including for multi-segment (hyphenated) gem modules.
     def test_path(framework)
-      rest = path_segments.drop(require_path.split("/").length)
-      if framework == :rspec
-        "#{File.join("spec", require_path, *rest)}_spec.rb"
-      else
-        "#{File.join("test", require_path, *rest)}_test.rb"
-      end
+      framework == :rspec ? path_for("spec", "_spec.rb") : path_for("test", "_test.rb")
     end
 
     private
@@ -57,5 +53,9 @@ module Gempilot
     def path_segments
       parts.map(&:underscore)
     end
+
+    def path_for(root, suffix)
+      "#{File.join(root, *path_segments)}#{suffix}"
+    end
   end
 end

data/lib/gempilot/github_release.rb

@@ -1,5 +1,6 @@
 module Gempilot
-  ## Manages GitHub releases for a version tag.
+  ## Manages GitHub releases for a version tag. Tags naming a prerelease
+  ## version (e.g. +v1.2.4.dev1+) are created as GitHub prereleases.
   class GithubRelease
     include StrictShell
 
@@ -12,6 +13,7 @@ module Gempilot
     def create
       sh "gh", "release", "create",
          "--generate-notes", "--fail-on-no-commits",
+         *prerelease_flag,
          tag
     end
 
@@ -24,5 +26,11 @@ module Gempilot
     def list
       sh "gh", "release", "list"
     end
+
+    private
+
+    def prerelease_flag
+      Gem::Version.new(tag.delete_prefix("v")).prerelease? ? ["--prerelease"] : []
+    end
   end
 end

data/lib/gempilot/project/version.rb

@@ -1,36 +1,15 @@
 module Gempilot
   class Project
+    ## The project's version file (+path+) and value. Bump arithmetic
+    ## delegates to SegmentedVersion, so every bump moves strictly forward
+    ## under RubyGems ordering.
     Version = Data.define(:path, :value) do
       def tag
         "v#{value}"
       end
 
       def bump(segment = :patch)
-        case segment.to_sym
-        when :major, :minor, :patch then bump_semver(segment)
-        when :dev                   then bump_dev
-        else raise ArgumentError, "Unknown segment #{segment.inspect}. Use :major, :minor, :patch, or :dev"
-        end
-      end
-
-      private
-
-      def bump_semver(segment)
-        major, minor, patch = value.split(".").first(3).map(&:to_i)
-        new_value = case segment.to_sym
-                    when :major then "#{major + 1}.0.0"
-                    when :minor then "#{major}.#{minor + 1}.0"
-                    when :patch then "#{major}.#{minor}.#{patch + 1}"
-                    end
-        with(value: new_value)
-      end
-
-      def bump_dev
-        if value.match?(/\.dev\d+\z/)
-          with(value: value.sub(/\d+\z/) { it.to_i + 1 })
-        else
-          with(value: "#{value}.dev1")
-        end
+        with(value: SegmentedVersion.parse(value).bump(segment).to_s)
       end
 
       alias_method :next_version, :bump

data/lib/gempilot/project.rb

@@ -33,8 +33,16 @@ module Gempilot
       project_segments.join("-")
     end
 
+    def require_path
+      project_segments.join("/")
+    end
+
+    def module_name
+      project_segments.map(&:camelize).join("::")
+    end
+
     def klass
-      Object.const_get(project_segments.map(&:camelize).join("::"))
+      Object.const_get(module_name)
     end
 
     def version

data/lib/gempilot/segmented_version.rb

@@ -0,0 +1,64 @@
+module Gempilot
+  ## Arithmetic over the three version shapes gempilot accepts: release
+  ## (+1.2.3+), tiny release (+1.2.3.1+), and dev prerelease (+1.2.3.dev1+).
+  ##
+  ## Every bump returns the smallest version of the requested shape that is
+  ## strictly greater than the current version under RubyGems ordering, so
+  ## bumping always moves a project forward: a dev bump previews the next
+  ## patch (+1.2.3+ to +1.2.4.dev1+) and numeric bumps finalize a dev cycle
+  ## (+1.2.4.dev2+ to +1.2.4+ for +:patch+).
+  SegmentedVersion = Data.define(:major, :minor, :patch, :tiny, :dev) do
+    def self.parse(string)
+      format = /\A(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:\.(?<tiny>\d+)|\.dev(?<dev>\d+))?\z/
+      match = format.match(string)
+      raise ArgumentError, "cannot parse version: #{string.inspect}" unless match
+
+      new(**match.named_captures.to_h { |name, digits| [name.to_sym, digits&.to_i] })
+    end
+
+    def bump(segment)
+      case segment.to_sym
+      when :major then bump_major
+      when :minor then bump_minor
+      when :patch then bump_patch
+      when :tiny  then bump_tiny
+      when :dev   then bump_dev
+      else raise ArgumentError, "Unknown segment #{segment.inspect}. Use :major, :minor, :patch, :tiny, or :dev"
+      end
+    end
+
+    def to_s
+      [major, minor, patch, tiny, ("dev#{dev}" if dev)].compact.join(".")
+    end
+
+    private
+
+    def bump_major
+      return finalize if dev && minor.zero? && patch.zero?
+
+      with(major: major + 1, minor: 0, patch: 0, tiny: nil, dev: nil)
+    end
+
+    def bump_minor
+      return finalize if dev && patch.zero?
+
+      with(minor: minor + 1, patch: 0, tiny: nil, dev: nil)
+    end
+
+    def bump_patch
+      dev ? finalize : with(patch: patch + 1, tiny: nil)
+    end
+
+    def bump_tiny
+      with(tiny: (tiny || 0) + 1, dev: nil)
+    end
+
+    def bump_dev
+      dev ? with(dev: dev + 1) : with(patch: patch + 1, tiny: nil, dev: 1)
+    end
+
+    def finalize
+      with(tiny: nil, dev: nil)
+    end
+  end.freeze
+end

data/lib/gempilot/version.rb

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

data/lib/gempilot/version_task.rb

@@ -50,7 +50,7 @@ module Gempilot
     end
 
     def define_bump_task(project)
-      desc "Bump version (patch default, or rake version:bump[minor])"
+      desc "Bump version (patch default; segments: major, minor, patch, tiny, dev)"
       task :bump, [:segment] do |_t, args|
         segment = (args[:segment] || :patch).to_sym
         old_version = project.version

data/lib/gempilot/zeitwerk_task.rb

@@ -0,0 +1,61 @@
+require "rake/tasklib"
+require_relative "../gempilot"
+
+module Gempilot
+  ## Rake tasks for validating and inspecting a gem's Zeitwerk loader.
+  ##
+  ## Owned by gempilot and consumed by generated gems via
+  ## <tt>require "gempilot/zeitwerk_task"; Gempilot::ZeitwerkTask.new</tt>, so
+  ## the logic rolls forward on a gempilot bump instead of being copied into
+  ## every gem's Rakefile. Each task boots a clean child process so eager
+  ## loading surfaces naming errors without polluting the Rake process.
+  class ZeitwerkTask < Rake::TaskLib
+    attr_reader :project
+
+    def initialize(root: Dir.pwd)
+      super()
+      @project = Project.new(root)
+      define_tasks
+    end
+
+    private
+
+    def define_tasks
+      namespace :zeitwerk do
+        define_validate_task
+        define_all_task
+      end
+    end
+
+    def define_validate_task
+      desc "Verify all files follow Zeitwerk naming conventions"
+      task(:validate) { ruby "-Ilib", "-e", validate_script }
+    end
+
+    def define_all_task
+      desc "List every constant Zeitwerk manages and the file it expects"
+      task(:all) { ruby "-Ilib", "-e", all_script }
+    end
+
+    def loader
+      "#{project.module_name}::LOADER"
+    end
+
+    def validate_script
+      <<~RUBY
+        require '#{project.require_path}'
+        #{loader}.eager_load(force: true)
+        puts 'Zeitwerk: All files loaded successfully.'
+      RUBY
+    end
+
+    def all_script
+      <<~RUBY
+        require '#{project.require_path}'
+        rows = #{loader}.all_expected_cpaths.sort_by(&:last)
+        width = rows.map { |_path, cpath| cpath.length }.max || 0
+        rows.each { |path, cpath| puts format("%-\#{width}s  %s", cpath, path) }
+      RUBY
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gempilot
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: ruby
 authors:
 - David Gillis
@@ -72,6 +72,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/memory/be-decisive-not-menus.md"
+- ".claude/memory/flagship-shared-rubocop-config-state.md"
 - ".claude/skills/using-command-kit/SKILL.md"
 - ".claude/skills/using-command-kit/cli-example.rb"
 - ".claude/skills/using-command-kit/generator-pattern.rb"
@@ -107,7 +109,9 @@ files:
 - data/templates/new/.keep
 - data/templates/new/command.rb.erb
 - docs/superpowers/plans/2026-07-20-release-task-hierarchy.md
+- docs/superpowers/plans/2026-08-09-dev-version-bump.md
 - docs/superpowers/specs/2026-07-20-release-task-hierarchy-design.md
+- docs/superpowers/specs/2026-08-09-dev-version-bump-design.md
 - exe/gempilot
 - issues.rec
 - lib/core_ext/string/inflection_methods.rb
@@ -130,10 +134,12 @@ files:
 - lib/gempilot/project.rb
 - lib/gempilot/project/version.rb
 - lib/gempilot/release_tasks.rb
+- lib/gempilot/segmented_version.rb
 - lib/gempilot/strict_shell.rb
 - lib/gempilot/version.rb
 - lib/gempilot/version_tag.rb
 - lib/gempilot/version_task.rb
+- lib/gempilot/zeitwerk_task.rb
 - vendor/vendored.gemv
 homepage: https://github.com/gillisd/gempilot
 licenses:
@@ -155,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.18
 specification_version: 4
 summary: A toolkit for creating, managing, and releasing your own rubygems
 test_files: []