agentilda 1.0.3

data/lib/agentilda/state_machine.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "aasm"
+
+module Agentilda
+  # 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: :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 planned
+      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.
+    #
+    # 🟡 🟢 👀 🔴 all look identical on disk — a `plan.md` and some open pull
+    # requests. Whether someone is still building, CI is green and a reviewer
+    # is wanted, a reviewer is reading it, or a reviewer asked for changes is
+    # not written down anywhere a program could read. So `resync` never moves
+    # between them; they advance by events alone.
+    #
+    # Order matters: the first member is the *weakest claim* in the family, and
+    # it is where a folder arriving from outside lands. Contents that fit the
+    # family justify only its floor, never its ceiling.
+    FAMILIES = [
+      %i[blocked product_blocked],
+      %i[building 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
+
+    # 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::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
+
+      # `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[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
+
+      event :submit, guard: :justified? do
+        transitions from: %i[building_ui 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: %i[new planned building], to: :blocked
+      end
+
+      event :block_on_product, guard: :justified? do
+        transitions from: %i[new planned building], to: :product_blocked
+      end
+
+      event :defer, guard: :justified? do
+        transitions from: %i[new planned building blocked product_blocked], to: :deferred
+      end
+
+      # Anything, from anywhere, may be dropped for good.
+      event :discard, guard: :justified? do
+        transitions from: Agentilda::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::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::Status] the state now occupied
+    # @raise [Agentilda::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 family's *first* member wins, not the
+    #   furthest. A ✅ folder found with an open pull request is demonstrably
+    #   back in the PR phase; nothing shows whether a reviewer has seen it, so
+    #   it lands on 🟡 rather than claiming 🔴.
+    #
+    # @return [Agentilda::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)
+      family.empty? ? best : STATUS_BY_KEY.fetch(family.first)
+    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

data/lib/agentilda/status.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # A folder's state: what it means, which files it cannot be honest without,
+  # and the rule that decides whether the folder may legitimately claim it.
+  #
+  # `invariant` is asked in both directions. {StateMachine} asks it of a
+  # destination before moving there; `resync` and `check` ask it of the current
+  # state, to catch folders whose name has drifted from their contents. One
+  # definition, so the two can never disagree about what a state means.
+  #
+  # @!attribute [r] key
+  #   @return [Symbol] machine-facing name, e.g. `:product_blocked`
+  # @!attribute [r] emoji
+  #   @return [String] as it appears in the folder name
+  # @!attribute [r] label
+  #   @return [String] the human words
+  # @!attribute [r] requires
+  #   @return [Array<String>] files this state cannot be honest without
+  # @!attribute [r] note
+  #   @return [String] one-line meaning, for tables and generated docs
+  # @!attribute [r] invariant
+  #   @return [Proc, nil] `(subject) -> String | nil` — the reason it does not hold
+  Status = Data.define(:key, :emoji, :label, :requires, :note, :invariant) do
+    # @param subject [#file?, #read, #pull_requests]
+    # @return [Boolean]
+    def satisfied_by?(subject) = violation(subject).nil?
+
+    # @param subject [#file?, #read, #pull_requests]
+    # @return [String, nil] why this state is not justified, nil when it is
+    def violation(subject)
+      missing = requires.reject { |f| subject.file?(f) }
+      return "#{label} requires #{missing.map { |f| "`#{f}`" }.join(" and ")}" unless missing.empty?
+
+      invariant&.call(subject)
+    end
+
+    # @return [Boolean] whether nothing may follow this state
+    def terminal? = StateMachine.outbound(key).empty?
+
+    # @return [String] emoji and words, as the tables print it
+    def to_s = "#{emoji} #{label}"
+  end
+
+  # "1 pull request", "3 pull requests".
+  #
+  # @param count [Integer]
+  # @return [String]
+  def self.pull_request_count(count) = "#{count} pull request#{"s" unless count == 1}"
+
+  # What proves a specification has been researched rather than merely
+  # written: the chapter `leah-researcher` contributes. It is a section of
+  # `spec.md` rather than a file of its own because research is not a separate
+  # document — it is the first half of the specification, and splitting it
+  # would leave `yoda-writer` reading two files to write one.
+  RESEARCH_CHAPTER = /^[ \t]{0,3}\#{2,3}[ \t]+Research\b/i
+
+  # Variation selectors make ⚪️ and ⚪ different strings that mean the same
+  # thing to a human. Compare with them removed.
+  #
+  # @param str [String, nil]
+  # @return [String]
+  def self.fold_emoji(str) = str.to_s.gsub(/[\u{FE0E}\u{FE0F}\u{200D}]/, "")
+
+  # 🟢 Ready for Review, 👀 In Review and 🔴 Changes Requested are the same
+  # thing on disk — the work exists and at least one pull request is still
+  # open. Which of the three it is lives in the folder name and nowhere else,
+  # so they share one invariant rather than three that could drift apart.
+  #
+  # @param label [String]
+  # @return [Proc]
+  def self.open_pull_request(label)
+    lambda { |subject|
+      return "#{label} requires an open pull request; none are recorded" if subject.pull_requests.empty?
+
+      "#{label}, but every pull request is already merged" if subject.pull_requests.none?(&:open?)
+    }
+  end
+
+  # A question that is still somebody's to answer, written as its own heading:
+  # `## B1`, `## B2`. The number is what `blocked.md` gets referenced by in
+  # conversation and in pull requests, so it is also the only part of the file
+  # a program can count.
+  #
+  # Whoever writes `blocked.md` MUST use this notation. A question written any
+  # other way is invisible to every part of this tool: the folder never becomes
+  # ⭕️, and `unblock` reports a file with nothing in it to drain. {ANSWER_BLOCK}
+  # is the other half of the pair.
+  OPEN_BLOCK = /^[ \t]{0,3}\#{0,4}[ \t]*\**B(\d+)\b/
+
+  # The answer to the question of the same number: `## A1` settles `## B1`.
+  #
+  # Answers are an inbox, not a record. `lando-broker` folds each one into the
+  # document its question was stopping and deletes both, so a `blocked.md`
+  # holding nothing but history must not go on stopping the folder. An `A`
+  # never matches {OPEN_BLOCK}, which is what lets the two live in one file.
+  ANSWER_BLOCK = /^[ \t]{0,3}\#{0,4}[ \t]*\**A(\d+)\b/
+
+  # The numbers named by every heading in +text+ matching +pattern+.
+  #
+  # @param text [String, nil]
+  # @param pattern [Regexp] {OPEN_BLOCK} or {ANSWER_BLOCK}
+  # @return [Array<Integer>] in the order they appear, without duplicates
+  def self.block_numbers(text, pattern)
+    text.to_s.lines.filter_map { |line| line[pattern, 1]&.to_i }.uniq
+  end
+
+  # ⭕️ Technical Block and 🅱️ Product Block are the same thing on disk: a
+  # `blocked.md` still naming at least one question nobody has answered. Which
+  # human is owed the answer lives in the folder name and nowhere else, so the
+  # two share one invariant rather than two that could drift apart.
+  #
+  # This is what lets a block drain in pieces. Answers land in `blocked.md`
+  # one at a time, `lando-broker` moves each into `spec.md` or `plan.md` and
+  # deletes it here, and the folder leaves ⭕️ on the pass that empties the
+  # file, by content rather than by anyone remembering to delete it.
+  #
+  # @param label [String]
+  # @return [Proc]
+  def self.open_block(label)
+    lambda { |subject|
+      "#{label}, but `blocked.md` names no open question" unless subject.read("blocked.md").to_s.match?(OPEN_BLOCK)
+    }
+  end
+
+  # Every state a plan folder may be in, in lifecycle order. That order drives
+  # the legend, the generated documentation and the `--to` help text.
+  #
+  # 🟣 Merged is deliberately absent: it is a pull request's status, not a
+  # folder's, and giving it a folder state invites folders that claim a pull
+  # request's condition as their own.
+  #
+  # Adding a state here, or changing an emoji, makes the hand-drawn
+  # `docs/img/plan-spec-build.png` stale — `just docs` will show you, because
+  # the mermaid source in the generated document moves with this list.
+  STATUSES = [
+    Status.new(
+      key: :new, emoji: "⚪️", label: "New", requires: %w[spec.md],
+      note: "a specification exists; it has not been planned yet",
+      invariant: nil
+    ),
+    Status.new(
+      key: :researched, emoji: "🔎", label: "Researched", requires: %w[spec.md],
+      note: "the topic has been researched; `spec.md` carries a `## Research` chapter",
+      invariant: lambda { |s|
+        body = s.read("spec.md").to_s
+        "Researched, but `spec.md` has no `## Research` chapter" unless body.match?(RESEARCH_CHAPTER)
+      }
+    ),
+    Status.new(
+      key: :planned, emoji: "⭐️", label: "Planned", requires: %w[spec.md plan.md],
+      note: "specified and planned; nobody has started building",
+      invariant: nil
+    ),
+    # `pull-requests.md` is deliberately absent from `requires` on both of the
+    # building states, though it names the file they are about. That file is
+    # written by opening a pull request, which happens once, when the last
+    # implementer advances the plan to Ready for Review. Requiring the file to
+    # *enter* Building would mean nothing could ever justify entering it, and
+    # `palpatine-planner` finishing `plan.md` would loop forever between itself
+    # and a state it can never actually reach. Ready for Review is where the
+    # file becomes a real requirement, once something has had the chance to
+    # write it.
+    Status.new(
+      key: :building, emoji: "🟡", label: "Building", requires: %w[spec.md plan.md],
+      note: "the back end is under way: data, domain and the API the interface will call",
+      invariant: nil
+    ),
+    # Two building states rather than one, because the order is not a
+    # preference: an interface is written against an API that already answers.
+    # Splitting them lets each half be built by someone who only has to be good
+    # at that half, and gives the second a working system to build on rather
+    # than a description of one.
+    Status.new(
+      key: :building_ui, emoji: "🎨", label: "Building UI", requires: %w[spec.md plan.md],
+      note: "the back end holds; the interface is being built against it",
+      invariant: nil
+    ),
+    Status.new(
+      key: :ready_for_review, emoji: "🟢", label: "Ready for Review", requires: %w[spec.md plan.md pull-requests.md],
+      note: "every pull request is green on CI and waiting for a reviewer",
+      invariant: open_pull_request("Ready for Review")
+    ),
+    Status.new(
+      key: :in_review, emoji: "👀", label: "In Review", requires: %w[spec.md plan.md pull-requests.md],
+      note: "a reviewer has picked it up and has not ruled yet",
+      invariant: open_pull_request("In Review")
+    ),
+    Status.new(
+      key: :rejected, emoji: "🔴", label: "Changes Requested", requires: %w[spec.md plan.md pull-requests.md],
+      note: "the review asked for fixes; resubmit once they are made",
+      invariant: open_pull_request("Changes Requested")
+    ),
+    Status.new(
+      key: :approved, emoji: "✅", label: "Approved & Merged", requires: %w[pull-requests.md],
+      note: "reviewed, approved, and every pull request merged",
+      invariant: lambda { |s|
+        return "Approved & Merged, but no pull requests are recorded" if s.pull_requests.empty?
+
+        open = s.pull_requests.count(&:open?)
+        "Approved & Merged, but #{Agentilda.pull_request_count(open)} still open" if open.positive?
+      }
+    ),
+    Status.new(
+      key: :deployed, emoji: "😎", label: "Deployed", requires: %w[deployed.md],
+      note: "live in production; `deployed.md` names the release, date and SHA",
+      invariant: nil
+    ),
+    Status.new(
+      key: :rolled_back, emoji: "😱", label: "Rolled Back", requires: %w[rollback.md],
+      note: "it shipped and was pulled; `rollback.md` names what broke",
+      invariant: nil
+    ),
+    Status.new(
+      key: :shit, emoji: "💩", label: "Scrapped by Review", requires: %w[rewrite.md],
+      note: "the review scrapped the work; the plan survives, the pull requests do not",
+      invariant: nil
+    ),
+    Status.new(
+      key: :blocked, emoji: "⭕️", label: "Technical Block", requires: %w[blocked.md],
+      note: "cannot proceed; `blocked.md` names what an engineer or the CTO must decide",
+      invariant: open_block("Technical Block")
+    ),
+    Status.new(
+      key: :product_blocked, emoji: "🅱️", label: "Product Block", requires: %w[blocked.md],
+      note: "cannot proceed; `blocked.md` names what a product manager must decide",
+      invariant: open_block("Product Block")
+    ),
+    Status.new(
+      key: :deferred, emoji: "☢️", label: "Deferred", requires: %w[delayed.md],
+      note: "could proceed and chose not to yet; `delayed.md` must name the trigger",
+      invariant: lambda { |s|
+        body = s.read("delayed.md").to_s
+        "Deferred, but `delayed.md` names no trigger" unless body.match?(/trigger|revisit|when\b|until\b|once\b/i)
+      }
+    ),
+    Status.new(
+      key: :retroactive, emoji: "🕰️", label: "Retroactive", requires: [],
+      note: "the feature is live, but has neither a specification nor a plan",
+      invariant: lambda { |s|
+        next "Retroactive, but a `spec.md` already exists — it has been documented" if s.file?("spec.md")
+
+        "Retroactive, but no pull requests are recorded" if s.pull_requests.empty?
+      }
+    ),
+    Status.new(
+      key: :discarded, emoji: "❌", label: "Discarded", requires: %w[discarded.md],
+      note: "dropped for good; `discarded.md` says why. A terminal state",
+      invariant: nil
+    )
+  ].freeze
+
+  # Emoji => status, folded so ⚪ and ⚪️ both resolve.
+  STATUS_BY_EMOJI = STATUSES.each_with_object({}) { |s, h| h[fold_emoji(s.emoji)] ||= s }.freeze
+
+  # Symbol => status.
+  STATUS_BY_KEY = STATUSES.to_h { |s| [s.key, s] }.freeze
+
+  # @param emoji [String, nil]
+  # @return [Agentilda::Status, nil]
+  def self.status_for_emoji(emoji) = STATUS_BY_EMOJI[fold_emoji(emoji)]
+
+  # Resolve a state from the only two names it has: its key, and its emoji.
+  #
+  # There is deliberately no synonym table. A state that also answers to
+  # "star", "green" and "completed" has four names to keep in step with the
+  # folder, the generated docs and the agent frontmatter — and the synonym
+  # table that used to live here went stale pointing six words at a state that
+  # no longer existed.
+  #
+  # @param text [String, Symbol, Agentilda::Status, nil]
+  # @return [Agentilda::Status, nil]
+  def self.status(text)
+    return nil if text.nil?
+    return text if text.is_a?(Status)
+
+    key = text.to_s.strip
+    STATUS_BY_KEY[key.to_sym] || status_for_emoji(key)
+  end
+end