openlanes 3.0.0

data/lib/openlanes/plans/spec.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # What the author of `spec.md` asked of the harness, in its frontmatter:
+    #
+    #   ---
+    #   lane: quick              # full (default) | plan | quick
+    #   frontend: false          # true forces rey-frontend, false forbids it
+    #   depth: fast              # fast | medium | deep
+    #   phases:
+    #     build:  { adapter: codex, model: gpt-5-codex, effort: medium }
+    #     review: { model: opus }
+    #   implementation_suggestions:
+    #     - Ruby, with dry-cli for the command line
+    #     - Reuse the gems already in the Gemfile before adding new ones
+    #   implementation_requirements:
+    #     - The database is PG-strict
+    #   task-completed-when:
+    #     - `openlanes create` opens an editor and writes no draft
+    #   how-to-verify:
+    #     - bundle exec rspec spec/openlanes/cli/create_spec.rb
+    #   ---
+    #
+    # The body is the specification; this is how it should be worked. A value
+    # this does not recognise is ignored and named in {#problems}, rather than
+    # stopping the run: a typo in `lane:` should cost the author their lane,
+    # not their plan.
+    #
+    # @!attribute [r] lane
+    #   @return [Symbol] :full, :plan or :quick
+    # @!attribute [r] frontend
+    #   @return [Boolean, nil] nil when the plan decides
+    # @!attribute [r] depth
+    #   @return [Symbol, nil] :fast, :medium or :deep
+    # @!attribute [r] phases
+    #   @return [Hash{String => Hash{String => String}}] per-phase
+    #     `adapter`, `model` and `effort`
+    # @!attribute [r] suggestions
+    #   @return [Array<String>] the author's `implementation_suggestions`:
+    #     language, libraries, an approach. Offered to the agents, never
+    #     imposed on them.
+    # @!attribute [r] requirements
+    #   @return [Array<String>] the author's `implementation_requirements`:
+    #     constraints the work must meet exactly as written.
+    # @!attribute [r] completed_when
+    #   @return [Array<String>] the author's `task-completed-when`: what
+    #     must be true for the task to count as finished.
+    # @!attribute [r] how_to_verify
+    #   @return [Array<String>] the author's `how-to-verify`: the commands or
+    #     checks that show it is.
+    # @!attribute [r] problems
+    #   @return [Array<String>] what was ignored, and why
+    Spec = Data.define(:lane,
+      :frontend,
+      :depth,
+      :phases,
+      :suggestions,
+      :requirements,
+      :completed_when,
+      :how_to_verify,
+      :problems) do
+      def initialize(lane: :full, frontend: nil, depth: nil, phases: {}, suggestions: [], requirements: [],
+        completed_when: [], how_to_verify: [], problems: [])
+        super
+      end
+
+      # @param phase [String, Symbol, nil]
+      # @return [Hash{String => String}] what the author set for that phase
+      def override_for(phase) = phases.fetch(phase.to_s, {})
+
+      # @return [Boolean]
+      def default? = self == Spec.new
+    end
+
+    class Spec
+      # Every route a plan can take through the agents.
+      #   full  — research, specification, planning, build, review
+      #   plan  — the spec is already what the author wants: plan, build, review
+      #   quick — a short mechanical task: one agent builds it, then review
+      LANES = %i[full plan quick].freeze
+
+      # How much each phase should think, and what an eval holds it to.
+      DEPTHS = %i[fast medium deep].freeze
+
+      # What a depth means as an effort, when nothing more specific is set.
+      EFFORT_FOR_DEPTH = { fast: "low", medium: "medium", deep: "high" }.freeze
+
+      # The keys a `phases:` entry may set.
+      PHASE_KEYS = %w[adapter model effort].freeze
+
+      # The frontmatter key for what the author would build it with. Optional,
+      # and a suggestion: an agent that finds a better route takes it and says
+      # why, so nothing here is validated against what is installed.
+      SUGGESTIONS_KEY = "implementation_suggestions"
+
+      # The other side of {SUGGESTIONS_KEY}: constraints the agents must meet
+      # exactly as written (`The database is PG-strict`). They are not weighed
+      # against anything, so an agent that cannot meet one signs Blocked
+      # instead of substituting its own.
+      REQUIREMENTS_KEY = "implementation_requirements"
+
+      # How the author says the task is finished, and how to tell. Hyphenated
+      # because that is how the author named them; they are copied into
+      # `plan.md` by {OpenLanes::Lifecycle::Completion}.
+      COMPLETED_WHEN_KEY = "task-completed-when"
+      HOW_TO_VERIFY_KEY = "how-to-verify"
+
+      FILENAME = "spec.md"
+
+      class << self
+        # @param subject [#read]
+        # @return [OpenLanes::Plans::Spec]
+        def for(subject) = parse(subject.read(FILENAME).to_s)
+
+        # @param dir [String] a plan folder
+        # @return [OpenLanes::Plans::Spec]
+        def load(dir)
+          path = File.join(dir, FILENAME)
+          File.file?(path) ? parse(File.read(path, encoding: "UTF-8")) : new
+        end
+
+        # @param text [String] a whole spec.md
+        # @return [OpenLanes::Plans::Spec]
+        def parse(text)
+          meta, = Frontmatter.split(text)
+          from(meta)
+        rescue Psych::Exception => e
+          new(problems: ["spec.md frontmatter is not valid YAML (#{e.message.lines.first.strip})"])
+        end
+
+        # @param meta [Hash]
+        # @return [OpenLanes::Plans::Spec]
+        def from(meta)
+          problems = []
+          new(lane:     choice(meta, "lane", LANES, :full, problems),
+            frontend: switch(meta, "frontend", problems),
+            depth:    choice(meta, "depth", DEPTHS, nil, problems),
+            phases:   phases(meta["phases"], problems),
+            suggestions: notes(meta, SUGGESTIONS_KEY, problems),
+            requirements: notes(meta, REQUIREMENTS_KEY, problems),
+            completed_when: notes(meta, COMPLETED_WHEN_KEY, problems),
+            how_to_verify: notes(meta, HOW_TO_VERIFY_KEY, problems),
+            problems:)
+        end
+
+        private
+
+        # @return [Symbol, nil]
+        def choice(meta, key, allowed, default, problems)
+          return default unless meta.key?(key)
+
+          value = meta[key].to_s.strip.downcase.to_sym
+          return value if allowed.include?(value)
+
+          problems << "#{key}: #{meta[key].inspect} is not one of #{allowed.join(", ")}"
+          default
+        end
+
+        # @return [Boolean, nil]
+        def switch(meta, key, problems)
+          return nil unless meta.key?(key)
+          return meta[key] if [true, false].include?(meta[key])
+
+          problems << "#{key}: #{meta[key].inspect} is not true or false"
+          nil
+        end
+
+        # A bare string is one item; a list is several.
+        #
+        # @param key [String] one of the keys above that holds free text
+        # @return [Array<String>]
+        def notes(meta, key, problems)
+          return [] if meta[key].nil?
+
+          items = meta[key].is_a?(Array) ? meta[key] : [meta[key]]
+          unless items.all? { |item| item.is_a?(String) || item.is_a?(Numeric) }
+            problems << "#{key}: must be text or a list of text"
+            return []
+          end
+
+          items.map { |item| item.to_s.strip }.reject(&:empty?)
+        end
+
+        # @return [Hash]
+        def phases(value, problems)
+          return {} if value.nil?
+
+          unless value.is_a?(Hash)
+            problems << "phases: must be a mapping of phase to adapter, model and effort"
+            return {}
+          end
+
+          value.each_with_object({}) do |(phase, settings), out|
+            next problems << "phases.#{phase}: must be a mapping" unless settings.is_a?(Hash)
+
+            kept = settings.transform_keys(&:to_s).slice(*PHASE_KEYS).transform_values(&:to_s)
+            (settings.keys.map(&:to_s) - PHASE_KEYS).each { |k| problems << "phases.#{phase}.#{k}: unknown key" }
+            if kept.key?("effort") && !Adapters.effort?(kept["effort"])
+              problems << "phases.#{phase}.effort: #{kept["effort"].inspect} is not one of #{Adapters::EFFORTS.join(", ")}"
+              kept.delete("effort")
+            end
+            if kept.key?("adapter") && !Adapters.known?(kept["adapter"])
+              problems << "phases.#{phase}.adapter: #{kept["adapter"].inspect} is not one of #{Adapters.names.join(", ")}"
+              kept.delete("adapter")
+            end
+            out[phase.to_s] = kept
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/plans/state_machine.rb

@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+require "aasm"
+
+module OpenLanes
+  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
+
+      # One step back along the spine, for the one move that goes backwards: a
+      # person discarding an interrupted round (W9) sends the plan back to the
+      # state the work started from. Derived from {SPINE}, walking it from ⚪️:
+      # each state on that path steps back to the one before it, as far as 👀,
+      # the last state an agent works in. States off the path (🔴 💩 ⏪ and
+      # the birth state) have no single state behind them and step back
+      # nowhere.
+      RETREAT = Enumerator.produce(:new) { SPINE.fetch(it) { raise StopIteration } }
+                          .take_while { it != :approved }
+                          .each_cons(2).to_h { |before, after| [after, before] }
+                          .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.
+        OpenLanes::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: OpenLanes::Plans::STATUSES.map(&:key) - %i[discarded], to: :discarded
+        end
+
+        # Back one step, fired only by {#retreat!}. It is the one event with
+        # several destinations, and it is left out of {inbound}, {outbound}
+        # and {event_for}: those describe how work moves on, which is what
+        # the documentation, the diagram and {#may?} are about, and a person
+        # sending work back is not a way for it to move on.
+        event :step_back, guard: :justified? do
+          RETREAT.each { |from, to| transitions from:, to: }
+        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 ||= forward_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 ||= forward_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)
+
+        # Every event but {RETREAT}'s.
+        #
+        # @return [Array<AASM::Core::Event>]
+        def forward_events = aasm.events.reject { it.name == :step_back }
+
+        # @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 [OpenLanes::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. A step back is not among
+      # them: only {#retreat!} takes it.
+      #
+      # @return [Array<Symbol>]
+      def allowed = aasm.states(permitted: true).map(&:name) & self.class.outbound(key)
+
+      # @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 [OpenLanes::Plans::Status] the state now occupied
+      # @raise [OpenLanes::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
+
+      # @return [Symbol, nil] the state one step back, nil when there is none
+      def previous = RETREAT[key]
+
+      # Move the folder one step back along the spine (W9).
+      #
+      # @return [OpenLanes::Plans::Status] the state now occupied
+      # @raise [OpenLanes::Plans::StateMachine::Refused] when nothing is
+      #   behind this state, or the folder's contents do not justify it
+      def retreat!
+        refusal = retreat_refusal and raise Refused, refusal
+
+        aasm.fire!(:step_back)
+        status
+      end
+
+      # @return [String, nil] why {#retreat!} would be refused, nil when it would not
+      def retreat_refusal
+        to = previous or return "#{describe(key)} has no state behind it to go back to"
+        return nil if aasm.may_fire_event?(:step_back)
+
+        STATUS_BY_KEY.fetch(to).violation(subject) || "#{describe(key)} cannot go back to #{describe(to)}"
+      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 [OpenLanes::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