gempilot 0.2.3 → 0.3.0

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

@@ -95,13 +95,13 @@ 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
 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
@@ -110,21 +110,21 @@ Description: e.g.
 +  Zeitwerk::Loader.for_gem.tap do |l|
 +     l.setup
 +   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,16 +155,60 @@ 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: 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/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

@@ -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/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/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.3.0".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

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