openlanes 3.0.0 → 3.1.0

data/lib/openlanes/live/store.rb

@@ -45,7 +45,7 @@ module OpenLanes
 
       # 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
+      WRITES = %i[set del expire hset hdel xadd xack xtrim].freeze
 
       # Records the writes of one {#multi} block, to be applied together.
       class Transaction
@@ -144,6 +144,15 @@ module OpenLanes
       # @return [Integer] entries in the stream
       def xlen(key) = call("XLEN", key)
 
+      # Drops every entry older than +minid+, exactly rather than with `~`,
+      # so a message an hour old is gone when the hour is up, not when Redis
+      # next finds a whole node to free.
+      #
+      # @param key [String]
+      # @param minid [String] `<ms>-<seq>`, the oldest id kept
+      # @return [Integer] how many were removed
+      def xtrim(key, minid:) = call(*xtrim_command(key, minid:))
+
       # Creates the group, and the stream with it. Asking twice is not an
       # error: every engine start asks.
       #
@@ -169,6 +178,10 @@ module OpenLanes
       # @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))
+      rescue RedisClient::CommandError => e
+        raise unless e.message.start_with?("NOGROUP")
+
+        raise GroupMissing, e.message.lines.first.to_s.strip
       end
 
       # @return [Integer] how many were acknowledged
@@ -215,6 +228,24 @@ module OpenLanes
         found.uniq.sort
       end
 
+      # ---- pub/sub ----------------------------------------------------------
+
+      # @param channel [String]
+      # @param message [String]
+      # @return [Integer] how many subscriptions received it
+      def publish(channel, message) = call("PUBLISH", channel, message)
+
+      # A connection of its own, subscribed to +channels+ and +patterns+.
+      #
+      # @return [OpenLanes::Live::Subscriber]
+      def subscriber(channels: [], patterns: []) = Subscriber.new(url:, channels:, patterns:)
+
+      # The database in the URL. Pub/sub ignores databases, so whoever names
+      # a channel puts this in it (see {Keys#chat_room}).
+      #
+      # @return [Integer]
+      def db = @client.config.db.to_i
+
       # ---- transactions -----------------------------------------------------
 
       # The writes the block makes, applied atomically.
@@ -250,10 +281,14 @@ module OpenLanes
         case name
         when :set then set_command(*args, **kwargs)
         when :xadd then xadd_command(*args, **kwargs)
+        when :xtrim then xtrim_command(*args, **kwargs)
         else [name.to_s.upcase, *args]
         end
       end
 
+      # @return [Array]
+      def xtrim_command(key, minid:) = ["XTRIM", key, "MINID", minid]
+
       # @return [Array]
       def set_command(key, value, ex: nil, nx: false)
         ["SET", key, value, *("NX" if nx), *(["EX", ex] if ex)]

data/lib/openlanes/live/subscriber.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "redis-client"
+
+module OpenLanes
+  module Live
+    # One Redis pub/sub connection, subscribed once to the channels and
+    # patterns it was made with (plan 006's chat). A subscribed connection
+    # can do nothing else, so it is its own connection, never the {Store}'s.
+    #
+    # Made by {Store#subscriber}; {MemorySubscriber} is the suite's.
+    class Subscriber
+      # Seconds the shortest wait lasts. redis-client reads a timeout of 0 as
+      # "wait for ever", which is the one thing a polling loop must not do.
+      SHORTEST = 0.01
+
+      # @param url [String]
+      # @param channels [Array<String>]
+      # @param patterns [Array<String>]
+      # @param timeout [Float] seconds to connect and to wait for each confirmation
+      # @raise [OpenLanes::Live::Unavailable]
+      def initialize(url:, channels: [], patterns: [], timeout: Store::TIMEOUT)
+        @url = url
+        guarded do
+          @pubsub = RedisClient.config(url:, timeout:).new_client.pubsub
+          @pubsub.call("SUBSCRIBE", *channels) unless channels.empty?
+          @pubsub.call("PSUBSCRIBE", *patterns) unless patterns.empty?
+          confirm(channels.size + patterns.size, timeout)
+        end
+      rescue Unavailable
+        # The caller never gets this object, so nobody else can close the
+        # connection, and a chat retrying a NOPERM every step would pile up
+        # one open socket per try until the GC got round to them.
+        close
+        raise
+      end
+
+      # The next message, waiting up to +timeout+ seconds for one.
+      #
+      # @param timeout [Float]
+      # @return [Array(String, String), nil] its channel and its payload
+      # @raise [OpenLanes::Live::Unavailable]
+      def next_message(timeout)
+        loop do
+          event = read([timeout, SHORTEST].max) or return nil
+          case event.first
+          when "message" then return [event[1], event[2]]
+          when "pmessage" then return [event[2], event[3]]
+          end
+        end
+      end
+
+      # @return [void]
+      def close = @pubsub&.close
+
+      private
+
+      # Waits until Redis has confirmed every subscription, so a message
+      # published the moment this returns is one this connection receives.
+      #
+      # @return [void]
+      def confirm(expected, timeout)
+        confirmed = 0
+        while confirmed < expected
+          event = read(timeout) or raise Unavailable, "Redis at #{Live.mask(@url)} did not confirm a subscription"
+          confirmed += 1 if %w[subscribe psubscribe].include?(event.first)
+        end
+      end
+
+      # The next event on the connection. redis-client hands a refusal back
+      # as an error object rather than raising it, so a `NOPERM` from an ACL
+      # that withholds `PSUBSCRIBE` would otherwise reach `event.first` as a
+      # NoMethodError and kill the hub's thread without a word.
+      #
+      # @param timeout [Float]
+      # @return [Array, nil]
+      # @raise [OpenLanes::Live::Unavailable]
+      def read(timeout)
+        event = guarded { @pubsub.next_event(timeout) }
+        guarded { raise event } if event.is_a?(RedisClient::Error)
+        event
+      end
+
+      # @return [Object] the block's value
+      # @raise [OpenLanes::Live::Unavailable]
+      def guarded
+        yield
+      rescue RedisClient::Error => e
+        raise Unavailable, "Redis at #{Live.mask(@url)} is unavailable: #{e.message.sub(/\s*\(redis:.*\)\z/, "")}"
+      end
+    end
+  end
+end

data/lib/openlanes/live.rb

@@ -17,6 +17,11 @@ module OpenLanes
     # Redis could not be reached, or stopped answering.
     class Unavailable < Error; end
 
+    # A stream's consumer group is not there: a Redis that restarted empty
+    # (W32) took it with everything else. Whoever reads the group creates it
+    # again; nothing is wrong with the connection.
+    class GroupMissing < Error; end
+
     module_function
 
     # W16's order: `--redis-url`, then `.openlanes.yml`'s `redis_url:`, then
@@ -36,6 +41,16 @@ module OpenLanes
     # @return [String]
     def mask(url) = url.to_s.sub(%r{\A([a-z][a-z0-9+.-]*://)([^:@/]*):[^@/]+@}i, '\1\2:***@')
 
+    # The address with all of its userinfo replaced, user name included, for
+    # a page anyone on the network can open. {.mask} keeps the user name
+    # because a log read by the person who ran the engine is better for it; a
+    # page shown on a shared screen is not.
+    #
+    # @param url [String]
+    # @return [String] `redis://:***@host:6379/0`, or the URL as it was when
+    #   it carries no userinfo
+    def redact(url) = url.to_s.sub(%r{\A([a-z][a-z0-9+.-]*://)[^@/]*@}i, '\1:***@')
+
     # @param url [String]
     # @return [OpenLanes::Live::Store]
     def store(url) = Store.new(url:)
@@ -54,9 +69,64 @@ module OpenLanes
       store
     end
 
+    # The process's {ChoiceJudge}: one, so its answers are shared by every
+    # snapshot built here; nil without TYPESAFE_API_KEY, and nil in the suite.
+    #
+    # @return [OpenLanes::Live::ChoiceJudge, nil]
+    def choice_judge
+      return @choice_judge if defined?(@choice_judge)
+
+      @choice_judge = ChoiceJudge.from_env
+    end
+
+    # @param judge [#call, nil] answers `call(text)` with true, false or nil
+    # @return [void]
+    def choice_judge=(judge)
+      @choice_judge = judge
+    end
+
+    # The process's {ChoiceConverter}: nil without OPENROUTER_API_KEY, and
+    # nil in the suite.
+    #
+    # @return [OpenLanes::Live::ChoiceConverter, nil]
+    def choice_converter
+      return @choice_converter if defined?(@choice_converter)
+
+      @choice_converter = ChoiceConverter.from_env
+    end
+
+    # @param converter [#call, nil] answers `call(heading:, body:)` with a
+    #   {ChoiceConverter::Result}
+    # @return [void]
+    def choice_converter=(converter)
+      @choice_converter = converter
+    end
+
+    # The process's {Interviewer} (M6): nil without OPENROUTER_API_KEY, and
+    # nil in the suite.
+    #
+    # @return [OpenLanes::Live::Interviewer, nil]
+    def interviewer
+      return @interviewer if defined?(@interviewer)
+
+      @interviewer = Interviewer.from_env
+    end
+
+    # @param interviewer [#call, nil] answers `call(idea:)` with
+    #   {Interviewer::Question}s
+    # @return [void]
+    def interviewer=(interviewer)
+      @interviewer = interviewer
+    end
+
     # @return [OpenLanes::Live::Session]
     def session(**) = Session.new(**)
 
+    # The conversation with the run's copilot (W17), on +store+ under +keys+.
+    #
+    # @return [OpenLanes::Live::Copilot]
+    def copilot(**) = Copilot.new(**)
+
     # This checkout's keys, for the API server beside its engine.
     #
     # @param root [String]
@@ -90,7 +160,7 @@ module OpenLanes
     # @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) })
+      EventBus.for(store).append(keys.commands, { json: JSON.generate(command.wire) })
       Reply.new(id: command.id, status: "accepted")
     end
 

data/lib/openlanes/plans/blocked_file.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # The bodies of the questions in `blocked.md`: the lines under each
+    # `## Bn` heading, up to the next heading of any kind or the next `## An`;
+    # and the answers under `## An`, which run to the next `Bn` or `An`.
+    #
+    # The page reads a body to show it and the engine reads one to rewrite it
+    # into choices, so both find its edges here; two readers with two ideas
+    # of where a question ends would rewrite text the page never showed.
+    # Pure: text in, text out.
+    module BlockedFile
+      # Any Markdown heading, which ends the body of the question above it.
+      HEADING = /^[ \t]{0,3}\#{1,6}[ \t]/
+
+      # What sits between `A1` and the answer on its heading: a `.`, `:` or
+      # `)`, the close of a bold `**A1.**`, or a dash with a space after it.
+      # Only that, because the answer's own punctuation is part of it: `-1`
+      # and `--no-delete` are decisions, and `1` and `no-delete` the opposite.
+      SEPARATOR = /\A[ \t]*[.:)]?\**[ \t]*(?:[-–—][ \t]+)?/
+
+      # A question or an answer heading, either of which ends an answer.
+      BLOCK = Regexp.union(OPEN_BLOCK, ANSWER_BLOCK)
+
+      module_function
+
+      # @param text [String] the whole of blocked.md
+      # @return [Hash{Integer => String}] each question's number to the
+      #   lines under its heading; a number written twice keeps the last
+      def bodies(text)
+        lines = text.to_s.lines
+        spans(lines).transform_values { |(from, to)| lines[from...to].join }
+      end
+
+      # The answers waiting under `## An` headings, by number, which is how
+      # the harness copies each question and its answer into the asking
+      # agent's journal (M3) before the broker drains them.
+      #
+      # An answer is often its heading: `## A2. Retain, do not delete`, with
+      # only who decided under it. So the words after the number are part of
+      # it. And it is a person's text, which the page writes verbatim, so a
+      # heading inside it (`### Database`) is part of it too; only the next
+      # question or answer ends it.
+      #
+      # @param text [String] the whole of blocked.md
+      # @return [Hash{Integer => String}] each answer's number to its heading's
+      #   words, if any, and the lines under it
+      def answers(text)
+        lines = text.to_s.lines
+        spans(lines, ANSWER_BLOCK, ends: BLOCK).to_h do |number, (from, to)|
+          title = lines[from - 1].sub(ANSWER_BLOCK, "").sub(SEPARATOR, "").strip
+          [number, "#{"#{title}\n" unless title.empty?}#{lines[from...to].join}"]
+        end
+      end
+
+      # +text+ with question +number+'s body replaced by +body+, its heading
+      # and everything else as they were.
+      #
+      # @param text [String] the whole of blocked.md
+      # @param number [Integer]
+      # @param body [String]
+      # @return [String, nil] nil when the file has no such question
+      def replace(text, number, body)
+        lines = text.to_s.lines
+        from, to = spans(lines)[number]
+        return nil unless from
+
+        lines[from - 1] = "#{lines[from - 1].chomp}\n"
+        section = ["\n", "#{body.strip}\n"]
+        section << "\n" if to < lines.size
+        (lines[0...from] + section + lines[to..]).join
+      end
+
+      # +text+ with answer +number+ taken out and +note+ put at the top of its
+      # question's body, so the question is open again and says why.
+      #
+      # An answer the broker read and would not fold in otherwise sits under
+      # its question for good: the page counts the question answered and
+      # hides it, and the broker refuses it every time it is asked. Before
+      # the options, because the page reads a body's options off its end.
+      #
+      # @param text [String] the whole of blocked.md
+      # @param number [Integer]
+      # @param note [String]
+      # @return [String, nil] nil when the file has no such question or answer
+      def reject(text, number, note)
+        lines = text.to_s.lines
+        from, to = spans(lines, ANSWER_BLOCK, ends: BLOCK)[number]
+        return nil unless from && bodies(text).key?(number)
+
+        reopened = (lines[0...(from - 1)] + lines[to..]).join
+        replace(reopened, number, "#{note.strip}\n\n#{bodies(reopened)[number].strip}")
+      end
+
+      # @param lines [Array<String>]
+      # @param pattern [Regexp] {OPEN_BLOCK} for questions, {ANSWER_BLOCK}
+      #   for answers; either kind of heading ends the other's body
+      # @param ends [Regexp] what else ends a body: any heading, by default
+      # @return [Hash{Integer => Array(Integer, Integer)}] each block's
+      #   number to the first line under its heading and the line that ends it
+      def spans(lines, pattern = OPEN_BLOCK, ends: HEADING)
+        found = {}
+        open = nil
+        lines.each_with_index do |line, i|
+          number = line[pattern, 1]
+          if number || line.match?(ends) || line.match?(OPEN_BLOCK) || line.match?(ANSWER_BLOCK)
+            found[open.first] = [open.last, i] if open
+            open = number && [number.to_i, i + 1]
+          end
+        end
+        found[open.first] = [open.last, lines.size] if open
+        found
+      end
+    end
+  end
+end

data/lib/openlanes/plans/choices.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # A question for a person, read as D3 shapes it: a short context paragraph,
+    # then lettered options `a)`, `b)`, `c)`, one of them recommended. The page
+    # draws a button per option, and `openlanes unblock` would offer the same
+    # ones, so both read them here rather than each guessing from the prose.
+    #
+    # Agents are told to write only that shape, but files written before D3,
+    # and agents that drift, use others. {.parse} reads them forgivingly:
+    #
+    # - lettered: `a)`, `(a)` or `a.` at the start of a line, or `a)` and
+    #   `(a)` inline, the way agents actually run a whole choice into one
+    #   paragraph; bullet-prefixed or bold-wrapped (`- **a)**`) alike
+    # - numbered: `1.`, `1)` or `Option 1:` at the start of a line
+    # - the W30 mark, `answers: yes, no`, which reads as `a) yes` `b) no`
+    #
+    # It is pure: text in, a value out, no file and no network. Whether the
+    # text really asks the reader to choose is a judgement the parser cannot
+    # make about a numbered list of steps already done, which is why the
+    # snapshot can ask {Live::ChoiceJudge} as well.
+    #
+    # @example
+    #   choices = Plans::Choices.parse("Rebase or merge?\n\na) Rebase (Recommended)\nb) Merge")
+    #   choices.context                 # => "Rebase or merge?"
+    #   choices.options.map(&:answer)   # => ["a) Rebase", "b) Merge"]
+    #   choices.recommended.letter      # => "a"
+    class Choices < Data.define(:context, :options)
+      # The text the person's choice sends back to the agent, beside how the
+      # option is shown. A yes/no option answers with the bare word, as W30
+      # promised agents ("branch on the word"); every other answers with its
+      # letter and label, so the agent can match either.
+      #
+      # @!attribute letter [String] "a", "b", …
+      # @!attribute label [String] what the button says, the marker stripped
+      # @!attribute recommended [Boolean]
+      # @!attribute answer [String] what choosing it sends
+      Option = Data.define(:letter, :label, :recommended, :answer) do
+        # @return [Hash] the page's `QuestionOption`
+        def to_h = { letter:, label:, recommended:, answer: }
+      end
+
+      # How an agent marked a yes/no question before D3 (W30), on its own line.
+      # Still read, and still what the prompt shows for a plain yes/no.
+      YES_NO_MARK = "answers: yes, no"
+
+      # {YES_NO_MARK}, read forgivingly: brackets, case and spacing vary.
+      YES_NO = /answers:\s*\[?\s*yes\s*,\s*no\s*\]?/i
+
+      # A letter's marker. At the start of a line (after a bullet or bold) it
+      # may be `a)`, `(a)` or `a.`, either case; inline only the parenthesised
+      # lowercase forms count, because `e.g.` and `I.` are prose.
+      LETTER_LINE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?(?:\(([a-z])\)|([a-z])[).])(?:\*\*)?[ \t]+/i
+      LETTER_INLINE = /(?<=[\s:])(?:\*\*)?(?:\(([a-z])\)|([a-z])\))(?:\*\*)?[ \t]+/
+
+      # A number's marker, line start only: `1.`, `1)`, `Option 1:`.
+      NUMBER_LINE = /^[ \t]*(?:[-*+][ \t]+)?(?:\*\*)?(?:option[ \t]+(\d{1,2})[:.)]|(\d{1,2})[.)])(?:\*\*)?[ \t]+/i
+
+      # A numbered list is also how agents report steps already done, so one
+      # counts as a choice only after something that asks.
+      ASKS = /\?|\b(?:choose|chose|pick|prefer|option|which|decide)\b/i
+
+      # The recommendation, in the ways it gets written: bracketed anywhere
+      # (`(Recommended)`, `[recommended]`), or bare as the option's first or
+      # last word ("Recommended. Rebase first"). A bare "recommended" mid-label
+      # is prose ("the recommended layout") and stays where it is.
+      RECOMMENDED = /
+        [[:blank:]]*(?:\*\*|_)?[(\[][[:blank:]]*recommended[[:blank:]]*[)\]](?:\*\*|_)?[[:blank:]]*[.:,;]?
+        | \A(?:\*\*|_)?recommended(?:\*\*|_)?[[:blank:]]*[.:,;—–-][[:blank:]]*
+        | [[:blank:]]*[—–-][[:blank:]]*(?:\*\*|_)?recommended(?:\*\*|_)?\.?\z
+      /ix
+
+      # The option the page's text box already is. D3 makes it the last
+      # choice of every question, so an agent that writes it out gets no
+      # second, dead button.
+      SOMETHING_ELSE = /\A(?:type|write|say)\s+something\s+(?:else\s+)?instead\b|\Asomething\s+else\b|\Aother\b/i
+
+      # A label that runs into a new paragraph is not a label: the list ended
+      # and prose followed it, so the options are not the end of the text.
+      PARAGRAPH = /\n[ \t]*\n/
+
+      class << self
+        # @param text [String, nil] a question's body, Markdown
+        # @return [OpenLanes::Plans::Choices, nil] nil when the text offers
+        #   fewer than two options, or its options are not where it ends
+        def parse(text)
+          text = text.to_s.strip
+          return nil if text.empty?
+
+          marked(text) || lettered(text) || numbered(text)
+        end
+
+        # A yes/no question about +context+.
+        #
+        # @param context [String]
+        # @return [OpenLanes::Plans::Choices]
+        def yes_no(context)
+          new(context: context.to_s.strip,
+            options: [Option.new(letter: "a", label: "yes", recommended: false, answer: "yes"),
+                      Option.new(letter: "b", label: "no", recommended: false, answer: "no")])
+        end
+
+        # The D3 shape, written out: the context, a blank line, then one
+        # lettered line per label with the recommended one marked. {.parse}
+        # reads it back into the same labels, which is how a rewritten
+        # question proves it kept its shape.
+        #
+        # @param context [String]
+        # @param labels [Array<String>] one line each
+        # @param recommended [Integer] the index of the recommended label
+        # @return [String] Markdown, ending in a newline
+        def write(context:, labels:, recommended:)
+          lines = labels.each_with_index.map do |label, i|
+            "#{("a".ord + i).chr}) #{label}#{" (Recommended)" if i == recommended}"
+          end
+          "#{context.to_s.strip}\n\n#{lines.join("\n")}\n"
+        end
+
+        private
+
+        # The W30 mark, on a line of its own.
+        def marked(text)
+          line = /^[ \t]*#{YES_NO.source}[ \t]*$\n?/i
+          return nil unless text.match?(line)
+
+          yes_no(text.gsub(line, ""))
+        end
+
+        # A line's marker also matches inline from its letter on, so the
+        # inline match inside one (the `a)` of `- a)`) is dropped: kept, it
+        # would leave the bullet behind at the end of the context.
+        def lettered(text)
+          lines = scan(text, LETTER_LINE) { |m| (m[1] || m[2]).downcase.ord - "a".ord }
+          inline = scan(text, LETTER_INLINE) { |m| (m[1] || m[2]).ord - "a".ord }
+                   .reject { |start, _, _| lines.any? { |from, to, _| (from...to).cover?(start) } }
+          run(text, (lines + inline).sort_by(&:first))
+        end
+
+        def numbered(text)
+          markers = scan(text, NUMBER_LINE) { |m| (m[1] || m[2]).to_i - 1 }
+          choices = run(text, markers)
+          choices if choices&.context&.match?(ASKS)
+        end
+
+        # Every marker in +text+ as `[start, finish, index]`, index 0 for `a`
+        # or `1`.
+        def scan(text, pattern)
+          found = []
+          text.scan(pattern) do
+            match = Regexp.last_match
+            found << [match.begin(0), match.end(0), yield(match)]
+          end
+          found
+        end
+
+        # The last run of markers that counts 0, 1, 2… up to the end of the
+        # text. The last, because a context may itself mention "a) or b)"
+        # before the real options; and to the end, because a list followed by
+        # more prose was something other than a choice.
+        def run(text, markers)
+          markers.each_index.reverse_each do |first|
+            next unless markers[first].last.zero?
+
+            picked = sequence(markers.drop(first))
+            next if picked.size < 2
+
+            choices = build(text, picked)
+            return choices if choices
+          end
+          nil
+        end
+
+        # From a marker for index 0, the next marker for 1, then 2, skipping
+        # anything out of order (an `(e)` quoted inside a label).
+        def sequence(markers)
+          markers.each_with_object([]) do |marker, picked|
+            picked << marker if marker.last == picked.size
+          end
+        end
+
+        def build(text, picked)
+          labels = picked.each_with_index.map do |(_, finish, _), i|
+            text[finish...(picked[i + 1]&.first || text.size)].strip
+          end
+          return nil if labels.any? { it.empty? || it.match?(PARAGRAPH) }
+
+          options = labels.each_with_index.map { |label, i| option(label, i) }
+          options.pop if options.last&.label&.match?(SOMETHING_ELSE)
+          return nil if options.size < 2
+
+          new(context: text[0...picked.first.first].strip, options: only_one_recommended(options))
+        end
+
+        def option(raw, index)
+          recommended = raw.match?(RECOMMENDED)
+          label = unbold(raw.sub(RECOMMENDED, " ").strip).strip
+          letter = ("a".ord + index).chr
+          Option.new(letter:, label:, recommended:, answer: "#{letter}) #{label}")
+        end
+
+        # A bold marker leaves its partner behind: `**a) Rebase**` becomes
+        # `Rebase**`. An odd count of `**` means one of them lost its pair.
+        def unbold(label)
+          label = label.sub('**', "") if label.scan("**").size.odd?
+          label = label[2...-2].strip if label.start_with?("**") && label.end_with?("**") && label.size > 4
+          label
+        end
+
+        # D3 says exactly one; an agent that recommends two has recommended
+        # the first, and the page shows one tag rather than several.
+        def only_one_recommended(options)
+          first = options.index(&:recommended)
+          options.each_with_index.map { |o, i| o.recommended && i != first ? o.with(recommended: false) : o }
+        end
+      end
+
+      # @return [OpenLanes::Plans::Choices::Option, nil]
+      def recommended = options.find(&:recommended)
+
+      # @return [Boolean] whether the options are yes and no
+      def yes_no? = options.map(&:label) == %w[yes no]
+
+      # @return [Array<Hash>] the page's `QuestionOption[]`
+      def to_a = options.map(&:to_h)
+    end
+  end
+end