openlanes 3.0.0

data/lib/openlanes/live/stations.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Live
+    # The stops on the page's board: the {Plans::StateMachine::SPINE}, with
+    # the states a person does not need told apart folded into one stop.
+    #
+    # The grouping and the labels are the page's vocabulary and are written
+    # here; which agents work at each stop is not, and comes from each
+    # agent's `handles:`. A spec walks the spine to prove every state on it
+    # has a stop, in spine order.
+    module Stations
+      # One stop.
+      #
+      # @!attribute [r] key
+      #   @return [Symbol] a spine state's key, or :pr
+      # @!attribute [r] label
+      #   @return [String]
+      # @!attribute [r] states
+      #   @return [Array<Symbol>] the states a plan at this stop may be in
+      # @!attribute [r] agents
+      #   @return [Array<String>] agents whose `handles:` names one of {#states}
+      Station = Data.define(:key, :label, :states, :agents) do
+        # @return [Hash] `Station` in `types.ts`
+        def wire = { key: key.to_s, label:, agents: }
+      end
+
+      # Key, label and the states folded into it, in spine order. ⭐️ Planned
+      # sits with 🟡 Building and 🟢 Ready for Review with 👀 In Review,
+      # because on the board each pair is one stop with the same agents.
+      GROUPS = [
+        [:new, "New", %i[new]],
+        [:researched, "Researched", %i[researched retroactive]],
+        [:ready_for_planning, "Planning", %i[ready_for_planning]],
+        [:building, "Building", %i[planned building]],
+        [:building_ui, "Building UI", %i[building_ui]],
+        [:in_review, "Review", %i[ready_for_review in_review]],
+        [:pr, "Pull request", %i[approved deployed]]
+      ].freeze
+
+      module_function
+
+      # @param registry [OpenLanes::Agents::Registry]
+      # @return [Array<Station>]
+      def all(registry)
+        GROUPS.map do |key, label, states|
+          Station.new(key:, label:, states:, agents: registry.all.select { |a| a.handles.intersect?(states) }.map(&:name))
+        end
+      end
+
+      # The stop a plan in +state+ is shown at. A state off the spine (🔴,
+      # 💩, 😱) is shown where the spine takes it next; one with no way
+      # forward (⭕️, 🅱️) where the plan was when it stopped, which only
+      # its history knows.
+      #
+      # @param state [Symbol]
+      # @param before [Symbol, nil] the state the plan was worked in last
+      # @return [Symbol]
+      def key_for(state, before: nil)
+        [state, Plans::StateMachine::SPINE[state], before].each do |candidate|
+          found = GROUPS.find { |_, _, states| states.include?(candidate) } and return found.first
+        end
+        GROUPS.first.first
+      end
+    end
+  end
+end

data/lib/openlanes/live/store.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "redis-client"
+
+module OpenLanes
+  module Live
+    # Redis, narrowed to what the contract uses: strings with an expiry,
+    # `SET NX EX` and compare-and-delete for claims, hashes, streams with a
+    # consumer group, `SCAN` by prefix, and `MULTI`.
+    #
+    # Narrow on purpose. {MemoryStore} answers the same methods, and the
+    # suite runs one shared set of examples against both, so every method
+    # added here is a method the fake must earn too. A store that offered
+    # all of Redis would let the engine come to depend on a command the
+    # fake only pretends to understand.
+    #
+    # Every connection failure surfaces as {Unavailable}, so a caller that
+    # wants to keep running without Redis rescues one class, not a gem's.
+    class Store
+      # One stream entry: its id and its fields.
+      #
+      # @!attribute [r] id
+      #   @return [String] `<ms>-<seq>`
+      # @!attribute [r] fields
+      #   @return [Hash{String => String}] empty for an entry trimmed away
+      #     while it was still pending
+      Entry = Data.define(:id, :fields)
+
+      # Deletes the key only when it still holds the value this process wrote.
+      # A plain GET then DEL would delete a claim another node took in between.
+      COMPARE_AND_DELETE = <<~LUA
+        if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end
+      LUA
+
+      # Extends the key only when it still holds this process's value, so a
+      # renewal can never keep alive a claim that has passed to someone else.
+      COMPARE_AND_EXPIRE = <<~LUA
+        if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("expire", KEYS[1], ARGV[2]) else return 0 end
+      LUA
+
+      # Seconds a connection attempt or a command may take before the store
+      # reports Redis as unavailable. Short, because the engine asks on its
+      # tick and a hung Redis must not hang the run.
+      TIMEOUT = 2.0
+
+      # The writes {#multi} accepts. Reads inside a transaction answer
+      # nothing until it commits, so none are offered.
+      WRITES = %i[set del expire hset hdel xadd xack].freeze
+
+      # Records the writes of one {#multi} block, to be applied together.
+      class Transaction
+        def initialize
+          @calls = []
+        end
+
+        # @return [Array<Array(Symbol, Array, Hash)>]
+        attr_reader :calls
+
+        WRITES.each do |name|
+          define_method(name) do |*args, **kwargs|
+            @calls << [name, args, kwargs]
+            nil
+          end
+        end
+      end
+
+      # @param url [String]
+      # @param timeout [Float] seconds
+      def initialize(url:, timeout: TIMEOUT)
+        @url = url
+        @client = RedisClient.config(url:, timeout:, reconnect_attempts: 1).new_client
+      end
+
+      # @return [String]
+      attr_reader :url
+
+      # @return [Boolean] whether Redis answered
+      def ping = call("PING") == "PONG"
+
+      # @return [void]
+      def close = @client.close
+
+      # ---- strings ----------------------------------------------------------
+
+      # @param key [String]
+      # @return [String, nil]
+      def get(key) = call("GET", key)
+
+      # @param key [String]
+      # @param value [String]
+      # @param ex [Integer, nil] seconds to live
+      # @param nx [Boolean] only when the key does not exist
+      # @return [Boolean] whether the value was written
+      def set(key, value, ex: nil, nx: false) = call(*set_command(key, value, ex:, nx:)) == "OK"
+
+      # @param keys [Array<String>]
+      # @return [Integer] how many were removed
+      def del(*keys) = keys.empty? ? 0 : call("DEL", *keys)
+
+      # @param key [String]
+      # @param seconds [Integer]
+      # @return [Boolean] whether the key exists to expire
+      def expire(key, seconds) = call("EXPIRE", key, seconds) == 1
+
+      # @param key [String]
+      # @return [Integer] seconds left, -1 without an expiry, -2 when absent
+      def ttl(key) = call("TTL", key)
+
+      # @param key [String]
+      # @param expected [String]
+      # @return [Boolean] whether the key held +expected+ and is now gone
+      def compare_and_delete(key, expected) = call("EVAL", COMPARE_AND_DELETE, 1, key, expected) == 1
+
+      # @param key [String]
+      # @param expected [String]
+      # @param seconds [Integer]
+      # @return [Boolean] whether the key held +expected+ and was extended
+      def compare_and_expire(key, expected, seconds)
+        call("EVAL", COMPARE_AND_EXPIRE, 1, key, expected, seconds) == 1
+      end
+
+      # ---- hashes -----------------------------------------------------------
+
+      # @return [Boolean] whether the field is new
+      def hset(key, field, value) = call("HSET", key, field, value) == 1
+
+      # @return [String, nil]
+      def hget(key, field) = call("HGET", key, field)
+
+      # @return [Hash{String => String}]
+      def hgetall(key) = call("HGETALL", key).to_h
+
+      # @return [Integer] how many fields were removed
+      def hdel(key, *fields) = fields.empty? ? 0 : call("HDEL", key, *fields)
+
+      # ---- streams ----------------------------------------------------------
+
+      # @param key [String]
+      # @param fields [Hash{#to_s => #to_s}]
+      # @param maxlen [Integer, nil] trimmed to about this many entries
+      # @return [String] the new entry's id
+      def xadd(key, fields, maxlen: nil) = call(*xadd_command(key, fields, maxlen:))
+
+      # @return [Integer] entries in the stream
+      def xlen(key) = call("XLEN", key)
+
+      # Creates the group, and the stream with it. Asking twice is not an
+      # error: every engine start asks.
+      #
+      # @param key [String]
+      # @param group [String]
+      # @param from [String] "0" to deliver what is already there, "$" for
+      #   only what arrives later
+      # @return [Boolean] whether the group is new
+      def xgroup_create(key, group, from: "0")
+        call("XGROUP", "CREATE", key, group, from, "MKSTREAM") == "OK"
+      rescue RedisClient::CommandError => e
+        raise unless e.message.start_with?("BUSYGROUP")
+
+        false
+      end
+
+      # @param key [String]
+      # @param group [String]
+      # @param consumer [String]
+      # @param id [String] ">" for entries never delivered, "0" for this
+      #   consumer's delivered and unacknowledged ones
+      # @param count [Integer]
+      # @return [Array<Entry>]
+      def xreadgroup(key, group, consumer, id: ">", count: 100)
+        entries(call("XREADGROUP", "GROUP", group, consumer, "COUNT", count, "STREAMS", key, id)&.fetch(key, nil))
+      end
+
+      # @return [Integer] how many were acknowledged
+      def xack(key, group, *ids) = ids.empty? ? 0 : call("XACK", key, group, *ids)
+
+      # Entries after +id+. With +block+ it waits up to that many
+      # milliseconds for one to arrive.
+      #
+      # @param key [String]
+      # @param id [String] "$" for only what arrives from now
+      # @param count [Integer]
+      # @param block [Integer, nil] milliseconds
+      # @return [Array<Entry>]
+      def xread(key, id: "0", count: 100, block: nil)
+        reply = if block
+                  guarded { @client.blocking_call((block / 1000.0) + TIMEOUT, "XREAD", "BLOCK", block, "COUNT", count, "STREAMS", key, id) }
+                else
+                  call("XREAD", "COUNT", count, "STREAMS", key, id)
+                end
+        entries(reply&.fetch(key, nil))
+      end
+
+      # @return [Array<Entry>] oldest first
+      def xrange(key, start: "-", stop: "+", count: 100) = entries(call("XRANGE", key, start, stop, "COUNT", count))
+
+      # @return [Array<Entry>] newest first
+      def xrevrange(key, stop: "+", start: "-", count: 100) = entries(call("XREVRANGE", key, stop, start, "COUNT", count))
+
+      # ---- keys -------------------------------------------------------------
+
+      # Every key starting with +prefix+, by cursor, so a large keyspace is
+      # never asked for in one blocking `KEYS`.
+      #
+      # @param prefix [String]
+      # @return [Array<String>]
+      def scan(prefix)
+        cursor = "0"
+        found = []
+        loop do
+          cursor, batch = call("SCAN", cursor, "MATCH", "#{glob_escape(prefix)}*", "COUNT", 500)
+          found.concat(batch)
+          break if cursor == "0"
+        end
+        found.uniq.sort
+      end
+
+      # ---- transactions -----------------------------------------------------
+
+      # The writes the block makes, applied atomically.
+      #
+      # @yieldparam tx [Transaction]
+      # @return [void]
+      def multi
+        tx = Transaction.new
+        yield tx
+        return if tx.calls.empty?
+
+        guarded { @client.multi { |t| tx.calls.each { |name, args, kwargs| t.call(*command_for(name, args, kwargs)) } } }
+        nil
+      end
+
+      private
+
+      # @return [Object] the reply
+      def call(*command) = guarded { @client.call(*command) }
+
+      # @return [Object] the block's value
+      # @raise [OpenLanes::Live::Unavailable]
+      def guarded
+        yield
+      rescue RedisClient::CommandError
+        raise
+      rescue RedisClient::Error => e
+        raise Unavailable, "Redis at #{Live.mask(url)} is unavailable: #{e.message.sub(/\s*\(redis:.*\)\z/, "")}"
+      end
+
+      # @return [Array] the raw command for one transaction write
+      def command_for(name, args, kwargs)
+        case name
+        when :set then set_command(*args, **kwargs)
+        when :xadd then xadd_command(*args, **kwargs)
+        else [name.to_s.upcase, *args]
+        end
+      end
+
+      # @return [Array]
+      def set_command(key, value, ex: nil, nx: false)
+        ["SET", key, value, *("NX" if nx), *(["EX", ex] if ex)]
+      end
+
+      # @return [Array]
+      def xadd_command(key, fields, maxlen: nil)
+        ["XADD", key, *(["MAXLEN", "~", maxlen] if maxlen), "*", *fields.flat_map { |k, v| [k.to_s, v.to_s] }]
+      end
+
+      # @param raw [Array, nil] `[[id, [field, value, ...]], ...]`
+      # @return [Array<Entry>]
+      def entries(raw)
+        Array(raw).map { |id, pairs| Entry.new(id:, fields: Array(pairs).each_slice(2).to_h) }
+      end
+
+      # @return [String] +prefix+ with glob metacharacters taken literally
+      def glob_escape(prefix) = prefix.gsub(/[*?\[\]\\]/) { "\\#{it}" }
+    end
+  end
+end

data/lib/openlanes/live.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  # The live run in Redis (plan 004): the engine publishes its board there
+  # and reads the page's commands from there, and machines sharing one Redis
+  # see each other's boards and never take each other's plans (W6, W13, W26).
+  #
+  # The engine builds a {Session}. The API server reads boards with {.board},
+  # queues commands with {.enqueue} and follows answers with {.replies}, all
+  # over the same {Keys}, so neither side spells a key.
+  module Live
+    # Where Redis is when nothing says otherwise (W16).
+    DEFAULT_URL = "redis://localhost:6379/0"
+
+    # Redis could not be reached, or stopped answering.
+    class Unavailable < Error; end
+
+    module_function
+
+    # W16's order: `--redis-url`, then `.openlanes.yml`'s `redis_url:`, then
+    # `$REDIS_URL`, then {DEFAULT_URL}.
+    #
+    # @param option [String, nil] what `--redis-url` typed
+    # @param config [OpenLanes::Config]
+    # @param env [Hash]
+    # @return [String]
+    def redis_url(option: nil, config: Config.current, env: ENV)
+      [option, config.redis_url, env["REDIS_URL"]].map { it.to_s.strip }.find { !it.empty? } || DEFAULT_URL
+    end
+
+    # The address with any password replaced, for logs and the page.
+    #
+    # @param url [String]
+    # @return [String]
+    def mask(url) = url.to_s.sub(%r{\A([a-z][a-z0-9+.-]*://)([^:@/]*):[^@/]+@}i, '\1\2:***@')
+
+    # @param url [String]
+    # @return [OpenLanes::Live::Store]
+    def store(url) = Store.new(url:)
+
+    # @return [OpenLanes::Live::MemoryStore]
+    def memory_store(**) = MemoryStore.new(**)
+
+    # A store that has answered, or the reason there is none.
+    #
+    # @param url [String]
+    # @return [OpenLanes::Live::Store]
+    # @raise [OpenLanes::Live::Unavailable]
+    def connect(url)
+      store = Store.new(url:)
+      store.ping or raise Unavailable, "Redis at #{mask(url)} did not answer PING"
+      store
+    end
+
+    # @return [OpenLanes::Live::Session]
+    def session(**) = Session.new(**)
+
+    # This checkout's keys, for the API server beside its engine.
+    #
+    # @param root [String]
+    # @return [OpenLanes::Live::Keys]
+    def keys(root:, node: Node.current(root:)) = Keys.new(repo: Repo.for(root), node: node.name)
+
+    # `Board` in `web/src/api/types.ts`: this node's snapshot and every other
+    # live node's on the same repository. A node is live while its snapshot
+    # key exists; one whose key has expired is left out.
+    #
+    # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+    # @param keys [OpenLanes::Live::Keys]
+    # @return [Hash] `{me: Hash or nil, others: Array<Hash>}`, parsed JSON
+    def board(store:, keys:)
+      registered = store.hgetall(keys.nodes).keys
+      snapshots = (registered | [keys.node]).to_h { |name| [name, store.get(keys.snapshot(name))] }.compact
+      # A node is in the registry for as long as it heartbeats; one that died
+      # without closing never takes itself out, so whoever reads prunes it.
+      store.hdel(keys.nodes, *(registered - snapshots.keys))
+      others = snapshots.except(keys.node).values.map { JSON.parse(it) }
+      others.each { |snapshot| snapshot["node"]["me"] = false }
+      { me: snapshots[keys.node]&.then { JSON.parse(it) }, others: others.sort_by { it.dig("node", "host").to_s } }
+    end
+
+    # Queue one command for this node's engine.
+    #
+    # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+    # @param keys [OpenLanes::Live::Keys]
+    # @param input [Hash, String] a `Command`
+    # @return [OpenLanes::Live::Reply] accepted
+    # @raise [OpenLanes::Live::Command::Invalid] for the API server's 422
+    def enqueue(store:, keys:, input:)
+      command = Command.parse(input)
+      store.xadd(keys.commands, { json: JSON.generate(command.wire) })
+      Reply.new(id: command.id, status: "accepted")
+    end
+
+    # Replies after +after+, oldest first, with the stream id of each so the
+    # caller can carry on from the last.
+    #
+    # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+    # @param keys [OpenLanes::Live::Keys]
+    # @param after [String] a stream id, "0" for all kept, "$" for new only
+    # @param block [Integer, nil] milliseconds to wait for one
+    # @return [Array<Array(String, Hash)>] stream id and the `Reply`
+    def replies(store:, keys:, after: "$", block: nil)
+      store.xread(keys.replies, id: after, block:).map { |entry| [entry.id, JSON.parse(entry.fields["json"])] }
+    end
+  end
+end

data/lib/openlanes/plans/dev_work.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # Telling "this belongs to no specification" apart from "nobody could tell".
+    #
+    # Both end up without a plan number, and filing them under one marker loses
+    # the difference between a finished thought and an open question. A
+    # dependency bump genuinely implements no specification and never will —
+    # that is an assertion, and `[dev]` records it. A pull request that adds
+    # Schedule K-1 for four tax years plainly implements *something*; nothing
+    # here could work out what, and `[none]` records that instead, as a job left
+    # for a human rather than a verdict.
+    #
+    # The bar for `[dev]` is deliberately high. Marking real work as `[dev]`
+    # tells everyone afterwards it was never worth a plan, and nobody re-opens a
+    # question that looks settled. `[none]` is visibly unfinished, so the cost of
+    # guessing wrong in that direction is somebody spending a minute on it.
+    module DevWork
+      module_function
+
+      # Titles that say what they are: dependency bumps, release chores, CI.
+      TITLES = [
+        /\Abump\s+\S+\s+from\s+\S+\s+to\s+\S+/i,
+        /\A(?:chore|ci|build|deps|style|refactor)(?:\([^)]*\))?:/i,
+        /\Abump\s+(?:to\s+)?v?\d+\.\d+/i
+      ].freeze
+
+      # Paths that are how the project is built rather than what it does.
+      PLUMBING = %r{\A(?:\.github/|\.circleci/|\.devcontainer/|bin/|scripts/|
+                         Dockerfile|\.dockerignore|Gemfile(?:\.lock)?|justfile|Rakefile|
+                         \.rubocop\.ya?ml|\.standard\.ya?ml|\.gitignore|\.tool-versions)}x
+
+      # Files that say nothing either way, so they neither prove plumbing nor
+      # disprove it — every pull request in this tool's world touches `.plans`.
+      NEUTRAL = %r{\A(?:#{PLANS_DIR}/|CHANGELOG|README)}
+
+      # @param title [String]
+      # @param files [Array<String>] paths in the diff
+      # @return [Boolean] whether this can be *asserted* to implement no plan
+      def developer?(title, files = [])
+        return true if TITLES.any? { |pattern| title.to_s.match?(pattern) }
+
+        judged = Array(files).reject { |path| path.match?(NEUTRAL) }
+        return false if judged.empty?
+
+        judged.all? { |path| path.match?(PLUMBING) }
+      end
+
+      # @param title [String]
+      # @param files [Array<String>]
+      # @return [String] the marker to stamp on it
+      def marker(title, files = []) = developer?(title, files) ? NO_PLAN_PREFIX : NONE_PREFIX
+    end
+  end
+end

data/lib/openlanes/plans/feature.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # Lowercase in the middle of a title, capitalised at the front.
+    SMALL_WORDS = %w[a an and as at but by for from in into nor of on or per the to via vs with].freeze
+
+    # Slug words that are really acronyms and should shout.
+    ACRONYMS = %w[
+      abac ai api aws cdn ci cd cli cms cors cpu crm css csv db dns dsl e2e ec2 etl gcp gdpr gpu gui
+      html http https iam id ide jwt json k8s llm ml mcp mvp npm oauth orm otp pdf pii poc pr prs qa
+      rbac rds rest rls rpc rss s3 saas sdk seo sns spa sql sqs sre ssh sso ssl ssr tls tui ts tsx ui
+      ux uuid vpc vpn xml yaml
+    ].freeze
+
+    # Words with a house spelling that neither capitalize nor upcase gets right.
+    SPECIAL_CASE = {
+      "github" => "GitHub", "gitlab" => "GitLab", "graphql" => "GraphQL", "ios" => "iOS",
+      "javascript" => "JavaScript", "macos" => "macOS", "nodejs" => "Node.js", "oauth" => "OAuth",
+      "openai" => "OpenAI", "postgres" => "PostgreSQL", "postgresql" => "PostgreSQL",
+      "typescript" => "TypeScript", "uuidv7" => "UUIDv7", "websocket" => "WebSocket"
+    }.freeze
+
+    # Turn a kebab slug into a proper name: `law-as-data` → "Law as Data".
+    #
+    # @param slug [String]
+    # @return [String]
+    def self.titleize(slug)
+      words = slug.to_s.split(/[-_\s.]+/).reject(&:empty?)
+      return "" if words.empty?
+
+      words.each_with_index.map { |word, i|
+        lower = word.downcase
+        if SPECIAL_CASE.key?(lower)
+          SPECIAL_CASE[lower]
+        elsif ACRONYMS.include?(lower)
+          lower.upcase
+        elsif i.positive? && SMALL_WORDS.include?(lower)
+          lower
+        elsif lower.match?(/\A\d+\z/)
+          lower
+        else
+          lower.sub(/\A./, &:upcase)
+        end
+      }.join(" ")
+    end
+
+    # The one place a plan folder's name is spelled out: `NNN.MM-<emoji> → <slug>`.
+    #
+    # The spaced arrow after the emoji is deliberate: an emoji renders two cells
+    # wide and visually swallows a bare dash beside it, so `🔎-refactor` reads
+    # as if the emoji and the slug were touching. Everything that mints or
+    # renames a folder goes through here; {Feature.parse} accepts the older
+    # `--` and single-dash spellings too, and `resync dirs` migrates them on
+    # contact.
+    #
+    # @param ordinal [OpenLanes::Plans::Ordinal, String]
+    # @param status [OpenLanes::Plans::Status]
+    # @param slug [String]
+    # @return [String]
+    def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji} → #{slug}"
+
+    # One `NNN.MM-<emoji> → <slug>` folder, decoded.
+    #
+    # @!attribute [r] ordinal
+    #   @return [OpenLanes::Plans::Ordinal]
+    # @!attribute [r] status
+    #   @return [OpenLanes::Plans::Status]
+    # @!attribute [r] slug
+    #   @return [String]
+    # @!attribute [r] dirname
+    #   @return [String] exactly as it is on disk
+    # @!attribute [r] path
+    #   @return [String] absolute
+    Feature = Data.define(:ordinal, :status, :slug, :dirname, :path) do
+      include Comparable
+
+      # Decode a folder name, or return nil when it is not a plan folder.
+      #
+      # @param path [String] absolute path to a candidate directory
+      # @return [OpenLanes::Plans::Feature, nil]
+      def self.parse(path)
+        dirname = File.basename(path)
+        ordinal = Ordinal.from_dirname(dirname) or return nil
+
+        rest = dirname.sub(/\A[\d.]+[-_]/, "")
+        head, tail = rest.split(/\s*→\s*|[-_]/, 2)
+
+        # A leading segment with no ASCII word character is the status emoji.
+        # The slug strips any further separators: the canonical spelling puts
+        # a spaced arrow after the emoji, and folders from before that rule put
+        # two dashes, or one.
+        status = (OpenLanes::Plans.status_for_emoji(head) if tail && !head.to_s.empty? && !head.match?(/[A-Za-z0-9]/))
+        slug = status ? tail.sub(/\A[-_\s]+/, "") : rest
+
+        new(ordinal:, status: status || STATUS_BY_KEY.fetch(:new), slug:, dirname:, path:)
+      end
+
+      # @return [String] proper name, e.g. "Law as Data"
+      def title = OpenLanes::Plans.titleize(slug)
+
+      # The folder name this feature would carry in a given state — the slug
+      # never moves, and the number is always rendered canonically, so this is
+      # also what repairs a folder written `018-⚪️--foo` before the `NNN.MM` rule.
+      #
+      # @param status [OpenLanes::Plans::Status]
+      # @return [String]
+      def dirname_as(status) = OpenLanes::Plans.plan_dirname(ordinal, status, slug)
+
+      # The number exactly as the folder writes it, which is not always the
+      # canonical rendering: `018-⚪️--foo` yields "018" where {#ordinal} renders
+      # "018.00".
+      #
+      # @return [String]
+      def dirname_ordinal = dirname.to_s[/\A[\d.]+/].to_s
+
+      # @return [Boolean] whether the number is written in full `NNN.MM` form
+      def padded? = dirname_ordinal == ordinal.to_s
+
+      # Whether the folder is already named the way this tool would name it —
+      # number padded, emoji matching the state it claims, slug unchanged.
+      #
+      # @return [Boolean]
+      def canonical? = dirname == dirname_as(status)
+
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other) = other.is_a?(self.class) ? [ordinal, dirname] <=> [other.ordinal, other.dirname] : nil
+    end
+  end
+end