agentilda 1.0.3

data/lib/agentilda/markdown.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # The smallest Markdown reader that covers what plan folders actually hold.
+  # No CommonMark ambitions: it needs to find a GFM table and split its rows.
+  module Markdown
+    module_function
+
+    # Split a table row into stripped cells.
+    #
+    # @param row [String] a line beginning, and usually ending, with `|`
+    # @return [Array<String>]
+    def cells(row)
+      row.strip.sub(/\A\|/, "").sub(/\|\z/, "").split(/(?<!\\)\|/).map(&:strip)
+    end
+
+    # @param row [String]
+    # @return [Boolean] whether this is a `|---|:--:|` alignment row
+    def delimiter_row?(row)
+      parsed = cells(row)
+      !parsed.empty? && parsed.all? { |c| c.match?(/\A:?-+:?\z/) }
+    end
+
+    # Every GFM table in the document, in order.
+    #
+    # @param text [String]
+    # @return [Array<Hash{Symbol => Array}>] `{header:, rows:}`
+    def tables(text)
+      lines = text.to_s.lines(chomp: true)
+      found = []
+      index = 0
+
+      while index < lines.length
+        head = lines[index]
+        rule = lines[index + 1]
+
+        unless head&.strip&.start_with?("|") && rule&.strip&.start_with?("|") && delimiter_row?(rule)
+          index += 1
+          next
+        end
+
+        body = []
+        cursor = index + 2
+        while cursor < lines.length && lines[cursor].strip.start_with?("|")
+          body << cells(lines[cursor])
+          cursor += 1
+        end
+
+        found << {header: cells(head), rows: body}
+        index = cursor
+      end
+
+      found
+    end
+  end
+end

data/lib/agentilda/ordinal.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # A plan's number, and therefore its identity. Set once when the folder is
+  # created and never changed: branch names, pull request titles and every
+  # `pull-requests.md` join on it, and renumbering breaks all of them silently.
+  #
+  # Always rendered `NNN.MM`. `002.00` is an ordinary plan, specified before it
+  # was built. `002.01` is retroactive — work that shipped between 002 and 003
+  # and was documented afterwards. The decimal marks a **sibling**, not
+  # containment: 002.01 is not part of 002.
+  #
+  # `000` is where the sequence starts, so the first plan of a project is
+  # `000.00`. It also absorbs the older meaning — work that predates the plan
+  # discipline — since either way it sorts first, which is where it belongs.
+  #
+  # @!attribute [r] major
+  #   @return [Integer] 0..999
+  # @!attribute [r] minor
+  #   @return [Integer] 0..99; zero for an ordinary plan
+  class Ordinal < Data.define(:major, :minor)
+    include Comparable
+
+    # The canonical form, plus the bare `NNN` that trees written before this
+    # rule still use and must remain readable.
+    PATTERN = /\A(\d{1,3})(?:\.(\d{1,2}))?\z/
+
+    # The most retroactive slots a single gap can hold.
+    MAX_MINOR = 99
+
+    # @param text [String, nil] e.g. "3", "003", "003.00", "018.01"
+    # @return [Agentilda::Ordinal, nil] nil when it is not a plan number
+    def self.parse(text)
+      m = PATTERN.match(text.to_s.strip)
+      m && new(major: m[1].to_i, minor: m[2].to_i)
+    end
+
+    # Pull the number off the front of a folder name.
+    #
+    # @param dirname [String] e.g. "018.01-✅--verify-against-filed-returns"
+    # @return [Agentilda::Ordinal, nil]
+    def self.from_dirname(dirname) = parse(dirname.to_s[/\A[\d.]+/])
+
+    # The next ordinary plan after everything in +existing+.
+    #
+    # The first plan in an empty tree is `000.00`, not `001.00`: the sequence
+    # counts from zero so that the very first specification — usually the
+    # project's own — sorts above everything and needs no gap reserved for it.
+    #
+    # @param existing [Array<Agentilda::Ordinal>]
+    # @return [Agentilda::Ordinal]
+    def self.next_major(existing)
+      return new(major: 0, minor: 0) if existing.empty?
+
+      new(major: existing.map(&:major).max + 1, minor: 0)
+    end
+
+    # The next retroactive slot in the gap after +major+.
+    #
+    # @param existing [Array<Agentilda::Ordinal>]
+    # @param major [Integer] the plan the work landed after
+    # @return [Agentilda::Ordinal]
+    # @raise [Agentilda::Error] when the gap is full
+    def self.next_minor(existing, major:)
+      taken = existing.select { |o| o.major == major }.map(&:minor).max || 0
+      if taken >= MAX_MINOR
+        raise Error, "all #{MAX_MINOR} retroactive slots after #{format("%03d", major)} are taken"
+      end
+
+      new(major:, minor: taken + 1)
+    end
+
+    # @return [Boolean] whether this plan was documented after the fact
+    def retroactive? = minor.positive?
+
+    # @return [String] the canonical `NNN.MM`
+    def to_s = format("%03d.%02d", major, minor)
+
+    # @return [String] what a pull request title carries
+    def to_prefix = "[#{self}]"
+
+    # @param other [Object]
+    # @return [Integer, nil]
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+
+      [major, minor] <=> [other.major, other.minor]
+    end
+  end
+end

data/lib/agentilda/progress_log.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # One line of `run --log FILE`, laid out as fixed-width columns.
+  #
+  # The log file is the only record of a headless run, and it is shared: two
+  # `agentilda run` invocations pointed at the same `--log` both append to
+  # it, interleaved, and so does every round within one run. That is what the
+  # process id column is for. Without it a reader cannot tell one run's agents
+  # from another's, and "started 003.00" twice looks like a bug rather than two
+  # machines doing the same work.
+  #
+  # Fixed columns are what make the file readable by eye and by `awk` alike. A
+  # value wider than its column is cut rather than allowed to push the columns
+  # out, and a value that is missing still occupies its width, so a round header
+  # with no plan or agent of its own lines up with the lines underneath it.
+  #
+  # @example
+  #   ProgressLog.render("editing spec.md", plan: "003.00", status: "⭐️ Planned",
+  #     agent: "yoda-writer", seconds: 42, round: "01", pid: 91_234)
+  #   #=> "[16:22:14 | 003.00 | ⭐️ Planned            | yoda-writer          | 01 |   91234 |    42s] editing spec.md"
+  module ProgressLog
+    # Wall clock only. A log line answers "when", and the date is the file's.
+    TIME_FORMAT = "%H:%M:%S"
+
+    # Width of {TIME_FORMAT}'s output.
+    TIME_WIDTH = 8
+
+    # "003.00".
+    PLAN_WIDTH = 6
+
+    # Derived from the widest state as {Status#to_s} renders it, emoji
+    # included, so a state added to {STATUSES} with a longer label cannot
+    # silently knock the columns after it out of line — then trimmed by five
+    # cells: the emoji already names the state, so the longest labels can
+    # afford to lose their tails to keep the line short.
+    STATUS_WIDTH = STATUSES.map { |status| UI.display_width(status.to_s) }.max - 5
+
+    # The longest specialist name in `agents/` is `palpatine-planner` at 17,
+    # and the names are hyphenated words rather than a bounded vocabulary, so
+    # this leaves room for one more without a reflow.
+    AGENT_WIDTH = 20
+
+    # Enough for a 32-bit process id, right justified.
+    PID_WIDTH = 7
+
+    # "01". Rounds cap at two digits; a run that reaches a third has bigger
+    # problems than this column.
+    ROUND_WIDTH = 2
+
+    # "  907s". Anything longer than four digits of seconds is an agent nobody
+    # is still waiting on.
+    SECONDS_WIDTH = 6
+
+    # Between columns, inside the brackets.
+    SEPARATOR = " | "
+
+    # Cells from the opening bracket to the closing one, separators included.
+    # The message starts one space after this on every line, whatever fields
+    # that line happens to be missing, so a reader indenting a wrapped message
+    # has a number to indent by.
+    COLUMN_WIDTHS = [TIME_WIDTH, PLAN_WIDTH, STATUS_WIDTH, AGENT_WIDTH, ROUND_WIDTH, PID_WIDTH,
+      SECONDS_WIDTH].freeze
+
+    # @see COLUMN_WIDTHS
+    LINE_WIDTH = COLUMN_WIDTHS.sum + (SEPARATOR.length * (COLUMN_WIDTHS.size - 1)) + 2
+
+    class << self
+      # Render one log line: bracketed fixed-width columns, then the message.
+      #
+      # No colour. The line goes to a file, where an escape sequence is neither
+      # readable nor the width it claims to be.
+      #
+      # @param message [String] the free-form tail, the only variable-width part
+      # @param plan [String, nil] the plan's ordinal, e.g. "003.00"
+      # @param status [String, nil] emoji and label, e.g. "⭐️ Planned"
+      # @param agent [String, nil] the specialist's name, e.g. "yoda-writer"
+      # @param seconds [Numeric, nil] how long this agent has been alive
+      # @param round [String, nil] which pass over the tree, e.g. "01"
+      # @param pid [Integer, nil] which run wrote the line
+      # @param at [Time] injectable, so a caller can render a fixed clock
+      # @return [String] one line, with no trailing newline
+      def render(message, plan: nil, status: nil, agent: nil, seconds: nil,
+        round: nil, pid: Process.pid, at: Time.now)
+        columns = [
+          left(at.strftime(TIME_FORMAT), TIME_WIDTH),
+          left(plan, PLAN_WIDTH),
+          left(status, STATUS_WIDTH),
+          left(agent, AGENT_WIDTH),
+          right(round, ROUND_WIDTH),
+          right(pid, PID_WIDTH),
+          right(duration(seconds), SECONDS_WIDTH)
+        ]
+
+        text = message.to_s
+        prefix = "[#{columns.join(SEPARATOR)}]"
+        text.empty? ? prefix : "#{prefix} #{text}"
+      end
+
+      # @param seconds [Numeric, nil]
+      # @return [String] whole seconds with a trailing "s", or blank for nil
+      def duration(seconds) = seconds.nil? ? "" : "#{seconds.round}s"
+
+      # @param value [Object, nil]
+      # @param width [Integer] terminal cells
+      # @return [String] padded on the right to exactly +width+ cells
+      def left(value, width) = UI.fit(value, width)
+
+      # {UI.fit} pads on the right, which is the wrong end for a number. Fit
+      # first so an over-long value is still truncated to the column, then move
+      # the padding to the front.
+      #
+      # @param value [Object, nil]
+      # @param width [Integer] terminal cells
+      # @return [String] padded on the left to exactly +width+ cells
+      def right(value, width)
+        text = UI.fit(value, width).rstrip
+        UI.fit("", width - UI.display_width(text)) + text
+      end
+    end
+  end
+end

data/lib/agentilda/publisher.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # Turns a finished worktree into a pushed branch and a pull request.
+  #
+  # This is the one place the harness reaches off the machine, so it requires
+  # `--commit`, is skipped with `--dont-push-anything`, and refuses anything
+  # it is not certain about. Everything it does is reported before it does it.
+  #
+  # Titles follow the convention the whole system joins on:
+  #
+  #     [002.00](A) Tenancy Households       — a plan's first pull request
+  #     [002.00](B) Tenancy Households       — its second
+  #
+  # The slug is title-cased from the folder name, so the title reads as a
+  # sentence rather than as a path fragment.
+  class Publisher
+    # A published, or publishable, pull request.
+    #
+    # @!attribute [r] ordinal
+    #   @return [Agentilda::Ordinal]
+    # @!attribute [r] branch
+    #   @return [String]
+    # @!attribute [r] title
+    #   @return [String]
+    # @!attribute [r] url
+    #   @return [String, nil] nil on a dry run or a refusal
+    # @!attribute [r] refusal
+    #   @return [String, nil]
+    Publication = Data.define(:ordinal, :branch, :title, :url, :refusal) do
+      # @return [Boolean]
+      def published? = !url.nil?
+    end
+
+    # A..Z, which is more parts than any feature should be split into.
+    LETTERS = ("A".."Z").to_a.freeze
+
+    # @param root [String] repository the worktree belongs to
+    # @param command [TTY::Command]
+    # @param base [String] the branch pull requests target
+    # @param dry_run [Boolean]
+    def initialize(root:, command: TTY::Command.new(printer: :null), base: "main", dry_run: true)
+      @root = root
+      @command = command
+      @base = base
+      @dry_run = dry_run
+    end
+
+    # Push one plan's branch and open its pull request.
+    #
+    # @param checkout [Agentilda::Worktree::Checkout]
+    # @param subject [Agentilda::Subject]
+    # @param letter [String, nil] force a part letter; nil auto-assigns
+    # @return [Agentilda::Publisher::Publication]
+    def publish(checkout:, subject:, letter: nil)
+      title = title_for(subject, letter)
+
+      unless checkout.dirty?
+        return refuse(subject, checkout, title, "nothing to publish — the worktree is unchanged")
+      end
+
+      return Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: nil) if @dry_run
+
+      commit(checkout, title)
+      push(checkout)
+      url = create_pull_request(checkout, subject, title)
+
+      Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil)
+    rescue TTY::Command::ExitError => e
+      refuse(subject, checkout, title, git_complaint(e))
+    end
+
+    # git and gh put the useful sentence in stderr, several lines below the
+    # command they echo. Reporting only the first line reports "it failed".
+    #
+    # @param error [TTY::Command::ExitError]
+    # @return [String]
+    def git_complaint(error)
+      lines = error.message.lines.map(&:strip).reject(&:empty?)
+      stderr = lines.find { |l| l.start_with?("stderr:") }
+      complaint = stderr&.delete_prefix("stderr:")&.strip
+
+      (complaint.to_s.empty? || complaint == "Nothing written") ? lines.first.to_s : complaint
+    end
+
+    # The title a plan's next pull request should carry.
+    #
+    # @param subject [Agentilda::Subject]
+    # @param letter [String, nil]
+    # @return [String]
+    def title_for(subject, letter = nil)
+      "[#{subject.feature.ordinal}](#{letter || auto_letter(subject)}) #{subject.feature.title}"
+    end
+
+    # Which part this is. Always a letter, starting at A: a plan that turns out
+    # to need only one pull request still reads consistently with every other,
+    # and nothing has to be renamed when a second arrives.
+    #
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def auto_letter(subject) = LETTERS.fetch(subject.pull_requests.size, LETTERS.last)
+
+    private
+
+    # @return [Hash]
+    def base_fields(subject, checkout, title)
+      {ordinal: subject.feature.ordinal, branch: checkout.branch, title:}
+    end
+
+    # @return [Agentilda::Publisher::Publication]
+    def refuse(subject, checkout, title, why)
+      Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: why)
+    end
+
+    # @param checkout [Agentilda::Worktree::Checkout]
+    # @param title [String]
+    # @return [void]
+    def commit(checkout, title)
+      run(checkout, "git", "add", "-A")
+      # The subject line drops the bracketed prefix: it belongs in the pull
+      # request title, where things join on it, not in every commit message.
+      run(checkout, "git", "commit", "-m", title.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
+    end
+
+    # @param checkout [Agentilda::Worktree::Checkout]
+    # @return [void]
+    def push(checkout) = run(checkout, "git", "push", "-u", "origin", checkout.branch)
+
+    # @return [String, nil] the pull request URL
+    def create_pull_request(checkout, subject, title)
+      Tempfile.create(["pr", ".md"]) do |file|
+        file.write(description(subject, title))
+        file.flush
+        result = run(checkout, "gh", "pr", "create", "-a", "@me", "-B", @base, "-t", title, "-F", file.path)
+        return result.out.to_s[%r{https://\S+}]
+      end
+    end
+
+    # The body `/create-pr` would have written: a title line, a summary lifted
+    # from the specification, and a link back to the plan folder so a reviewer
+    # can find the rest.
+    #
+    # @return [String]
+    def description(subject, title)
+      <<~MARKDOWN
+        # #{title}
+
+        ## Summary
+
+        #{summary_text(subject)}
+
+        ## Plan
+
+        Implements `#{subject.feature.dirname}`. The specification and the plan
+        for this work live in that folder.
+      MARKDOWN
+    end
+
+    # The specification's own Goal section, verbatim. A pull request body that
+    # paraphrases the spec is a second copy that drifts; quoting it is not.
+    #
+    # @param subject [Agentilda::Subject]
+    # @return [String]
+    def summary_text(subject)
+      text = subject.goal.join("\n\n")
+      text.empty? ? "See `#{subject.feature.dirname}/spec.md`." : text
+    end
+
+    # @return [TTY::Command::Result]
+    def run(checkout, *argv) = @command.run(*argv, chdir: checkout.path)
+  end
+end

data/lib/agentilda/pull_request.rb

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