agentilda 2.0.3 → 2.0.4

data/lib/agentilda/plans/pull_request.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Plans
+    # One row of a plan's `pull-requests.md`.
+    #
+    # @!attribute [r] number
+    #   @return [String, nil] as written, without the `#`
+    # @!attribute [r] title
+    #   @return [String]
+    # @!attribute [r] url
+    #   @return [String, nil]
+    # @!attribute [r] state
+    #   @return [String] normalised words plus emoji, e.g. "Open 🟡"
+    PullRequest = Data.define(:number, :title, :url, :state) do
+      # Still awaiting a decision. A closed-unmerged pull request is finished
+      # business, so it is neither open nor merged.
+      #
+      # @return [Boolean]
+      def open? = state.match?(/\b(?:open|wip|draft)\b/i)
+
+      # @return [Boolean]
+      def merged? = state.match?(/\bmerged\b/i) && !state.match?(/\bunmerged\b/i)
+
+      # @return [String] "#92 — Send mail through Resend"
+      def label = number ? "##{number} — #{title}" : title
+    end
+  end
+end

data/lib/agentilda/plans/pull_requests.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Plans
+    # Extracts the pull request roll-up from a plan folder.
+    class PullRequests
+      # A markdown link whose text may contain escaped brackets, because every
+      # title this tool writes now opens with `\[NNN.MM\]`. Matching `[^\]]+`
+      # stops at the escaped `]` and loses the URL with it.
+      LINK = /\[((?:\\.|[^\]\\])+)\]\((https?:[^)\s]+)\)/
+
+      # Canonical wording for the states we recognise, most specific first.
+      STATES = [
+        [/\bclosed\b|\bunmerged\b|\babandoned\b/i, "Closed 🔴"],
+        [/\bmerged\b/i, "Merged 🟣"],
+        [/\bdraft\b|\bwip\b/i, "WIP 🟡"],
+        [/\bopen\b/i, "Open 🟡"]
+      ].freeze
+
+      # Filenames that may hold the table.
+      CANDIDATES = %w[pull-requests.md pull_requests.md prs.md].freeze
+
+      # The file this class writes, and the first one it looks for.
+      FILENAME = CANDIDATES.first
+
+      # Render `pull-requests.md` for a set of pull requests fetched from GitHub.
+      #
+      # The table is what {#parse} reads back and what the state machine judges
+      # a folder by. The descriptions below it are for a reader — human or
+      # agent — synthesizing a specification from work that already shipped:
+      # the table says *which* pull requests, the bodies say *what they did*,
+      # and a retroactive `spec.md` cannot be written from numbers alone.
+      #
+      # Prose after the table is ignored by the parser, so the two can coexist
+      # in one file rather than needing a scratch file the folder rules forbid.
+      #
+      # @param prs [Array<Hash>] `{number:, title:, url:, state:, body:}`
+      # @return [String]
+      def self.render(prs)
+        rows = prs.map { |pr|
+          "| #{pr[:number]} | [#{escape(pr[:title])}](#{pr[:url]}) | #{pr[:state]} |"
+        }
+
+        <<~MARKDOWN
+          # Pull Requests
+
+          | Pull Request Number | Pull Request Name | Status |
+          | ------------------: | :---------------- | -----: |
+          #{rows.join("\n")}
+
+          ## What these pull requests did
+
+          #{prs.map { |pr| describe(pr) }.join("\n")}
+        MARKDOWN
+      end
+
+      # The table alone, for splicing into a file that already says other
+      # things: the ledger blocks luke and rey write before a pull request
+      # exists. Rewriting the whole file deleted their signatures.
+      #
+      # @param prs [Array<Hash>]
+      # @return [String] header, rule and rows, newline-terminated
+      def self.table(prs)
+        rows = prs.map { |pr| "| #{pr[:number]} | [#{escape(pr[:title])}](#{pr[:url]}) | #{pr[:state]} |" }
+        ["| Pull Request Number | Pull Request Name | Status |",
+         "| ------------------: | :---------------- | -----: |", *rows].join("\n") + "\n"
+      end
+
+      # Write the table into +path+ without touching anything else there.
+      #
+      # @param path [String]
+      # @param prs [Array<Hash>]
+      # @return [void]
+      def self.upsert(path, prs)
+        return File.write(path, render(prs)) unless File.file?(path)
+
+        lines = File.read(path, encoding: "UTF-8").lines
+        start = lines.index { |l| l.strip.start_with?("|") && lines[lines.index(l) + 1].to_s.strip.start_with?("|") }
+        if start
+          stop = start
+          stop += 1 while lines[stop + 1]&.strip&.start_with?("|")
+          lines[start..stop] = [table(prs)]
+        else
+          at = lines.index { |l| l.start_with?("# ") }
+          insertion = ["\n", table(prs)]
+          at ? lines.insert(at + 1, *insertion) : lines.unshift("# Pull Requests\n", *insertion, "\n")
+        end
+        File.write(path, lines.join)
+      end
+
+      # @param pr [Hash]
+      # @return [String]
+      def self.describe(pr)
+        body = pr[:body].to_s.strip
+        body = "_No description was written on the pull request._" if body.empty?
+
+        <<~MARKDOWN
+          ### ##{pr[:number]} — #{pr[:title]}
+
+          #{pr[:url]}
+
+          #{body}
+        MARKDOWN
+      end
+
+      # Three characters have to survive a round trip through a table cell.
+      #
+      # A `|` ends the cell, and a title containing one is not unusual —
+      # "fix: guard against a || b".
+      #
+      # `[` and `]` are newer and cost more. Every title this tool writes now
+      # opens with a plan number, so the row reads `[[013.00] Ship it](url)` —
+      # and a markdown link whose text starts with `[` does not parse. The
+      # title came back with the URL glued to it and `url` came back nil, which
+      # is not a cosmetic loss: it is every pull request link on the page, and
+      # the attachment on every Linear issue.
+      #
+      # @param text [String]
+      # @return [String]
+      def self.escape(text)
+        text.to_s.gsub(/([\[\]|])/) { "\\#{$1}" }.gsub(/\s+/, " ").strip
+      end
+
+      # @param dir [String] absolute path to the plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [Array<Agentilda::Plans::PullRequest>] possibly empty
+      def all = @all ||= parse
+
+      private
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [Array<Agentilda::Plans::PullRequest>]
+      def parse
+        path = CANDIDATES.map { |f| File.join(dir, f) }.find { |p| File.file?(p) }
+        return [] unless path
+
+        text = File.read(path, encoding: "UTF-8")
+        table = pick_table(Markdown.tables(text))
+        return scrape(text) unless table
+
+        rows = table[:rows].filter_map { |cells| row_to_pr(cells, columns(table[:header])) }
+        rows.empty? ? scrape(text) : rows
+      end
+
+      # @param tables [Array<Hash>]
+      # @return [Hash, nil]
+      def pick_table(tables)
+        tables.find { |t|
+          t[:header].any? { |h| h.match?(/pull\s*request|\bpr\b|\A#\z|\Anumber\z/i) } &&
+            t[:rows].any? { |r| r.any? { |c| c.match?(%r{/(?:pull|merge_requests)/\d+}) } }
+        } || tables.find { |t| t[:rows].any? { |r| r.any? { |c| c.match?(%r{/pull/\d+}) } } }
+      end
+
+      # @param header [Array<String>]
+      # @return [Hash{Symbol => Integer, nil}]
+      def columns(header)
+        {
+          number: header.index { |h| h.match?(/number|\A#\z|\Apr\z|\Apr\s*#/i) },
+          title:  header.index { |h| h.match?(/name|title|summary|description|scope/i) },
+          state:  header.index { |h| h.match?(/status|state/i) }
+        }
+      end
+
+      # @param cells [Array<String>]
+      # @param idx [Hash{Symbol => Integer, nil}]
+      # @return [Agentilda::Plans::PullRequest, nil]
+      def row_to_pr(cells, idx)
+        title_cell = cells[idx[:title] || 1].to_s
+
+        # The title comes from the title column and the URL from wherever it is.
+        # Scanning every cell for the first link and taking both from it reads
+        # `| [#24](...) | Split verified into signed_off |` as an issue called
+        # "#24", because the number column is a link too and comes first.
+        titled = title_cell.match(LINK)
+        link = titled || cells.filter_map { |c| c.match(LINK) }.first
+
+        url = link && link[2]
+        title = titled ? titled[1] : unformat(title_cell)
+        title = title.gsub(/\\([\[\]|\\])/, '\1') # undo the escaping {.render} applies
+        number = cells[idx[:number] || 0].to_s[/\d+/] || url&.[](%r{/(?:pull|merge_requests)/(\d+)}, 1)
+        return nil if title.empty? && url.nil?
+
+        PullRequest.new(number:,
+          url:,
+          title: title.empty? ? "Pull request" : title,
+          state: normalize(cells[idx[:state] || -1].to_s))
+      end
+
+      # When there is no parsable table, scrape bare links so a folder that
+      # plainly has pull requests does not report none.
+      #
+      # @param text [String]
+      # @return [Array<Agentilda::Plans::PullRequest>]
+      def scrape(text)
+        text.scan(%r{https?://\S+?/(?:pull|merge_requests)/(\d+)}).flatten.uniq.map do |num|
+          PullRequest.new(number: num,
+            title: "Pull request ##{num}",
+            state: "Unknown",
+            url: text[%r{https?://\S+?/(?:pull|merge_requests)/#{num}\b}])
+        end
+      end
+
+      # Strip the markdown a title was wrapped in without eating the title.
+      #
+      # An underscore between letters is not emphasis, it is an identifier —
+      # `signed_off`, `as_of`, `pull_requests`. Removing every underscore turned
+      # "Split verified into signed_off" into "signedoff" on the way to Linear.
+      #
+      # @param cell [String]
+      # @return [String]
+      def unformat(cell)
+        cell.to_s.gsub(/[*`]/, "").sub(/\A_+/, "").sub(/_+\z/, "").strip
+      end
+
+      # @param cell [String]
+      # @return [String]
+      def normalize(cell)
+        STATES.each { |pattern, label| return label if cell.match?(pattern) }
+        stripped = cell.gsub(/[*_`]/, "").strip
+        stripped.empty? ? "Unknown" : stripped
+      end
+    end
+  end
+end

data/lib/agentilda/plans/state_machine.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require "aasm"
+
+module Agentilda
+  module Plans
+    # The state machine for one plan folder.
+    #
+    # The whole topology is the `aasm` block below, and it is nowhere else. To
+    # change what may follow what, edit an event's `from:` list. To add a state,
+    # add it to {STATUSES} and give it an event. There is no second table to keep
+    # in step: {inbound}, {outbound}, {edge?} and `terminal?` are all read back
+    # off these declarations.
+    #
+    # Two rules hold the rest together:
+    #
+    # 1. **The guard for entering a state is that state's own invariant.** There
+    #    is one guard method, {#justified?}, and it reads the destination off the
+    #    transition in flight — so a destination is named once, in `to:`.
+    # 2. **The state lives in the folder name.** There is no column and no
+    #    database. A successful transition renames the directory, which is why
+    #    firing an event is a real side effect and asking a question is not.
+    class StateMachine
+      include AASM
+
+      # Raised when a transition is refused, carrying the reason rather than
+      # AASM's "failed callback #17".
+      class Refused < Error; end
+
+      # The forward path a bare {#promote!} walks. Everything off this spine —
+      # blocking, deferring, discarding — has to be named explicitly, which is
+      # the entire reason for having a machine rather than a rename.
+      #
+      # 🔴 rejoins at 🎨 rather than continuing: fixing review comments puts the
+      # work back through both halves of building, it does not skip the reviewer
+      # and it does not assume the half nobody complained about still holds.
+      SPINE = {
+        retroactive:        :planned,
+        new:                :researched,
+        researched:         :ready_for_planning,
+        ready_for_planning: :planned,
+        planned:            :building,
+        building:           :building_ui,
+        building_ui:        :ready_for_review,
+        ready_for_review:   :in_review,
+        in_review:          :approved,
+        approved:           :deployed,
+        rejected:           :building_ui,
+        rolled_back:        :ready_for_review,
+        shit:               :planned
+      }.freeze
+
+      # Preference order when several states fit a folder's contents at once.
+      # Read top to bottom: the loudest fact wins. A discard outranks everything,
+      # a block outranks progress, and `retroactive` is last because it is the
+      # absence of documents rather than the presence of any.
+      PREFERENCE = %i[
+        discarded rolled_back shit deferred blocked product_blocked
+        deployed approved rejected in_review ready_for_review building_ui building planned ready_for_planning
+        researched new
+        retroactive
+      ].freeze
+
+      # States whose members a folder's *contents* cannot tell apart. Within a
+      # family the current name always wins, because re-deriving it would be a
+      # guess dressed up as a correction.
+      #
+      # ⭕️ and 🅱️ both mean "a human must decide before this moves"; *which*
+      # human is recorded nowhere but the emoji.
+      #
+      # ⭐️ 🟡 🎨 look identical on disk: a `spec.md` and a `plan.md` with work
+      # units in it. Whether nobody has started, the back end is under way, or
+      # the interface is, is recorded only by the agent that renamed the folder
+      # when it started. 🟢 👀 🔴 add an open pull request and are just as
+      # mute about whether a reviewer has seen it. So `resync` never moves
+      # between any of them; they advance by events alone.
+      #
+      # Order matters: the members run weakest claim first, and a folder
+      # arriving from outside lands on the weakest member its contents fit.
+      # Contents that fit the family justify only its floor, never its ceiling.
+      FAMILIES = [
+        %i[blocked product_blocked],
+        %i[planned building building_ui ready_for_review in_review rejected]
+      ].freeze
+
+      # States the agent loop leaves alone: work that is finished (✅ 😎), work
+      # that was dropped (❌), and work waiting on a human (⭕️ 🅱️ ☢️).
+      # Everything else is fair game for a specialist.
+      #
+      # ✅ Approved is here deliberately. `hansolo-reviewer` advancing a plan to
+      # it is the end of the loop, not a step in it: nothing merges, and no agent
+      # handles `approved`. Merging is the one act in this lifecycle that changes
+      # a branch everyone else builds on, and an autonomous loop that does it
+      # unattended has no way to be wrong quietly.
+      #
+      # Moving `approved` out of this list is therefore a decision about blast
+      # radius rather than about topology. If it ever moves, something has to own
+      # `approved -> deployed`, and today nothing does.
+      SETTLED = %i[approved deployed discarded blocked product_blocked deferred].freeze
+
+      # Every state an agent that may sign `Blocked` works in. A block the
+      # machine refuses is reported as a failed attempt and parks nothing, so a
+      # state missing here turns an honest "I need a decision" into a failure.
+      # The agents spec checks every prompt that describes blocking against it.
+      #
+      # Review is absent: a reviewer rules, it does not ask.
+      BLOCKABLE = %i[new researched retroactive ready_for_planning planned building building_ui rejected].freeze
+
+      # Rerouting a transition below makes the hand-drawn
+      # `docs/img/plan-spec-build.png` stale — `just docs` will show you, because
+      # the mermaid source in the generated document is derived from this block.
+      aasm do
+        # The vocabulary is defined once, in {STATUSES}. This machine may not
+        # quietly know a different set.
+        Agentilda::Plans::STATUSES.each { |status| state status.key }
+
+        event :specify, guard: :justified? do
+          transitions from: %i[retroactive blocked product_blocked deferred], to: :new
+        end
+
+        event :research, guard: :justified? do
+          transitions from: %i[new retroactive blocked product_blocked deferred], to: :researched
+        end
+
+        # The specification is done and the planner has not started. Entered
+        # by the harness when `yoda-writer` completes; `resync` reaches it on
+        # a blank `plan.md`. Without it ⭐️ Planned required a file only the
+        # agent handling ⭐️ Planned writes, and nothing could enter it.
+        event :ready_to_plan, guard: :justified? do
+          transitions from: %i[researched new retroactive shit blocked product_blocked deferred],
+            to: :ready_for_planning
+        end
+
+        # `new` stays in this list. The spine routes a plan through research, and
+        # that is what the agent loop follows — but a specification somebody has
+        # already researched by hand should not have to pretend otherwise to get
+        # planned. What research buys is not enforced here; it is enforced by
+        # `yoda-writer` handling `researched` and nothing else.
+        event :plan, guard: :justified? do
+          transitions from: %i[ready_for_planning researched new retroactive shit blocked product_blocked deferred],
+            to: :planned
+        end
+
+        event :build, guard: :justified? do
+          transitions from: %i[planned shit approved rolled_back retroactive blocked product_blocked deferred],
+            to: :building
+        end
+
+        # Building hands off rather than finishing. A plan with no interface work
+        # still passes through Building UI: `rey-frontend` says there is nothing
+        # to build and moves it on, which costs one cheap round and keeps the
+        # spine one shape instead of two. `rejected` re-enters here rather than
+        # going straight back to review, because a change request reopens the
+        # implementation and neither half can assume the other still holds.
+        event :build_ui, guard: :justified? do
+          transitions from: %i[building rejected], to: :building_ui
+        end
+
+        # The pair lands one pull request, and whichever half finishes last
+        # carries the plan to review from wherever the folder stands.
+        event :submit, guard: :justified? do
+          transitions from: %i[building building_ui rejected rolled_back], to: :ready_for_review
+        end
+
+        event :review, guard: :justified? do
+          transitions from: %i[ready_for_review], to: :in_review
+        end
+
+        event :approve, guard: :justified? do
+          transitions from: %i[in_review retroactive], to: :approved
+        end
+
+        event :request_changes, guard: :justified? do
+          transitions from: %i[in_review], to: :rejected
+        end
+
+        event :slop, guard: :justified? do
+          transitions from: %i[in_review], to: :shit
+        end
+
+        event :deploy, guard: :justified? do
+          transitions from: %i[approved], to: :deployed
+        end
+
+        # 🚀 is not the end of the line. A release that breaks in production comes
+        # back through ⏪, which needs its own proof on disk: by the time work is
+        # deployed every pull request is merged, so 🟢's "at least one open pull
+        # request" guard would refuse a direct return, permanently.
+        event :rollback, guard: :justified? do
+          transitions from: %i[deployed], to: :rolled_back
+        end
+
+        event :block, guard: :justified? do
+          transitions from: BLOCKABLE, to: :blocked
+        end
+
+        event :block_on_product, guard: :justified? do
+          transitions from: BLOCKABLE, to: :product_blocked
+        end
+
+        event :defer, guard: :justified? do
+          transitions from: BLOCKABLE + %i[blocked product_blocked], to: :deferred
+        end
+
+        # Anything, from anywhere, may be dropped for good.
+        event :discard, guard: :justified? do
+          transitions from: Agentilda::Plans::STATUSES.map(&:key) - %i[discarded], to: :discarded
+        end
+
+        # A transition is not a bookkeeping entry: it is the folder moving.
+        after_all_transitions :rename!
+      end
+
+      class << self
+        # Destination => the event that reaches it. Every event above has exactly
+        # one `to:`, which is what lets `--to <state>` name a destination rather
+        # than making callers learn the verbs.
+        #
+        # @return [Hash{Symbol => Symbol}]
+        def event_for
+          @event_for ||= aasm.events.each_with_object({}) { |event, map|
+            event.transitions.each { |t| map[t.to] ||= event.name }
+          }.freeze
+        end
+
+        # Destination => the states that may legitimately reach it.
+        #
+        # `retroactive` is absent: it is a birth state, produced by
+        # `create --after` for work that shipped undocumented.
+        #
+        # @return [Hash{Symbol => Array<Symbol>}]
+        def inbound
+          @inbound ||= aasm.events.each_with_object({}) { |event, map|
+            event.transitions.each { |t| (map[t.to] ||= []).concat(Array(t.from)) }
+          }.transform_values { |froms| froms.uniq.freeze }.freeze
+        end
+
+        # Source => the states it may reach.
+        #
+        # @return [Hash{Symbol => Array<Symbol>}]
+        def outbound_map
+          @outbound_map ||= inbound.each_with_object({}) { |(to, froms), map|
+            froms.each { |from| (map[from] ||= []) << to }
+          }.transform_values(&:freeze).freeze
+        end
+
+        # @param key [Symbol]
+        # @return [Array<Symbol>]
+        def outbound(key) = outbound_map.fetch(key, [])
+
+        # @param from [Symbol]
+        # @param to [Symbol]
+        # @return [Boolean] whether the topology permits this edge at all
+        def edge?(from, to) = outbound(from).include?(to)
+
+        # @param key [Symbol]
+        # @return [Array<Symbol>] the family +key+ belongs to, empty when it has none
+        def family_of(key) = FAMILIES.find { |family| family.include?(key) } || []
+      end
+
+      # @param subject [#status, #file?, #read, #pull_requests, #rename_to]
+      def initialize(subject)
+        @subject = subject
+        @key = subject.status.key
+      end
+
+      # @return [Object] the plan folder this machine speaks for
+      attr_reader :subject
+
+      # @return [Symbol] the state right now
+      attr_reader :key
+
+      # @return [Agentilda::Plans::Status]
+      def status = STATUS_BY_KEY.fetch(key)
+
+      # AASM keeps state in an ORM column; we keep it in a directory name. These
+      # three methods are the whole of that adaptation.
+      #
+      # @return [Symbol]
+      def aasm_read_state(_name = :default) = @key
+
+      # @return [Boolean]
+      def aasm_write_state(new_state, name = :default) = aasm_write_state_without_persistence(new_state, name)
+
+      # @return [Boolean]
+      def aasm_write_state_without_persistence(new_state, _name = :default)
+        @key = new_state
+        true
+      end
+
+      # States reachable right now, guards applied.
+      #
+      # @return [Array<Symbol>]
+      def allowed = aasm.states(permitted: true).map(&:name)
+
+      # @param to [Symbol]
+      # @return [Boolean] whether that move is permitted right now
+      def may?(to) = allowed.include?(to)
+
+      # The next state along the spine, whether or not its guard passes.
+      #
+      # @return [Symbol, nil]
+      def spine_next = SPINE[key]
+
+      # Move the folder. With no argument it walks one step along the {SPINE}.
+      #
+      # A refusal is information — it means the phase has not actually happened
+      # yet — so it arrives as {Refused} carrying the reason, never as `false`.
+      #
+      # @param to [Symbol] destination, defaulting to the next spine state
+      # @return [Agentilda::Plans::Status] the state now occupied
+      # @raise [Agentilda::Plans::StateMachine::Refused]
+      def promote!(to = spine_next)
+        raise Refused, "#{describe(key)} is terminal — nothing follows it" if to.nil?
+        raise Refused, "nothing can reach #{describe(to)}" unless self.class.event_for.key?(to)
+        raise Refused, refusal(to) unless may?(to)
+
+        aasm.fire!(self.class.event_for.fetch(to))
+        status
+      end
+
+      # The state a folder's contents justify — the answer to "well, what should
+      # it be, then?". This is what `resync dirs` renames toward.
+      #
+      # Invariants are *minimum* requirements, not exact matches: a ⚪️ folder
+      # that has since grown a `plan.md` still satisfies ⚪️, and is nonetheless
+      # ⭐️ now. So the furthest-justified state wins, and the caller compares it
+      # against the current one to decide whether anything should move.
+      #
+      # The exception is a {FAMILIES family}, whose members contents cannot tell
+      # apart. Two rules cover it:
+      #
+      # - **Already inside one** — the current name wins. Re-deriving it would be
+      #   a guess dressed up as a correction, and every ⭕️ would become 🅱️.
+      # - **Arriving from outside** — the *weakest* member the contents fit
+      #   wins, not the furthest. A 📋 folder whose `plan.md` grew work units
+      #   lands on ⭐️, not 🟡, because nobody has started. A ✅ folder found
+      #   with an open pull request is demonstrably back in the PR phase, and
+      #   ⭐️ refuses an open pull request, so it lands on 🟡 rather than
+      #   claiming 🔴.
+      #
+      # @return [Agentilda::Plans::Status, nil] nil when nothing fits at all
+      def best_fit
+        fitting = STATUSES.select { |s| s.satisfied_by?(subject) }
+        return nil if fitting.empty?
+
+        best = PREFERENCE.filter_map { |k| fitting.find { |s| s.key == k } }.first || fitting.first
+        return status if self.class.family_of(key).include?(best.key)
+
+        family = self.class.family_of(best.key)
+        return best if family.empty?
+
+        floor = family.find { |k| fitting.any? { |s| s.key == k } }
+        STATUS_BY_KEY.fetch(floor)
+      end
+
+      private
+
+      # The one guard. Entering a state is permitted exactly when that state's
+      # invariant holds for this folder's contents.
+      #
+      # @return [Boolean]
+      def justified? = STATUS_BY_KEY.fetch(aasm.to_state).satisfied_by?(subject)
+
+      # @param to [Symbol]
+      # @return [String]
+      def refusal(to)
+        return "#{describe(key)} cannot become #{describe(to)}" unless self.class.edge?(key, to)
+
+        STATUS_BY_KEY.fetch(to).violation(subject)
+      end
+
+      # @param key [Symbol]
+      # @return [String]
+      def describe(key) = STATUS_BY_KEY.fetch(key).to_s
+
+      # The folder moves. {Subject} owns the path, so it owns the move.
+      #
+      # @return [void]
+      def rename! = subject.rename_to(STATUS_BY_KEY.fetch(aasm.to_state))
+    end
+  end
+end