gempilot 0.2.4 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed510959d35011586d23fc0dcc0baff3a453a2acbd1a2d1c8fb4489cee63e6e0
-  data.tar.gz: 455ba876df7b3fb40df26932737cae4062a6e6e2210f1fd02b18a231566bd23d
+  metadata.gz: 686fd797469009843d44529b0831634baf163cbd007a7d625f9605e340aa021a
+  data.tar.gz: f1144a8db6d9a54e8b4cfb146aae7d4d240c92f87a08cf4501589241934cfcbc
 SHA512:
-  metadata.gz: 4ce5185ea5c07adc72435dee47b2f749f4f6146f26a09c8d8c557490e4be1b69b2b048e4c9ab32b8548d043c9a0d393cc32a0d8dd23c94c98cabd3a8737334d9
-  data.tar.gz: 6094227a45e9bb173f0455dc155bd3ac7593698a7c41c7ac1482c5e7c44a59a90c547bb20206d3c7887b87a84977fc1f7ca615b2975fe53dc6a8ab85384a83e8
+  metadata.gz: 5ae0fdd86a89ec6855ae589c6c64fc28d97e71df117f81a35440ca9029333d962171daf080c8d0b24adafe2e83a4e41e2cb0bd989399d8df9cc79dfb2da6d9b0
+  data.tar.gz: abcea8380c013d64f9f22d8c82a59ffbb18a24ff5bcd0be017c0a640450cec51afc88fb676c0004f797f0a54404ca24e4acc8a2183cd836719dab0e117532580

data/.claude/memory/be-decisive-not-menus.md

@@ -0,0 +1,14 @@
+---
+name: be-decisive-not-menus
+description: "David wants decisive action — make the clear right move, don't present option-menus or re-ask"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 8ab20c6a-4c03-4f0a-9acd-e12099699ad8
+---
+
+David wants decisive execution, not deliberation theater. He corrected me repeatedly (and bluntly) this session for presenting choices instead of acting, re-offering things already done, and asking permission for obvious next steps.
+
+**Why:** He's the maintainer and knows his codebase; a menu of options he has to adjudicate is friction, not help. "and?" from him means "keep going / do the next obvious thing." "do the right thing" means "use your judgment and execute."
+
+**How to apply:** When something's already done, say it's done — don't re-offer it. When there's a clear best move (green reviewed PR → merge it; verified-safe branch cleanup → do it), just make it and report the result. Reserve questions for genuine forks where his answer changes the outcome, and even then lead with a one-word-approvable recommendation instead of a survey. Don't narrate options you won't pursue. Confirm only truly hard-to-reverse or outward-facing actions — and expect him to push you past even those with "just do it."

data/.claude/memory/flagship-shared-rubocop-config-state.md

@@ -0,0 +1,16 @@
+---
+name: flagship-shared-rubocop-config-state
+description: "Status of issue 79AE436E (shared RuboCop config + eject) — designed 2026-07-20, not yet built"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 8ab20c6a-4c03-4f0a-9acd-e12099699ad8
+---
+
+The flagship **79AE436E** ("own shared RuboCop config via `inherit_gem` + eject hatch") is **designed but not implemented** as of 2026-07-20. Design spec committed at `docs/superpowers/specs/2026-07-20-shared-rubocop-config-eject-design.md` on branch `file-issue-own-shared-config` (that branch = the flagship WIP: issue-filing commit + design doc only; the 6 backlog fixes that were briefly on it shipped separately via PR #20 and are now in master).
+
+Approved direction: `inherit_gem`; gempilot ships `config/rubocop/{base,minitest,rspec}.yml`; generated `.rubocop.yml` shrinks to near-zero (gem-name excludes become globs `*.gemspec`/`lib/*-*.rb`; drop `TargetRubyVersion` since RuboCop reads it from the gemspec's `required_ruby_version`); new `gempilot eject` inlines config + cuts the link; generated Gemfile pins gempilot.
+
+Before/while building: **(1) OPEN decision** — CI-break mitigation policy; **pin** is the recommended default but David has NOT confirmed it. **(2) First step is a SPIKE** — verify RuboCop loads `plugins:` (rubocop-claude etc.) *through* an `inherit_gem` config; if not, the plugins list stays in the local file. See [[gempilot-generated-gem-rubocop-gate]].
+
+Other open backlog item: **741FFD05** (reduce deps). The gemspec's 4 runtime deps (`command_kit`, `rake`, `warning`, `zeitwerk`) are all used — leave them; reduction is purely Gemfile dev deps. Recommended: drop `benchmark`/`observer`/`rbs`; keep `irb`/`repl_type_completor` (bin/console), `rdoc` (docs), `debug`. (`warning` is the one narrow runtime dep — only silences the VERSION-reload warnings in `Project#fetch_version`.)

data/.rubocop.yml

@@ -279,17 +279,3 @@ RSpec/NamedSubject:
 # have_file_content matcher accepts a filename string in expect()
 RSpec/ExpectActual:
   Enabled: false
-
-Design/PositionalArguments:
-  Enabled: false
-
-Design/KeywordArguments:
-  Enabled: false
-
-Design/TotalArguments:
-  Enabled: false
-
-Design/AgentNounClassName:
-  Exclude:
-    - 'lib/gempilot/generator.rb'
-    - 'test/gempilot/cli/generator_test.rb'

data/CLAUDE.md

@@ -10,7 +10,7 @@ A CLI tool for creating and managing Ruby gems, built on CommandKit.
 - `gempilot create` — Scaffold a new gem (templates in `data/templates/gem/`)
 - `gempilot new` — Generate a class, module, or command in an existing gem (templates in `data/templates/new/`)
 - `gempilot destroy` — Remove a class, module, or command from an existing gem
-- `gempilot bump` — Bump version in `version.rb` (patch default, or minor/major)
+- `gempilot bump` — Bump version in `version.rb` (patch default, or minor/major/tiny/dev)
 - `gempilot release` — Thin proxy to `rake release`
 - `gempilot console` — Thin proxy to `bin/console`
 
@@ -21,6 +21,7 @@ A CLI tool for creating and managing Ruby gems, built on CommandKit.
 - Generator module (`lib/gempilot/cli/generator.rb`) provides template rendering via ERB
 - GemContext module (`lib/gempilot/cli/gem_context.rb`) shared by new, destroy, release, console
 - `GemConstant` value object (`lib/gempilot/gem_constant.rb`) owns constant→namespace/path resolution for `new`/`destroy`; constants are rooted at the gem module by construction
+- `SegmentedVersion` value object (`lib/gempilot/segmented_version.rb`) owns version parsing and bump arithmetic; every bump moves to the smallest version of the requested shape greater than the current version (RubyGems ordering)
 - CommandKit::Commands::AutoLoad maps filenames in `commands/` to command names
 
 ### Testing

data/README.md

@@ -82,8 +82,16 @@ Bump the version in `lib/<gem>/version.rb`.
 gempilot bump          # patch (default)
 gempilot bump minor
 gempilot bump major
+gempilot bump tiny     # fourth integer for tiny follow-ups: 0.2.0 -> 0.2.0.1
+gempilot bump dev      # preview of the next patch: 0.2.0 -> 0.2.1.dev1
 ```
 
+A `dev` version previews the next patch, so it always sorts ahead of the
+current release (`0.2.0 < 0.2.1.dev1 < 0.2.1`), and a numeric bump finalizes
+the cycle (`gempilot bump` from `0.2.1.dev3` gives `0.2.1`). A repo holding an
+old-style dev version — one created *after* its base version shipped — needs a
+one-time hand edit of `version.rb` past the last published version.
+
 ### `gempilot release`
 
 Delegates to `rake release`, which publishes the current version to all remotes
@@ -113,7 +121,7 @@ Generated gems include rake tasks for the full version lifecycle:
 | Task | Description |
 |------|-------------|
 | `rake version:current` | Display the current version |
-| `rake version:bump` | Increment the patch version |
+| `rake version:bump` | Bump the version (patch default; major/minor/patch/tiny/dev) |
 | `rake version:commit` | Commit the version file change |
 | `rake version:tag` | Create a git tag for the version |
 | `rake version:untag` | Delete the version git tag |

data/data/templates/gem/Rakefile.erb

@@ -18,16 +18,8 @@ RuboCop::RakeTask.new
 require "gempilot/version_task"
 Gempilot::VersionTask.new
 
-namespace :zeitwerk do
-  desc "Verify all files follow Zeitwerk naming conventions"
-  task :validate do
-    ruby "-e", <<~RUBY
-      require '<%= @require_path %>'
-      <%= @module_name %>::LOADER.eager_load(force: true)
-      puts 'Zeitwerk: All files loaded successfully.'
-    RUBY
-  end
-end
+require "gempilot/zeitwerk_task"
+Gempilot::ZeitwerkTask.new
 
 <% if @test_framework == :minitest -%>
 task default: [:test, :rubocop]

data/data/templates/gem/lib/gem_name.rb.erb

@@ -6,8 +6,7 @@ require "zeitwerk"
 ##
 # Top-level namespace for the <%= @gem_name %> gem.
 module <%= @module_name %>
-  LOADER = Zeitwerk::Loader.for_gem
-  LOADER.setup
+  LOADER = Zeitwerk::Loader.for_gem.tap(&:setup)
 
   ##
   # Base error class for <%= @gem_name %>.

data/data/templates/gem/lib/gem_name_extension.rb.erb

@@ -9,8 +9,7 @@ require "zeitwerk"
 <% end -%>
 <%= "  " * i %>module <%= part %>
 <% end -%>
-<%= "  " * @module_parts.size %>LOADER = Zeitwerk::Loader.for_gem_extension(<%= @base_module %>)
-<%= "  " * @module_parts.size %>LOADER.setup
+<%= "  " * @module_parts.size %>LOADER = Zeitwerk::Loader.for_gem_extension(<%= @base_module %>).tap(&:setup)
 
 <%= "  " * @module_parts.size %>##
 <%= "  " * @module_parts.size %># Base error class for <%= @gem_name %>.

data/data/templates/gem/test/test_helper.rb.erb

@@ -1,7 +1,10 @@
 ENV["MT_NO_PLUGINS"] = "1" unless ENV["RM_INFO"]
 
 require "minitest/autorun"
-require "minitest/reporters"
-Minitest::Reporters.use! [Minitest::Reporters::DefaultReporter.new(color: true)]
+
+unless ENV["RM_INFO"]
+  require "minitest/reporters"
+  Minitest::Reporters.use! [Minitest::Reporters::DefaultReporter.new(color: true)]
+end
 
 require "<%= @require_path %>"

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

@@ -0,0 +1,483 @@
+# Forward-Moving Version Bumps 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 every `version:bump` segment move strictly forward under RubyGems ordering, add a `tiny` fourth-integer segment, and mark dev GitHub releases as prereleases.
+
+**Architecture:** A new `Gempilot::SegmentedVersion` value object (Data class) owns parsing of the three accepted version shapes (`M.m.p`, `M.m.p.N`, `M.m.p.devN`) and all bump arithmetic; `Project::Version#bump` becomes a thin delegation, keeping its `Data.define(:path, :value)` surface untouched. `GithubRelease#create` derives prerelease status from its tag string. Spec: `docs/superpowers/specs/2026-08-09-dev-version-bump-design.md`.
+
+**Tech Stack:** Ruby (Zeitwerk autoloading), RSpec (`spec/`, library), Minitest (`test/`, CLI), RuboCop.
+
+## Global Constraints
+
+- Semantics rule (from spec): every bump yields the smallest version of the requested shape strictly greater than the current version. Full transition table is in the spec and is reproduced in Task 1's test code — treat that table as normative.
+- Double-quoted strings (`Style/StringLiterals: double_quotes`); NO `# frozen_string_literal:` comments (`EnforcedStyle: never`); trailing commas in multiline literals/arguments.
+- Ruby ≥ 3.4 idioms are fine (`it` block parameter is used throughout the codebase); rdoc `##` doc blocks (never YARD tags), no blank line between `##` block and the definition.
+- Zeitwerk: new file `lib/gempilot/segmented_version.rb` MUST define `Gempilot::SegmentedVersion` (the eager-load spec `spec/zeitwerk_spec.rb` enforces this).
+- Verification commands: `bundle exec rspec <file>` for focused runs, `bundle exec rake default` (= `test` + `spec` + `rubocop`) for the full gate. Baseline before Task 1: 145 examples, 0 failures, 60 files no rubocop offenses.
+- Commit messages: plain imperative, no conventional-commit prefixes (repo style: "Add issue", "Add dev version bump design spec").
+
+---
+
+### Task 1: SegmentedVersion arithmetic + Version#bump rewrite
+
+**Files:**
+- Create: `lib/gempilot/segmented_version.rb`
+- Modify: `lib/gempilot/project/version.rb` (full rewrite shown below)
+- Test: `spec/gempilot/project/version_spec.rb` (full rewrite shown below)
+- Test: `spec/gempilot/version_task_spec.rb:35-38` (one expectation flip)
+
+**Interfaces:**
+- Consumes: `Gempilot::Project::Version` `Data.define(:path, :value)` (existing), `Data#with` (Ruby core).
+- Produces: `Gempilot::SegmentedVersion.parse(string) → SegmentedVersion` (raises `ArgumentError` on unrecognized shapes), `SegmentedVersion#bump(segment) → SegmentedVersion` for `:major/:minor/:patch/:tiny/:dev` (symbol or string; raises `ArgumentError` otherwise), `SegmentedVersion#to_s → String`. `Version#bump(segment = :patch)` / `#next_version` keep their existing signatures — later tasks rely only on those.
+
+- [ ] **Step 1: Rewrite the version spec with the normative transition table**
+
+Replace the entire contents of `spec/gempilot/project/version_spec.rb` with:
+
+```ruby
+require "spec_helper"
+
+RSpec.describe Gempilot::Project::Version do
+  let(:path) { Pathname("lib/my_gem/version.rb") }
+
+  def version(value)
+    described_class.new(path: path, value: value)
+  end
+
+  describe "#tag" do
+    it "prepends v to the value" do
+      expect(version("1.2.3").tag).to eq("v1.2.3")
+    end
+  end
+
+  describe "#bump" do
+    transitions = {
+      "1.2.3" => { major: "2.0.0", minor: "1.3.0", patch: "1.2.4", tiny: "1.2.3.1", dev: "1.2.4.dev1" },
+      "1.2.3.1" => { major: "2.0.0", minor: "1.3.0", patch: "1.2.4", tiny: "1.2.3.2", dev: "1.2.4.dev1" },
+      "1.2.4.dev2" => { major: "2.0.0", minor: "1.3.0", patch: "1.2.4", tiny: "1.2.4.1", dev: "1.2.4.dev3" },
+      "1.3.0.dev2" => { major: "2.0.0", minor: "1.3.0", patch: "1.3.0", tiny: "1.3.0.1", dev: "1.3.0.dev3" },
+      "2.0.0.dev2" => { major: "2.0.0", minor: "2.0.0", patch: "2.0.0", tiny: "2.0.0.1", dev: "2.0.0.dev3" },
+    }
+
+    transitions.each do |from, bumps|
+      bumps.each do |segment, to|
+        it "bumps #{from} to #{to} for #{segment}" do
+          expect(version(from).bump(segment).value).to eq(to)
+        end
+      end
+    end
+
+    it "moves every transition strictly forward under Gem::Version ordering" do
+      transitions.each do |from, bumps|
+        bumps.each_value do |to|
+          expect(Gem::Version.new(to)).to be > Gem::Version.new(from)
+        end
+      end
+    end
+
+    it "bumps patch by default" do
+      expect(version("1.2.3").bump.value).to eq("1.2.4")
+    end
+
+    it "accepts segment as a string" do
+      expect(version("1.0.0").bump("minor").value).to eq("1.1.0")
+    end
+
+    it "raises for an unknown segment" do
+      expect { version("1.0.0").bump(:hotfix) }.to raise_error(ArgumentError, /unknown segment/i)
+    end
+
+    it "raises for a two-integer version" do
+      expect { version("1.2").bump }.to raise_error(ArgumentError, /cannot parse/i)
+    end
+
+    it "raises for a non-dev prerelease version" do
+      expect { version("1.2.3.beta1").bump }.to raise_error(ArgumentError, /cannot parse/i)
+    end
+  end
+
+  describe "#next_version" do
+    it "finalizes a dev version to its target" do
+      expect(version("0.0.4.dev3").next_version.value).to eq("0.0.4")
+    end
+
+    it "bumps the patch of a release version" do
+      expect(version("1.0.99").next_version.value).to eq("1.0.100")
+    end
+  end
+end
+```
+
+- [ ] **Step 2: Flip the stale expectation in the version task spec**
+
+In `spec/gempilot/version_task_spec.rb`, the fixture version is `1.0.0.dev3`. Change the `version:bump` default example (currently expects `"1.0.1"`) to:
+
+```ruby
+    it "finalizes a dev version to its target by default" do
+      Rake::Task["version:bump"].invoke
+      expect(version_in_file).to eq("1.0.0")
+    end
+```
+
+(The `version:bump[dev]` → `"1.0.0.dev4"` and both `version:release` examples are already correct under the new semantics — do not touch them.)
+
+- [ ] **Step 3: Run the specs to verify they fail for the right reason**
+
+Run: `bundle exec rspec spec/gempilot/project/version_spec.rb spec/gempilot/version_task_spec.rb --no-color`
+Expected: FAILURES including `expected: "1.2.4.dev1" got: "1.2.3.dev1"` (dev goes backward today), `expected: "1.2.4" got: "1.2.5"` (patch overshoots a dev target), every `:tiny` cell erroring with `ArgumentError: Unknown segment :tiny` (old code rejects the segment), the `"1.2"` example failing with `NoMethodError` instead of `ArgumentError` (old code coerces then crashes on the missing patch integer), the `"1.2.3.beta1"` example failing with "expected ArgumentError but nothing was raised" (old code silently coerces to `1.2.4`), and `expected: "1.0.0" got: "1.0.1"` in the task spec. The `#tag`, string-segment, and unknown-segment examples still pass.
+
+- [ ] **Step 4: Create the SegmentedVersion value object**
+
+Create `lib/gempilot/segmented_version.rb`:
+
+```ruby
+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
+```
+
+Notes for the implementer:
+- The regex lives in a method-local (`format`), not a constant — a constant inside the `Data.define` block would trip `Lint/ConstantDefinitionInBlock`.
+- `bump` dispatches to five one-branch private methods to stay under `Metrics/CyclomaticComplexity` (max 7).
+- `finalize` drops the prerelease/tiny suffix — it encodes "the smallest version of a numeric shape greater than a dev version is the dev version's own target".
+
+- [ ] **Step 5: Rewrite Version#bump as a delegation**
+
+Replace the entire contents of `lib/gempilot/project/version.rb` with:
+
+```ruby
+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)
+        with(value: SegmentedVersion.parse(value).bump(segment).to_s)
+      end
+
+      alias_method :next_version, :bump
+    end.freeze
+  end
+end
+```
+
+- [ ] **Step 6: Run the specs to verify they pass**
+
+Run: `bundle exec rspec spec/gempilot/project/version_spec.rb spec/gempilot/version_task_spec.rb --no-color`
+Expected: PASS, 0 failures (34 + task-spec examples). If `zeitwerk` cannot resolve the new constant, the filename does not match `Gempilot::SegmentedVersion` — fix the filename, not the loader.
+
+- [ ] **Step 7: Run the full gate**
+
+Run: `bundle exec rake default 2>&1 | tail -8`
+Expected: minitest green, all RSpec examples green (count grows from 145), `no offenses detected`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add lib/gempilot/segmented_version.rb lib/gempilot/project/version.rb spec/gempilot/project/version_spec.rb spec/gempilot/version_task_spec.rb
+git commit -m "Make version bumps move strictly forward"
+```
+
+---
+
+### Task 2: `tiny` segment on the rake and CLI surfaces
+
+**Files:**
+- Modify: `lib/gempilot/version_task.rb:53` (desc string only)
+- Modify: `lib/gempilot/cli/commands/bump.rb`
+- Test: `spec/gempilot/version_task_spec.rb` (add one example)
+- Test: `test/gempilot/cli/bump_command_test.rb` (add one test)
+
+**Interfaces:**
+- Consumes: `Version#bump` accepting `:tiny` (Task 1); rake `version:bump[segment]` forwards the segment string verbatim (existing behavior — no logic change needed there).
+- Produces: `gempilot bump tiny` and `rake version:bump[tiny]` as documented user commands; CLI allowed-segment list `%w[patch minor major tiny dev]`.
+
+- [ ] **Step 1: Add the failing rake-task example**
+
+In `spec/gempilot/version_task_spec.rb`, inside `describe "version:bump"`, add:
+
+```ruby
+    it "bumps the tiny segment" do
+      Rake::Task["version:bump"].invoke("tiny")
+      expect(version_in_file).to eq("1.0.0.1")
+    end
+```
+
+(Fixture is `1.0.0.dev3`; `tiny` finalizes the core and appends `.1`.)
+
+- [ ] **Step 2: Add the failing CLI test**
+
+In `test/gempilot/cli/bump_command_test.rb`, after `test_bump_dev_invokes_rake`, add:
+
+```ruby
+      def test_bump_tiny_invokes_rake
+        calls = recorded_system_calls { |cmd| cmd.main(["tiny"]) }
+
+        assert_includes calls, ["bundle", "exec", "rake", "version:bump[tiny]"]
+      end
+```
+
+- [ ] **Step 3: Run both to verify the CLI test fails and the rake example passes**
+
+Run: `bundle exec rspec spec/gempilot/version_task_spec.rb --no-color && bundle exec rake test 2>&1 | tail -4`
+Expected: the rake-task example PASSES already (the task forwards any segment and Task 1 taught `Version#bump` about `:tiny`) — it is a pin, not a driver. The minitest CLI test FAILS: `Bump#validate_segment` rejects `tiny` and exits 1 before calling rake.
+
+- [ ] **Step 4: Teach the CLI command the tiny segment**
+
+In `lib/gempilot/cli/commands/bump.rb` apply these four edits:
+
+```ruby
+        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, tiny, or dev"
+```
+
+and in `validate_segment`:
+
+```ruby
+          return segment if %w[patch minor major tiny dev].include?(segment)
+
+          puts colors.red("Unknown segment '#{segment}'. Use patch, minor, major, tiny, or dev.")
+```
+
+- [ ] **Step 5: Update the rake task description**
+
+In `lib/gempilot/version_task.rb`, `define_bump_task`:
+
+```ruby
+      desc "Bump version (patch default; segments: major, minor, patch, tiny, dev)"
+```
+
+- [ ] **Step 6: Run the full gate**
+
+Run: `bundle exec rake default 2>&1 | tail -8`
+Expected: all green, no offenses. (`test_bump_fails_with_invalid_segment` uses `hotfix`, which stays invalid.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add lib/gempilot/version_task.rb lib/gempilot/cli/commands/bump.rb spec/gempilot/version_task_spec.rb test/gempilot/cli/bump_command_test.rb
+git commit -m "Add tiny segment to bump interfaces"
+```
+
+---
+
+### Task 3: Mark dev GitHub releases as prereleases
+
+**Files:**
+- Modify: `lib/gempilot/github_release.rb`
+- Test: `spec/gempilot/github_release_spec.rb`
+
+**Interfaces:**
+- Consumes: `GithubRelease.new(tag)` with tag strings like `"v1.2.4.dev1"` (signature unchanged); `Gem::Version#prerelease?` (rubygems, always loaded).
+- Produces: `gh release create` invoked with `--prerelease` when and only when the tag names a prerelease version.
+
+- [ ] **Step 1: Add the failing specs**
+
+In `spec/gempilot/github_release_spec.rb`, inside `describe "#create"`, add two contexts after the existing examples:
+
+```ruby
+    context "with a dev prerelease tag" do
+      let(:tag) { "v1.2.4.dev1" }
+
+      it "marks the release as a prerelease" do
+        release.create
+        args = ["gh", "release", "create", "--generate-notes", "--fail-on-no-commits", "--prerelease", tag]
+        expect(release).to have_received(:sh).with(*args)
+      end
+    end
+
+    context "with a tiny release tag" do
+      let(:tag) { "v1.2.3.1" }
+
+      it "does not mark the release as a prerelease" do
+        release.create
+        args = ["gh", "release", "create", "--generate-notes", "--fail-on-no-commits", tag]
+        expect(release).to have_received(:sh).with(*args)
+      end
+    end
+```
+
+- [ ] **Step 2: Run to verify the dev context fails**
+
+Run: `bundle exec rspec spec/gempilot/github_release_spec.rb --no-color`
+Expected: FAIL — the dev-tag example receives no `--prerelease` argument; the tiny-tag example passes.
+
+- [ ] **Step 3: Implement the prerelease flag**
+
+In `lib/gempilot/github_release.rb`, replace `#create` and append a private section after `#list`:
+
+```ruby
+    def create
+      sh "gh", "release", "create",
+         "--generate-notes", "--fail-on-no-commits",
+         *prerelease_flag,
+         tag
+    end
+```
+
+```ruby
+    private
+
+    def prerelease_flag
+      Gem::Version.new(tag.delete_prefix("v")).prerelease? ? ["--prerelease"] : []
+    end
+```
+
+Also extend the class doc block's first line to:
+
+```ruby
+  ## Manages GitHub releases for a version tag. Tags naming a prerelease
+  ## version (e.g. +v1.2.4.dev1+) are created as GitHub prereleases.
+```
+
+- [ ] **Step 4: Run the spec, then the full gate**
+
+Run: `bundle exec rspec spec/gempilot/github_release_spec.rb --no-color && bundle exec rake default 2>&1 | tail -8`
+Expected: PASS everywhere, no offenses.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/gempilot/github_release.rb spec/gempilot/github_release_spec.rb
+git commit -m "Mark dev GitHub releases as prereleases"
+```
+
+---
+
+### Task 4: Documentation
+
+**Files:**
+- Modify: `README.md` (bump section ~line 77-85; version tasks table row ~line 116)
+- Modify: `CLAUDE.md` (bump command bullet; architecture list)
+
+**Interfaces:**
+- Consumes: final semantics from Tasks 1-3.
+- Produces: user-facing docs; no code.
+
+- [ ] **Step 1: Update the README bump section**
+
+Replace the `gempilot bump` code block and add one paragraph after it:
+
+````markdown
+```bash
+gempilot bump          # patch (default)
+gempilot bump minor
+gempilot bump major
+gempilot bump tiny     # fourth integer for tiny follow-ups: 0.2.0 -> 0.2.0.1
+gempilot bump dev      # preview of the next patch: 0.2.0 -> 0.2.1.dev1
+```
+
+A `dev` version previews the next patch, so it always sorts ahead of the
+current release (`0.2.0 < 0.2.1.dev1 < 0.2.1`), and a numeric bump finalizes
+the cycle (`gempilot bump` from `0.2.1.dev3` gives `0.2.1`). A repo holding an
+old-style dev version — one created *after* its base version shipped — needs a
+one-time hand edit of `version.rb` past the last published version.
+````
+
+- [ ] **Step 2: Update the README version tasks table row**
+
+```markdown
+| `rake version:bump` | Bump the version (patch default; major/minor/patch/tiny/dev) |
+```
+
+- [ ] **Step 3: Update CLAUDE.md**
+
+Change the bump command bullet to:
+
+```markdown
+- `gempilot bump` — Bump version in `version.rb` (patch default, or minor/major/tiny/dev)
+```
+
+and add to the Architecture list, after the `GemConstant` bullet:
+
+```markdown
+- `SegmentedVersion` value object (`lib/gempilot/segmented_version.rb`) owns version parsing and bump arithmetic; every bump moves to the smallest version of the requested shape greater than the current version (RubyGems ordering)
+```
+
+- [ ] **Step 4: Full gate and commit**
+
+Run: `bundle exec rake default 2>&1 | tail -8`
+Expected: all green (docs only — this is a regression guard).
+
+```bash
+git add README.md CLAUDE.md
+git commit -m "Update docs for forward-moving version bumps"
+```