agentilda 2.0.1 → 2.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b707f3c9d7c48b2983152af1c7561480f1191a38b9d4998c28e8756dbf08c149
-  data.tar.gz: 40f6f8f9764077d3f0120a76e9d6963465f763d6c8092a178d49973e6597198b
+  metadata.gz: 2c9a4385f83c40b57a76438a289cf74e55f7b9ca9814fea4c3da588ff3ae44a2
+  data.tar.gz: 6623390360484fd07adf1424c59ab67a6552da4d19ceb7d130bb6d7957ef6197
 SHA512:
-  metadata.gz: 866812a595b01d7e57303414a8b91dc330498b87d117218119561d29420401ea252d6734e56dc34b0cdf07e85c9f81ea95e1ff2b295e0e332defc091f0a05ddc
-  data.tar.gz: c716f989842f5400829f9ab1be7dba8817cd09c2b07b27eb2cacb7680c8c366bfef7d20e7c9053dd69909181ac5ba730fd916a82f96e13ae90ac828b7fcb42c3
+  metadata.gz: 2789d3e66bc6717cd7fdeff4f8ab2aaa3d85aadacc31ef01830dda9a108116512bfd5c498ffc17a69f0fd3aaa1ce7fb0a9ceae8e1c7cd011efdd98a2d4379f76
+  data.tar.gz: b28ee786d2f7696ade7d640080eaaef60132c2ddc6fe53bc5eabc5dc3c687098e63cc08ae1c30d7fd83b25e4b169c1d176351d188d483d4304cf6215931d7776

data/lib/agentilda/agents/agent.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Agents
+    # One specialist, loaded from `~/.agents/agents/<name>.md`.
+    #
+    # The definition files are the single source of truth for who does what: the
+    # frontmatter says which plan states this agent handles and what it may write,
+    # and the body is the prompt. Nothing about a specialty is duplicated in Ruby.
+    #
+    # @!attribute [r] name
+    #   @return [String]
+    # @!attribute [r] description
+    #   @return [String]
+    # @!attribute [r] handles
+    #   @return [Array<Symbol>] plan states this agent is offered work from
+    # @!attribute [r] advances_to
+    #   @return [Symbol, nil] the state it is expected to reach; nil = read-only
+    # @!attribute [r] model
+    #   @return [String, nil]
+    # @!attribute [r] allowed_tools
+    #   @return [Array<String>]
+    # @!attribute [r] may
+    #   @return [Array<String>] commands lifted from {Executor::FORBIDDEN_COMMANDS}
+    #     for this agent alone. Nothing in {Executor::UNGRANTABLE} can be lifted.
+    # @!attribute [r] timeout
+    #   @return [Integer, nil] seconds before this agent is abandoned; nil
+    #     defers to the executor's run-wide default
+    # @!attribute [r] ledger
+    #   @return [Array<String>] the documents this agent signs, in the order
+    #     it reaches them; the last entry it wrote is where it stands
+    # @!attribute [r] rounds
+    #   @return [Integer] how many times it may be invoked on one plan in one
+    #     state before the plan parks; a Completed never earns another
+    # @!attribute [r] effort
+    #   @return [String, nil] passed to `claude --effort`
+    # @!attribute [r] starts_as
+    #   @return [Symbol, nil] the state the harness renames the plan into the
+    #     moment this agent is dispatched, where the topology permits it
+    # @!attribute [r] holds_at
+    #   @return [Symbol, nil] the state the plan takes when this agent completes
+    #     while its partner on the same plan is still running
+    Agent = Data.define(:name,
+      :description,
+      :handles,
+      :advances_to,
+      :model,
+      :allowed_tools,
+      :may,
+      :network,
+      :timeout,
+      :prompt,
+      :path,
+      :ledger,
+      :rounds,
+      :effort,
+      :starts_as,
+      :holds_at) do
+      def initialize(ledger: [], rounds: 1, effort: nil, starts_as: nil, holds_at: nil, **rest) = super
+
+      # @return [Boolean] whether this agent changes anything on disk
+      def read_only? = advances_to.nil?
+
+      # @param status [Agentilda::Plans::Status]
+      # @return [Boolean]
+      def handles?(status) = handles.include?(status.key)
+
+      # The word after the hyphen: `researcher`, `backend`. What the screen's
+      # agent column shows, the name being too long for it.
+      #
+      # @return [String]
+      def role = name.split("-", 2).last.to_s
+    end
+
+    # More rounds than this costs tokens and buys nothing: an agent that has
+    # not finished in five tries is not going to on the sixth.
+    Agent::MAX_ROUNDS = 5
+  end
+end

data/lib/agentilda/agents/registry.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Agents
+    # Loads and indexes the agent definitions.
+    class Registry
+      # Where definitions live, unless told otherwise.
+      DEFAULT_DIR = File.expand_path("../../../agents", __dir__)
+
+      # @param dir [String]
+      # @param roster [Array<Agentilda::Agents::Agent>, nil] a pre-selected list, used
+      #   by {#only} and {#without} to derive a narrower roster; nil (the
+      #   default) loads every definition in `dir`
+      def initialize(dir: DEFAULT_DIR, roster: nil)
+        @dir = File.expand_path(dir)
+        @all = roster
+      end
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [Array<Agentilda::Agents::Agent>] in name order
+      def all
+        @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
+      end
+
+      # @param name [String]
+      # @return [Agentilda::Agents::Agent, nil]
+      def find(name) = all.find { |a| a.name == name.to_s }
+
+      # A roster holding only the agents named — what `run --agent` hands the
+      # loop, so a restriction typed at the command line restricts assignments
+      # and not merely chaining.
+      #
+      # @param names [Array<String>]
+      # @return [Agentilda::Agents::Registry]
+      def only(*names)
+        wanted = names.flatten.map(&:to_s)
+        self.class.new(dir:, roster: all.select { |a| wanted.include?(a.name) })
+      end
+
+      # A roster without the agents named — what `run --skip` hands the loop.
+      # A plan sitting in a skipped agent's state is simply never assigned, the
+      # same way a state no agent handles is stepped around.
+      #
+      # @param names [Array<String>]
+      # @return [Agentilda::Agents::Registry]
+      def without(*names)
+        unwanted = names.flatten.map(&:to_s)
+        self.class.new(dir:, roster: all.reject { |a| unwanted.include?(a.name) })
+      end
+
+      # Every agent the query could mean. An exact name wins outright; failing
+      # that the query matches as a prefix, and failing that anywhere in the
+      # name, so `leah` finds leah-researcher and `review` finds
+      # hansolo-reviewer. A directory or a trailing `.md` is stripped first,
+      # because tab completion hands those in.
+      #
+      # @param query [String]
+      # @return [Array<Agentilda::Agents::Agent>]
+      def match(query)
+        wanted = File.basename(query.to_s, ".md")
+        exact = all.select { |a| a.name == wanted }
+        return exact unless exact.empty?
+
+        prefixed = all.select { |a| a.name.start_with?(wanted) }
+        return prefixed unless prefixed.empty?
+
+        all.select { |a| a.name.include?(wanted) }
+      end
+
+      # Every agent that will act on a plan in this state, in definition order.
+      # A read-only agent is never offered work by the loop — it has nothing to
+      # advance, so including it would make every round look productive.
+      #
+      # @param status [Agentilda::Plans::Status]
+      # @return [Array<Agentilda::Agents::Agent>]
+      def for_status(status) = all.select { |a| a.handles?(status) && !a.read_only? }
+
+      # Everyone on a plan in this state: the agents that work it, plus any
+      # agent whose `holds_at` parks the plan here after it finished its half.
+      # Rey resuming a plan at 🎨 still needs luke's messages in the mailbox.
+      #
+      # @param status [Agentilda::Plans::Status]
+      # @return [Array<Agentilda::Agents::Agent>]
+      def team_for(status) = all.select { |a| !a.read_only? && (a.handles?(status) || a.holds_at == status.key) }
+
+      private
+
+      # @param path [String]
+      # @return [Agentilda::Agents::Agent, nil]
+      def parse(path)
+        meta, body = Frontmatter.split(File.read(path, encoding: "UTF-8"))
+        return nil if meta["name"].to_s.empty?
+
+        Agent.new(
+          name:          meta["name"].to_s,
+          description:   meta["description"].to_s,
+          handles:       Array(meta["handles"]).map { |s| s.to_s.to_sym },
+          advances_to:   meta["advances_to"]&.to_s&.then { |s| s.empty? ? nil : s.to_sym },
+          model:         meta["model"],
+          allowed_tools: Array(meta["allowed_tools"]).map(&:to_s),
+          may:           Array(meta["may"]).map { |c| c.to_s.strip.squeeze(" ") },
+          network:       meta["network"] == true,
+          timeout:       meta["timeout"].to_i.then { |s| s.positive? ? s : nil },
+          prompt:        body.strip,
+          path:          path,
+          ledger:        Array(meta["ledger"]).map(&:to_s),
+          rounds:        meta["rounds"].to_i.clamp(1, Agent::MAX_ROUNDS),
+          effort:        meta["effort"]&.to_s,
+          starts_as:     symbol_or_nil(meta["starts_as"]),
+          holds_at:      symbol_or_nil(meta["holds_at"])
+        )
+      end
+
+      # @param value [Object, nil]
+      # @return [Symbol, nil]
+      def symbol_or_nil(value) = value.to_s.empty? ? nil : value.to_s.to_sym
+    end
+  end
+end

data/lib/agentilda/agents/roster.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Agents
+    # `agentilda agents` — who the specialists are and what each is offered
+    # work from. Reading one in full is {Viewer}'s job: the definition file is
+    # already the whole truth, so `agents describe` opens it rather than
+    # restating it.
+    #
+    # {#list} returns a string and prints nothing, the same bargain {Reporter}
+    # makes, so the caller decides where the text goes and the table stays
+    # pipeable.
+    #
+    # Everything here is read from the definition files. Nothing about a
+    # specialty is restated in Ruby, because a second copy of "who does what" is
+    # a copy that drifts from the frontmatter the loop actually routes on.
+    class Roster
+      # Columns, so the header and the rows cannot drift apart.
+      HEADINGS = ["Agent", "Handles", "Advances to", "Model"].freeze
+
+      # What an agent with no `advances_to` is, in the one word that explains why
+      # `run` never offers it work.
+      READ_ONLY = "read-only"
+
+      # What an agent that handles only {StateMachine::SETTLED} states advances
+      # to. `run` never starts it; a command does, and `resync` then names the
+      # folder by what its files justify.
+      BY_CONTENTS = "by contents"
+
+      # @param agents [Agentilda::Agents::Registry]
+      def initialize(agents: Registry.new)
+        @agents = agents
+      end
+
+      # @return [Agentilda::Agents::Registry]
+      attr_reader :agents
+
+      # One row per agent, in name order, framed by {UI.table}.
+      #
+      # @return [String] newline-terminated
+      def list
+        all = agents.all
+        return "No agent definitions in #{agents.dir}\n" if all.empty?
+
+        UI.table(all.map { |agent| row(agent) }, header: HEADINGS)
+      end
+
+      private
+
+      # A state as its words alone, deliberately without the emoji that every
+      # other rendering of a state carries. The table widget pads a cell to a
+      # width it measures in characters, while the terminal draws a status emoji
+      # in two cells; the variation-selector ones (⭕️ 🅱️ ⚪️ ⭐️ 🕰️) are two
+      # characters drawn in two cells, so no single count is right for all of
+      # them. A row carrying one lands short or long and the frame stops lining
+      # up. The label says the same thing unambiguously, and is worth more than
+      # the emoji is. {Reporter} lays its own columns out with {UI.fit} and so
+      # keeps the emoji.
+      #
+      # @param key [Symbol]
+      # @return [String]
+      def state(key)
+        status = Plans::STATUS_BY_KEY[key] or return key.to_s
+        status.label
+      end
+
+      # @param agent [Agentilda::Agents::Agent]
+      # @return [String]
+      def handles(agent) = agent.handles.map { |key| state(key) }.join(", ")
+
+      # @param agent [Agentilda::Agents::Agent]
+      # @return [String]
+      def advances(agent)
+        return state(agent.advances_to) if agent.advances_to
+        return BY_CONTENTS if agent.handles.any? && agent.handles.all? { |key| Plans::StateMachine::SETTLED.include?(key) }
+
+        READ_ONLY
+      end
+
+      # The widget measures and pads the cells, so they arrive painted only.
+      #
+      # @param agent [Agentilda::Agents::Agent]
+      # @return [Array<String>] one cell per entry in {HEADINGS}
+      def row(agent)
+        [UI.paint(agent.name, :bright_cyan),
+         handles(agent),
+         UI.paint(advances(agent), agent.read_only? ? :bright_black : :green),
+         UI.paint(agent.model.to_s, :bright_black)]
+      end
+    end
+  end
+end

data/lib/agentilda/agents.rb

@@ -1,122 +1,20 @@
 # frozen_string_literal: true
 
-require "agentilda/agent"
-require "agentilda/frontmatter"
-
 module Agentilda
-  # Loads and indexes the agent definitions.
-  class Agents
-    # Where definitions live, unless told otherwise.
-    DEFAULT_DIR = File.expand_path("../../agents", __dir__)
-
-    # @param dir [String]
-    # @param roster [Array<Agentilda::Agent>, nil] a pre-selected list, used
-    #   by {#only} and {#without} to derive a narrower roster; nil (the
-    #   default) loads every definition in `dir`
-    def initialize(dir: DEFAULT_DIR, roster: nil)
-      @dir = File.expand_path(dir)
-      @all = roster
-    end
+  # The specialists: their definitions in `agents/*.md`, the registry that
+  # loads and filters them, and the roster that reports on them.
+  module Agents
+    module_function
 
-    # @return [String]
-    attr_reader :dir
-
-    # @return [Array<Agentilda::Agent>] in name order
-    def all
-      @all ||= Dir.glob(File.join(dir, "*.md")).sort.filter_map { |path| parse(path) }
-    end
+    # @param dir [String] where the definitions live
+    # @return [Agentilda::Agents::Registry]
+    def registry(dir: Registry::DEFAULT_DIR) = Registry.new(dir:)
 
     # @param name [String]
-    # @return [Agentilda::Agent, nil]
-    def find(name) = all.find { |a| a.name == name.to_s }
-
-    # A roster holding only the agents named — what `run --agent` hands the
-    # loop, so a restriction typed at the command line restricts assignments
-    # and not merely chaining.
-    #
-    # @param names [Array<String>]
-    # @return [Agentilda::Agents]
-    def only(*names)
-      wanted = names.flatten.map(&:to_s)
-      self.class.new(dir:, roster: all.select { |a| wanted.include?(a.name) })
-    end
-
-    # A roster without the agents named — what `run --skip` hands the loop.
-    # A plan sitting in a skipped agent's state is simply never assigned, the
-    # same way a state no agent handles is stepped around.
-    #
-    # @param names [Array<String>]
-    # @return [Agentilda::Agents]
-    def without(*names)
-      unwanted = names.flatten.map(&:to_s)
-      self.class.new(dir:, roster: all.reject { |a| unwanted.include?(a.name) })
-    end
-
-    # Every agent the query could mean. An exact name wins outright; failing
-    # that the query matches as a prefix, and failing that anywhere in the
-    # name, so `leah` finds leah-researcher and `review` finds
-    # hansolo-reviewer. A directory or a trailing `.md` is stripped first,
-    # because tab completion hands those in.
-    #
-    # @param query [String]
-    # @return [Array<Agentilda::Agent>]
-    def match(query)
-      wanted = File.basename(query.to_s, ".md")
-      exact = all.select { |a| a.name == wanted }
-      return exact unless exact.empty?
-
-      prefixed = all.select { |a| a.name.start_with?(wanted) }
-      return prefixed unless prefixed.empty?
-
-      all.select { |a| a.name.include?(wanted) }
-    end
-
-    # Every agent that will act on a plan in this state, in definition order.
-    # A read-only agent is never offered work by the loop — it has nothing to
-    # advance, so including it would make every round look productive.
-    #
-    # @param status [Agentilda::Status]
-    # @return [Array<Agentilda::Agent>]
-    def for_status(status) = all.select { |a| a.handles?(status) && !a.read_only? }
-
-    # Everyone on a plan in this state: the agents that work it, plus any
-    # agent whose `holds_at` parks the plan here after it finished its half.
-    # Rey resuming a plan at 🎨 still needs luke's messages in the mailbox.
-    #
-    # @param status [Agentilda::Status]
-    # @return [Array<Agentilda::Agent>]
-    def team_for(status) = all.select { |a| !a.read_only? && (a.handles?(status) || a.holds_at == status.key) }
-
-    private
-
-    # @param path [String]
-    # @return [Agentilda::Agent, nil]
-    def parse(path)
-      meta, body = Frontmatter.split(File.read(path, encoding: "UTF-8"))
-      return nil if meta["name"].to_s.empty?
-
-      Agent.new(
-        name:          meta["name"].to_s,
-        description:   meta["description"].to_s,
-        handles:       Array(meta["handles"]).map { |s| s.to_s.to_sym },
-        advances_to:   meta["advances_to"]&.to_s&.then { |s| s.empty? ? nil : s.to_sym },
-        model:         meta["model"],
-        allowed_tools: Array(meta["allowed_tools"]).map(&:to_s),
-        may:           Array(meta["may"]).map { |c| c.to_s.strip.squeeze(" ") },
-        network:       meta["network"] == true,
-        timeout:       meta["timeout"].to_i.then { |s| s.positive? ? s : nil },
-        prompt:        body.strip,
-        path:          path,
-        ledger:        Array(meta["ledger"]).map(&:to_s),
-        rounds:        meta["rounds"].to_i.clamp(1, Agent::MAX_ROUNDS),
-        effort:        meta["effort"]&.to_s,
-        starts_as:     symbol_or_nil(meta["starts_as"]),
-        holds_at:      symbol_or_nil(meta["holds_at"])
-      )
-    end
+    # @return [Agentilda::Agents::Agent, nil]
+    def find(name, dir: Registry::DEFAULT_DIR) = registry(dir:).find(name)
 
-    # @param value [Object, nil]
-    # @return [Symbol, nil]
-    def symbol_or_nil(value) = value.to_s.empty? ? nil : value.to_s.to_sym
+    # @return [Agentilda::Agents::Roster]
+    def roster(**) = Roster.new(**)
   end
 end

data/lib/agentilda/cli/agents/subcommands/describe.rb

@@ -30,9 +30,9 @@ module Agentilda
         # default to the real thing; the suite hands in its own to keep
         # viewers from opening on the box running it.
         #
-        # @param agents [Agentilda::Agents]
-        # @param viewer [Agentilda::Viewer]
-        def initialize(agents: Agentilda::Agents.new, viewer: Viewer.new)
+        # @param agents [Agentilda::Agents::Registry]
+        # @param viewer [Agentilda::Presentation::Viewer]
+        def initialize(agents: Agentilda::Agents.registry, viewer: Presentation.viewer)
           super()
           @agents = agents
           @viewer = viewer

data/lib/agentilda/cli/agents/subcommands/list.rb

@@ -13,7 +13,7 @@ module Agentilda
         example ["", "| less -R"]
 
         # @return [void]
-        def call(**) = $stdout.write(Roster.new.list)
+        def call(**) = $stdout.write(Agentilda::Agents.roster.list)
       end
     end
   end

data/lib/agentilda/cli/base.rb

@@ -51,9 +51,9 @@ module Agentilda
       private
 
       # @param options [Hash]
-      # @return [Agentilda::Tree]
+      # @return [Agentilda::Plans::Tree]
       def tree_for(options)
-        tree = Tree.new(dir: options.fetch(:dir, Agentilda::PLANS_DIR))
+        tree = Plans.tree(options.fetch(:dir, Agentilda::PLANS_DIR))
         unless tree.exist?
           refuse("No #{Agentilda::PLANS_DIR} directory at\n#{tree.dir}\n\n" \
                  "Run this from the project root, or pass -D.",
@@ -101,7 +101,7 @@ module Agentilda
       #
       # @return [void]
       def credentials_warning
-        names = Executor.foreign_credentials
+        names = Execution::Executor.foreign_credentials
         return if names.empty?
 
         one = names.size == 1

data/lib/agentilda/cli/create/create.rb

@@ -67,12 +67,11 @@ module Agentilda
         words, seed = resolve_seed(words, options)
         prs = fetch_prs(options)
         result =
-          Creator.new(dir:).create(
+          Lifecycle.create(dir:,
             words:,
-            after: options[:after],
+            after:  options[:after],
             status: options[:status],
-            prs:
-          )
+            prs:)
 
         result.either(
           ->(path) { created(path, prs, options, seed:) },
@@ -159,7 +158,7 @@ module Agentilda
           )
         end
 
-        GitHub.new.pull_requests(GitHub.parse_refs(options[:prs]))
+        Vcs.github.pull_requests(Vcs::GitHub.parse_refs(options[:prs]))
       rescue Agentilda::Error => e
         refuse("Could not read the pull requests:\n#{e.message}", 65)
       end
@@ -183,7 +182,7 @@ module Agentilda
         puts path
         return if quiet?(options)
 
-        feature = Feature.parse(path)
+        feature = Plans::Feature.parse(path)
         success(
           "Created #{File.basename(path)}\n\n" \
           "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
@@ -199,17 +198,17 @@ module Agentilda
       # @param options [Hash]
       # @return [String] the folder's path, which the resync may have renamed
       def synthesize(path, options)
-        agent = Agentilda::Agents.new.find(Agentilda::RETROACTIVE_WRITER) or
+        agent = Agentilda::Agents.registry.find(Agentilda::RETROACTIVE_WRITER) or
           return path
         root = options[:root] || File.dirname(path, 2)
 
-        feature = Feature.parse(path)
+        feature = Plans::Feature.parse(path)
         ok, note = on_agent_row("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}",
           agent: agent.name,
           plan:  feature.ordinal.to_s,
           root:) do |line|
-          handle = line.handle if line.is_a?(Dashboard::Tracker)
-          Executor.new(root:).call(agent, Subject.new(feature), handle:, &line)
+          handle = line.handle if line.is_a?(Presentation::Dashboard::Tracker)
+          Execution.executor(root:).call(agent, Plans.subject(feature), handle:, &line)
         end
         warn_about(note) unless ok
 
@@ -228,19 +227,19 @@ module Agentilda
       # @param options [Hash] the options hash
       # @return [String] +path+, unchanged
       def brief(path, options, seed: nil)
-        feature = Feature.parse(path)
+        feature = Plans::Feature.parse(path)
         return path if feature.status.key == :retroactive
 
         root = options[:root] || File.dirname(path, 2)
-        brief = Brief.new(path:, title: feature.title, root:, seed:)
+        brief = Lifecycle.brief(path:, title: feature.title, root:, seed:)
         brief.write_scaffold!
 
         if options.fetch(:draft, true)
           # Painted the way Runner::Task#label paints a roster agent, so the
           # half-agent reads as one of them on the terminal.
           label =
-            "#{UI.paint(Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
-          ok, note = on_agent_row(label, agent: Brief::AGENT_NAME, plan: feature.ordinal.to_s, root:) { brief.attempt! }
+            "#{UI.paint(Lifecycle::Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
+          ok, note = on_agent_row(label, agent: Lifecycle::Brief::AGENT_NAME, plan: feature.ordinal.to_s, root:) { brief.attempt! }
           warn_about_draft(note) unless ok
         end
 
@@ -258,7 +257,7 @@ module Agentilda
       # @yieldparam line [Agentilda::UI::Line]
       # @return [Object] the block's value
       def on_agent_row(label, agent:, plan:, root:, &block)
-        Control.on_interrupt do
+        Execution.on_interrupt do
           UI.concurrently([plan],
             label,
             jobs:   1,
@@ -287,9 +286,9 @@ module Agentilda
       # @param path [String]
       # @return [String] where the folder ended up
       def settle(path)
-        tree = Tree.new(dir: File.dirname(path))
+        tree = Plans.tree(File.dirname(path))
         change =
-          Agentilda::Resync::Dirs
+          Agentilda::Lifecycle::Resync::Dirs
           .new(tree:)
           .call(commit: true)
           .find { |c| c.source == path }
@@ -315,7 +314,7 @@ module Agentilda
       end
 
       # @param path [String]
-      # @param feature [Agentilda::Feature]
+      # @param feature [Agentilda::Plans::Feature]
       # @return [String]
       def next_step(path, feature, from_prs:)
         spec = File.join(File.basename(path), "spec.md")

data/lib/agentilda/cli/docs/docs.rb

@@ -18,7 +18,7 @@ module Agentilda
       # @param options [Hash]
       # @return [void]
       def call(**options)
-        document = Documentation.new.render
+        document = Presentation.documentation
 
         if (path = options[:output])
           FileUtils.mkdir_p(File.dirname(path))

data/lib/agentilda/cli/index/index.rb

@@ -22,7 +22,7 @@ module Agentilda
       # @param options [Hash]
       # @return [void]
       def call(**options)
-        index = Agentilda::Index.new(tree: tree_for(options), project: options[:project])
+        index = Agentilda::Plans.index(tree: tree_for(options), project: options[:project])
 
         if options[:output] == "-"
           $stdout.write(index.render)

data/lib/agentilda/cli/linear/subcommands/import.rb

@@ -106,7 +106,7 @@ module Agentilda
           return nil unless options[:status]
 
           options[:status].to_s.split(",").map { |word|
-            Agentilda.status(word.strip)&.key ||
+            Agentilda::Plans.status(word.strip)&.key ||
               raise(Agentilda::Error, "no such state: #{word.strip}")
           }
         end

data/lib/agentilda/cli/list_plans/list_plans.rb

@@ -11,7 +11,7 @@ module Agentilda
       # @param options [Hash]
       # @return [void]
       def call(**options)
-        reporter = Reporter.new(tree: tree_for(options))
+        reporter = Presentation.reporter(tree: tree_for(options))
         $stdout.write(reporter.render)
 
         exit 1 unless reporter.inconsistent.empty?

data/lib/agentilda/cli/mail/mail.rb

@@ -3,7 +3,7 @@
 module Agentilda
   module CLI
     # `agentilda mail` — the two halves of a pair talking through the plan
-    # folder. See {Agentilda::Mailbox} for why a file rather than a session.
+    # folder. See {Agentilda::Plans::Mailbox} for why a file rather than a session.
     module Mail
       # Both subcommands name a plan and need its folder.
       module Locating
@@ -14,16 +14,16 @@ module Agentilda
         # silence as "my partner has nothing to say".
         #
         # @param options [Hash]
-        # @return [Agentilda::Mailbox]
+        # @return [Agentilda::Plans::Mailbox]
         def mailbox_for(options)
           tree = tree_for(options)
-          ordinal = Ordinal.parse(options[:plan].to_s)
+          ordinal = Plans::Ordinal.parse(options[:plan].to_s)
           subject = ordinal && tree.find(ordinal)
           unless subject
             refuse("No plan #{options[:plan]} in #{tree.dir}.\n\nKnown: #{tree.ordinals.join(", ")}", 66)
           end
 
-          Mailbox.new(dir: subject.feature.path)
+          Plans.mailbox(subject.feature.path)
         end
       end
     end

data/lib/agentilda/cli/mail/subcommands/send.rb

@@ -35,7 +35,7 @@ module Agentilda
 
           # One line, not a box: an agent runs this between steps, and a
           # four-line frame around "#7 → rey-frontend" is noise it reads.
-          UI.line("##{message.number} → #{message.to}, in #{File.basename(mailbox.dir)}/#{Mailbox::FILENAME}")
+          UI.line("##{message.number} → #{message.to}, in #{File.basename(mailbox.dir)}/#{Plans::Mailbox::FILENAME}")
         end
       end
     end