agentilda 2.0.1 → 2.0.4

data/lib/agentilda/{ui.rb → support/ui.rb}

@@ -66,7 +66,7 @@ module Agentilda
     # These are two readers of one story and used to be told it separately:
     # the spinner got the phrase, the log got a start and a finish, and an
     # animated run wrote nothing about what any agent was actually doing. A
-    # {Agentilda::Transcript::Progress} arrives here several times a
+    # {Agentilda::Execution::Transcript::Progress} arrives here several times a
     # second; the line is redrawn every time, and the log takes a line only
     # when the phrase itself changes, which is a few dozen times an agent.
     #
@@ -188,7 +188,7 @@ module Agentilda
         note("failed after #{alive}: #{reason}")
       end
 
-      # @param update [Agentilda::Transcript::Progress]
+      # @param update [Agentilda::Execution::Transcript::Progress]
       # @return [void]
       def call(update)
         if update.respond_to?(:pid) && update.pid && update.pid != @pid
@@ -262,7 +262,7 @@ module Agentilda
       def log(message, **fields)
         path = log_path or return
 
-        line = ProgressLog.render(message, **fields)
+        line = Engine::ProgressLog.render(message, **fields)
         (@log_mutex ||= Mutex.new).synchronize do
           FileUtils.mkdir_p(File.dirname(path))
           File.open(path, "a") { |f| f.puts(line) }
@@ -282,7 +282,7 @@ module Agentilda
       # is what the model generated. Sub-agent spend is folded into up, since
       # `claude` reports a sub-agent's total without splitting it.
       #
-      # @param update [Agentilda::Transcript::Progress, nil]
+      # @param update [Agentilda::Execution::Transcript::Progress, nil]
       # @return [String]
       def meter(update)
         paint(fit("↑#{abbreviate(update&.up)}", METER_WIDTH), :bright_blue) +
@@ -463,7 +463,7 @@ module Agentilda
       #
       # @return [Array] one result per item, in input order
       def on_dashboard(list, jobs:, label:, fields:, failure:, timeout:, file:, root:, &)
-        Dashboard.open(root:) do |dashboard|
+        Presentation::Dashboard.open(root:) do |dashboard|
           # Tracked when it starts, not when it is queued: a row's clock is
           # the agent's clock, and a queued plan has no agent yet.
           run = lambda do |item|

data/lib/agentilda/vcs/github.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+require "tty/command"
+
+module Agentilda
+  module Vcs
+    # The `gh` CLI, wrapped thinly.
+    #
+    # It is a seam rather than a convenience: every example in the suite injects
+    # a double here, so nothing in the tests reaches the network or a real
+    # repository.
+    class GitHub
+      # Fields asked of `gh pr list`.
+      FIELDS = %w[number title url headRefName files state isDraft mergedAt].freeze
+
+      # @param command [TTY::Command] runner, injectable for tests
+      # @param limit [Integer] how many pull requests to fetch
+      def initialize(command: TTY::Command.new(printer: :null), limit: 200)
+        @command = command
+        @limit = limit
+      end
+
+      # Every pull request, normalised into plain hashes.
+      #
+      # @param state [String] "open", "closed", "merged" or "all"
+      # @return [Array<Hash>] `{number:, title:, url:, branch:, files:}`
+      def pulls(state: "all")
+        out = UI.spinning("Fetching pull requests from GitHub") {
+          @command.run("gh",
+            "pr",
+            "list",
+            "--state",
+            state,
+            "--limit",
+            @limit.to_s,
+            "--json",
+            FIELDS.join(",")).out
+        }
+
+        # `gh` can exit 0 having printed NOTHING — most often when it cannot reach
+        # the credential store, as in a non-interactive shell that has no keyring
+        # access, or when GH_TOKEN is set to something invalid and shadows a
+        # working login. Left alone this parses as a JSON error and reports as
+        # "bad output", sending you to look at the wrong thing entirely.
+        raise Error, no_output_message if out.to_s.strip.empty?
+
+        JSON.parse(out).map do |pr|
+          {
+            number: pr["number"],
+            title:  pr["title"].to_s,
+            url:    pr["url"],
+            branch: pr["headRefName"].to_s,
+            files:  Array(pr["files"]).map { |f| f["path"] }.compact,
+            state:  self.class.state_label(pr),
+            open:   pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
+          }
+        end
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not list pull requests via `gh`: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @return [String] the diagnosis for a silent `gh`
+      def no_output_message
+        <<~MESSAGE.strip
+          `gh` produced no output and did not report an error.
+
+          That is almost always authentication rather than an empty repository:
+
+            - Check `gh auth status`. An invalid GH_TOKEN in the environment
+              shadows a working keyring login and fails without saying so.
+
+            - A non-interactive shell may have no access to the system keyring
+              even when an interactive one does.
+
+          Verify with: gh pr list --state all --limit 1
+        MESSAGE
+      end
+
+      # Fields asked of `gh pr view`, which unlike `pr list` can be told about
+      # one pull request in another repository.
+      VIEW_FIELDS = %w[number title url state isDraft mergedAt body].freeze
+
+      # A reference to one pull request: a bare number, a `#`-prefixed number,
+      # or a full URL to a GitHub pull request or a GitLab merge request.
+      REF = %r{\A(?:\#?\d+|https?://\S+?/(?:pull|merge_requests)/\d+/?)\z}
+
+      # Split and validate a `--prs` value before any of it reaches the network,
+      # so a typo fails in a hundredth of a second with the offending token named
+      # rather than after four round trips with a `gh` diagnostic.
+      #
+      # @param text [String] e.g. "12,15,18" or "https://…/pull/12, #15"
+      # @return [Array<String>] references, in the order given, de-duplicated
+      # @raise [Agentilda::Error] on anything that is not a reference
+      def self.parse_refs(text)
+        refs = text.to_s.split(",").map(&:strip).reject(&:empty?)
+        raise Error, "no pull requests given" if refs.empty?
+
+        bad = refs.reject { |r| r.match?(REF) }
+        unless bad.empty?
+          raise Error, "not a pull request number or URL: #{bad.join(", ")}"
+        end
+
+        refs.uniq
+      end
+
+      # One pull request, by number or URL.
+      #
+      # @param ref [String] "12", "#12" or "https://github.com/o/r/pull/12"
+      # @return [Hash] `{number:, title:, url:, state:, body:}`
+      # @raise [Agentilda::Error]
+      def pull_request(ref)
+        out = @command.run("gh", "pr", "view", ref.to_s, "--json", VIEW_FIELDS.join(",")).out
+        raise Error, no_output_message if out.to_s.strip.empty?
+
+        pr = JSON.parse(out)
+        {
+          number: pr["number"],
+          title:  pr["title"].to_s,
+          url:    pr["url"].to_s,
+          state:  self.class.state_label(pr),
+          body:   pr["body"].to_s
+        }
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not read pull request #{ref}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # Several pull requests, in the order asked for.
+      #
+      # @param refs [Array<String>]
+      # @return [Array<Hash>]
+      def pull_requests(refs)
+        UI.stepping(refs, "Fetching pull requests") { |ref| ref }
+        refs.map { |ref| pull_request(ref) }
+      end
+
+      # `gh` speaks in enums; `pull-requests.md` speaks in the words the state
+      # machine parses. Translate once, here, rather than at each call site.
+      #
+      # @param pr [Hash] a decoded `gh pr view` payload
+      # @return [String] one of the labels in {PullRequests::STATES}
+      def self.state_label(pr)
+        return "Merged 🟣" if pr["mergedAt"]
+        return "WIP 🟡" if pr["isDraft"]
+
+        case pr["state"].to_s.upcase
+        when "OPEN" then "Open 🟡"
+        when "CLOSED" then "Closed 🔴"
+        else "Unknown"
+        end
+      end
+
+      # Change a pull request's title.
+      #
+      # @param number [Integer]
+      # @param title [String]
+      # @return [void]
+      def retitle(number:, title:)
+        @command.run("gh", "pr", "edit", number.to_s, "--title", title)
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not retitle ##{number}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @return [Boolean] whether `gh` is installed and authenticated
+      def available?
+        @command.run!("gh", "auth", "status").success?
+      end
+    end
+  end
+end

data/lib/agentilda/vcs/publisher.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "tty/command"
+
+module Agentilda
+  module Vcs
+    # Turns a finished worktree into a pushed branch and a pull request.
+    #
+    # This is the one place the harness reaches off the machine, so it requires
+    # `--commit`, is skipped with `--no-git-push`, and refuses anything
+    # it is not certain about. Everything it does is reported before it does it.
+    #
+    # Titles follow the convention the whole system joins on:
+    #
+    #     [002.00](A) Tenancy Households       — a plan's first pull request
+    #     [002.00](B) Tenancy Households       — its second
+    #
+    # The slug is title-cased from the folder name, so the title reads as a
+    # sentence rather than as a path fragment.
+    class Publisher
+      # A published, or publishable, pull request.
+      #
+      # @!attribute [r] ordinal
+      #   @return [Agentilda::Plans::Ordinal]
+      # @!attribute [r] branch
+      #   @return [String]
+      # @!attribute [r] title
+      #   @return [String]
+      # @!attribute [r] url
+      #   @return [String, nil] nil on a dry run or a refusal
+      # @!attribute [r] refusal
+      #   @return [String, nil]
+      Publication = Data.define(:ordinal, :branch, :title, :url, :refusal) do
+        # @return [Boolean]
+        def published? = !url.nil?
+      end
+
+      # A..Z, which is more parts than any feature should be split into.
+      LETTERS = ("A".."Z").to_a.freeze
+
+      # @param root [String] repository the worktree belongs to
+      # @param command [TTY::Command]
+      # @param base [String] the branch pull requests target
+      # @param dry_run [Boolean]
+      def initialize(root:, command: TTY::Command.new(printer: :null), base: "main", dry_run: true)
+        @root = root
+        @command = command
+        @base = base
+        @dry_run = dry_run
+      end
+
+      # Push one plan's branch and open its pull request.
+      #
+      # @param checkout [Agentilda::Vcs::Worktree::Checkout]
+      # @param subject [Agentilda::Plans::Subject]
+      # @param letter [String, nil] force a part letter; nil auto-assigns
+      # @return [Agentilda::Vcs::Publisher::Publication]
+      def publish(checkout:, subject:, letter: nil)
+        title = title_for(subject, letter)
+
+        unless checkout.dirty?
+          return refuse(subject, checkout, title, "nothing to publish — the worktree is unchanged")
+        end
+
+        return Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: nil) if @dry_run
+
+        commit(checkout, title)
+        push(checkout)
+        url = create_pull_request(checkout, subject, title)
+
+        Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil)
+      rescue TTY::Command::ExitError => e
+        refuse(subject, checkout, title, git_complaint(e))
+      end
+
+      # git and gh put the useful sentence in stderr, several lines below the
+      # command they echo. Reporting only the first line reports "it failed".
+      #
+      # @param error [TTY::Command::ExitError]
+      # @return [String]
+      def git_complaint(error)
+        lines = error.message.lines.map(&:strip).reject(&:empty?)
+        stderr = lines.find { |l| l.start_with?("stderr:") }
+        complaint = stderr&.delete_prefix("stderr:")&.strip
+
+        complaint.to_s.empty? || complaint == "Nothing written" ? lines.first.to_s : complaint
+      end
+
+      # The title a plan's next pull request should carry.
+      #
+      # @param subject [Agentilda::Plans::Subject]
+      # @param letter [String, nil]
+      # @return [String]
+      def title_for(subject, letter = nil)
+        "[#{subject.feature.ordinal}](#{letter || auto_letter(subject)}) #{subject.feature.title}"
+      end
+
+      # Which part this is. Always a letter, starting at A: a plan that turns out
+      # to need only one pull request still reads consistently with every other,
+      # and nothing has to be renamed when a second arrives.
+      #
+      # @param subject [Agentilda::Plans::Subject]
+      # @return [String]
+      def auto_letter(subject) = LETTERS.fetch(subject.pull_requests.size, LETTERS.last)
+
+      private
+
+      # @return [Hash]
+      def base_fields(subject, checkout, title)
+        { ordinal: subject.feature.ordinal, branch: checkout.branch, title: }
+      end
+
+      # @return [Agentilda::Vcs::Publisher::Publication]
+      def refuse(subject, checkout, title, why)
+        Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: why)
+      end
+
+      # @param checkout [Agentilda::Vcs::Worktree::Checkout]
+      # @param title [String]
+      # @return [void]
+      def commit(checkout, title)
+        run(checkout, "git", "add", "-A")
+        # The subject line drops the bracketed prefix: it belongs in the pull
+        # request title, where things join on it, not in every commit message.
+        run(checkout, "git", "commit", "-m", title.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
+      end
+
+      # @param checkout [Agentilda::Vcs::Worktree::Checkout]
+      # @return [void]
+      def push(checkout) = run(checkout, "git", "push", "-u", "origin", checkout.branch)
+
+      # @return [String, nil] the pull request URL
+      def create_pull_request(checkout, subject, title)
+        Tempfile.create(["pr", ".md"]) do |file|
+          file.write(description(subject, title))
+          file.flush
+          result = run(checkout, "gh", "pr", "create", "-a", "@me", "-B", @base, "-t", title, "-F", file.path)
+          return result.out.to_s[%r{https://\S+}]
+        end
+      end
+
+      # The body `/create-pr` would have written: a title line, a summary lifted
+      # from the specification, and a link back to the plan folder so a reviewer
+      # can find the rest.
+      #
+      # @return [String]
+      def description(subject, title)
+        <<~MARKDOWN
+          # #{title}
+
+          ## Summary
+
+          #{summary_text(subject)}
+
+          ## Plan
+
+          Implements `#{subject.feature.dirname}`. The specification and the plan
+          for this work live in that folder.
+        MARKDOWN
+      end
+
+      # The specification's own Goal section, verbatim. A pull request body that
+      # paraphrases the spec is a second copy that drifts; quoting it is not.
+      #
+      # @param subject [Agentilda::Plans::Subject]
+      # @return [String]
+      def summary_text(subject)
+        text = subject.goal.join("\n\n")
+        text.empty? ? "See `#{subject.feature.dirname}/spec.md`." : text
+      end
+
+      # @return [TTY::Command::Result]
+      def run(checkout, *argv) = @command.run(*argv, chdir: checkout.path)
+    end
+  end
+end

data/lib/agentilda/vcs/worktree.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "shellwords"
+
+module Agentilda
+  module Vcs
+    # A git worktree per plan, so agents working on different plans cannot
+    # collide at all.
+    #
+    # A lock coordinates a shared tree; a worktree removes the sharing. That
+    # matters more than it sounds for an agent loop: two agents editing one
+    # checkout produce no git conflict — same branch, same files — so the last
+    # writer simply wins and the loser's work vanishes with nothing anywhere to
+    # say it happened.
+    #
+    # The branch carries the plan number (`<user>/NNN.MM-slug`), which is not
+    # decoration: it is the first thing `resync prs` reads when deciding which
+    # plan a pull request implements. Naming branches this way means the number
+    # carries itself from worktree creation through to a merged pull request with
+    # nobody having to remember it.
+    class Worktree
+      # `bin/setup-worktree`, which copies in the ignored-but-required files a new
+      # checkout does not get. Shelling out rather than reimplementing the rules
+      # here keeps one answer to "what does a worktree need", and keeps that answer
+      # usable from a shell on a machine that has never run `bundle install`.
+      SEEDER = File.expand_path("../../../bin/setup-worktree", __dir__)
+
+      # One plan's isolated checkout.
+      #
+      # @!attribute [r] ordinal
+      #   @return [Agentilda::Plans::Ordinal]
+      # @!attribute [r] branch
+      #   @return [String]
+      # @!attribute [r] path
+      #   @return [String] absolute
+      # @!attribute [r] created
+      #   @return [Boolean] false when an existing worktree was reused
+      Checkout = Data.define(:ordinal, :branch, :path, :created) do
+        # @return [Boolean] whether the agent left anything behind
+        def dirty? = !`git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+        # @return [String] the plans directory inside this checkout
+        def plans_dir = File.join(path, Agentilda::PLANS_DIR)
+
+        # @return [Boolean] whether this round made it, rather than reusing one
+        def created? = created
+      end
+
+      # @param root [String] the main repository
+      # @param dir [String, nil] where worktrees go; defaults to a sibling
+      # @param user [String] branch namespace
+      def initialize(root:, dir: nil, user: ENV["USER"] || "agent")
+        @root = File.expand_path(root)
+        @user = user
+        @dir = File.expand_path(dir || default_dir)
+      end
+
+      # @return [String] the main repository
+      attr_reader :root
+
+      # @return [String] where worktrees are kept
+      attr_reader :dir
+
+      # @return [Boolean] whether root is a git repository at all
+      def repository? = system("git", "-C", root, "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
+
+      # Get, or create, the isolated checkout for one plan.
+      #
+      # The checkout is seeded before it is handed back, on both paths. `git
+      # worktree add` brings every TRACKED file and nothing else, so an agent
+      # given a bare one cannot run the suite it was told to keep green: a Rails
+      # project dies on `MissingKeyError` because `config/credentials/*.key` is
+      # gitignored. The agent then reports a broken checkout as a broken plan,
+      # which is the worst failure this loop has, because the diagnosis points
+      # at the code rather than at the tree.
+      #
+      # A reused worktree is seeded too. {#seed} only ever adds a missing file,
+      # so running it again costs one fast subprocess and repairs the worktrees
+      # that were created before any of this existed.
+      #
+      # @param feature [Agentilda::Plans::Feature]
+      # @return [Agentilda::Vcs::Worktree::Checkout]
+      # @raise [Agentilda::Error] when git refuses
+      def checkout_for(feature)
+        branch = branch_for(feature)
+        path = File.join(dir, "#{feature.ordinal}-#{feature.slug}")
+
+        if File.directory?(path)
+          seed(path)
+          return Checkout.new(ordinal: feature.ordinal, branch:, path:, created: false)
+        end
+
+        # git keeps a registration for a worktree whose directory was deleted by
+        # hand, marks it `prunable`, and then refuses to create a new one at that
+        # path. Anybody who has ever `rm -rf`d a worktree meets this, and the
+        # error says only "already exists" about a directory that does not.
+        forget_stale
+
+        FileUtils.mkdir_p(dir)
+        add(branch, path)
+        seed(path)
+        Checkout.new(ordinal: feature.ordinal, branch:, path:, created: true)
+      end
+
+      # Copy in the files git ignores and a new checkout therefore lacks: `.env`
+      # and friends, and credential keys.
+      #
+      # Never fatal. A repository with no ignored files is perfectly normal, and
+      # a plan is not worth abandoning over a seeding step, so this notes it and
+      # carries on.
+      #
+      # The note goes to the progress log, never the terminal: this runs while
+      # the ratatui dashboard owns the screen, and a line written to STDERR
+      # lands on top of an agent's row. The seeder's own output is silenced for
+      # the same reason. A suite that later dies on a missing key is explained
+      # by the log line.
+      #
+      # @param path [String] the worktree to seed
+      # @return [Boolean] whether the seeder ran and succeeded
+      def seed(path)
+        unless File.executable?(SEEDER)
+          UI.log("worktree: #{SEEDER} is missing, so #{path} has no .env or credential keys")
+          return false
+        end
+
+        return true if system(SEEDER, "--quiet", path, out: File::NULL, err: File::NULL)
+
+        UI.log("worktree: could not seed #{path}; its suite may fail on a missing key")
+        false
+      end
+
+      # @param feature [Agentilda::Plans::Feature]
+      # @return [String] e.g. "kig/002.00-tenancy-households"
+      def branch_for(feature) = "#{@user}/#{feature.ordinal}-#{feature.slug}"
+
+      # Every worktree this class manages, as git sees them.
+      #
+      # @return [Array<String>] absolute paths
+      def list
+        # Compare canonical paths. git reports resolved ones, and on macOS the
+        # temp and home trees run through symlinks (/var -> /private/var), so a
+        # raw string compare matches nothing and prune silently does nothing.
+        mine = canonical(dir)
+
+        `git -C #{root.shellescape} worktree list --porcelain 2>/dev/null`
+          .lines(chomp: true)
+          .filter_map { |l| l.delete_prefix("worktree ") if l.start_with?("worktree ") }
+          .select { |p| canonical(p).start_with?(mine) }
+      end
+
+      # @param path [String]
+      # @return [String] the symlink-resolved path, or the input when it is gone
+      def canonical(path)
+        File.realpath(path)
+      rescue Errno::ENOENT
+        path
+      end
+
+      # Remove worktrees the agents left untouched.
+      #
+      # An agent that ran and changed nothing has produced a checkout that is
+      # pure cost: it looks like work in progress and is not. Dirty ones are
+      # always kept — that is the output.
+      #
+      # @return [Array<String>] paths removed
+      def prune
+        list.select { |path| clean?(path) }.each { |path| remove(path) }
+      end
+
+      # @param path [String]
+      # @return [void]
+      def remove(path)
+        system("git", "-C", root, "worktree", "remove", "--force", path, out: File::NULL, err: File::NULL)
+      end
+
+      private
+
+      # Sibling of the repository, not inside it: a worktree under the repo shows
+      # up in its own `git status` and in every glob anybody writes.
+      #
+      # @return [String]
+      def default_dir = "#{@root}.worktrees"
+
+      # Drop registrations whose directory is gone.
+      #
+      # @return [void]
+      def forget_stale
+        system("git", "-C", root, "worktree", "prune", out: File::NULL, err: File::NULL)
+      end
+
+      # @param path [String]
+      # @return [Boolean]
+      def clean?(path) = `git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+      # @param branch [String]
+      # @param path [String]
+      # @return [void]
+      def add(branch, path)
+        exists = system("git", "-C", root, "show-ref", "--verify", "--quiet", "refs/heads/#{branch}")
+        args = exists ? ["worktree", "add", path, branch] : ["worktree", "add", "-b", branch, path]
+
+        return if system("git", "-C", root, *args, out: File::NULL, err: File::NULL)
+
+        raise Error, "could not create a worktree for #{branch} at #{path}"
+      end
+    end
+  end
+end

data/lib/agentilda/vcs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Git and GitHub: a checkout per plan, pushing a branch, and reading
+  # pull requests. Everything that leaves the machine leaves through here.
+  module Vcs
+    module_function
+
+    # @return [Agentilda::Vcs::GitHub]
+    def github = GitHub.new
+
+    # @param root [String] repository root
+    # @return [Agentilda::Vcs::Worktree]
+    def worktree(root:, **) = Worktree.new(root:, **)
+
+    # @return [Agentilda::Vcs::Publisher]
+    def publisher(**) = Publisher.new(**)
+  end
+end

data/lib/agentilda/version.rb

@@ -6,5 +6,5 @@
 #
 # © 2026 Konstantin Gredeskoul
 module Agentilda
-  VERSION = "2.0.1"
+  VERSION = "2.0.4"
 end

data/lib/agentilda.rb

@@ -19,6 +19,7 @@ loader.inflector.inflect(
   "unit"       => "Units",
   "ui"         => "UI"
 )
+loader.collapse("#{__dir__}/agentilda/support")
 loader.collapse("#{__dir__}/agentilda/cli/create")
 loader.collapse("#{__dir__}/agentilda/cli/docs")
 loader.collapse("#{__dir__}/agentilda/cli/index")
@@ -115,13 +116,13 @@ module Agentilda
   #
   # @param root [String] repository root
   # @param ref [String] a branch name; `origin/` is tried first
-  # @return [Array<Agentilda::Ordinal>] possibly empty
+  # @return [Array<Agentilda::Plans::Ordinal>] possibly empty
   def self.plans_on_ref(root, ref)
     ["origin/#{ref}", ref].each do |candidate|
       out = `git -C #{root.shellescape} ls-tree -d --name-only #{candidate.shellescape} #{PLANS_DIR}/ 2>/dev/null`
       next if out.to_s.strip.empty?
 
-      return out.lines.filter_map { |line| Ordinal.from_dirname(File.basename(line.strip)) }
+      return out.lines.filter_map { |line| Plans::Ordinal.from_dirname(File.basename(line.strip)) }
     end
     []
   end
@@ -134,9 +135,9 @@ module Agentilda
   class Error < StandardError; end
 end
 
-# status.rb and feature.rb define methods on Agentilda itself (`status`,
+# plans/status.rb and plans/feature.rb define methods on Agentilda::Plans (`status`,
 # `plan_dirname`, `titleize` and friends) beside the class each is named for.
 # Zeitwerk loads a file when its constant is first named, and a caller of
-# `Agentilda.status` names no constant, so without this those methods exist
+# `Plans.status` names no constant, so without this those methods exist
 # or not depending on what happened to load first.
-%w[status feature].each { |name| loader.load_file("#{__dir__}/agentilda/#{name}.rb") }
+%w[status feature].each { |name| loader.load_file("#{__dir__}/agentilda/plans/#{name}.rb") }