openlanes 3.0.0

data/lib/openlanes/lifecycle/unblocker.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Lifecycle
+    # Draining a plan's `blocked.md`, and saying what happened.
+    #
+    # `unblock` is the one command a human runs *because* they know something the
+    # tool cannot observe: an answer has arrived. So it owes them an account of
+    # what it did with it. Four things can happen to a plan named on the command
+    # line, and only one of them is the interesting one:
+    #
+    #   * the number names no folder,
+    #   * the folder is not blocked and there is nothing to drain,
+    #   * the folder is blocked, and some, none or all of its questions fold in,
+    #   * `blocked.md` is there but numbers nothing `## B<n>`, so no program can
+    #     read it at all.
+    #
+    # Each is reported differently, because each needs a different thing done
+    # next. This object works out which one happened; {CLI::Unblock} prints it.
+    class Unblocker
+      # One open question, as `blocked.md` writes it.
+      #
+      # @!attribute [r] number
+      #   @return [Integer] the `n` in `## B<n>`
+      # @!attribute [r] heading
+      #   @return [String] the heading text, hashes stripped
+      # @!attribute [r] answered
+      #   @return [Boolean] whether an `## A<n>` of the same number is waiting
+      Question = Data.define(:number, :heading, :answered) do
+        # @return [String]
+        def to_s = answered ? "#{heading}  ← answer waiting" : heading
+      end
+
+      # One token from the command line, once the tree has had a look at it.
+      #
+      # @!attribute [r] token
+      #   @return [String] what the user typed
+      # @!attribute [r] subject
+      #   @return [OpenLanes::Plans::Subject, nil]
+      # @!attribute [r] problem
+      #   @return [Symbol, nil] :missing, :not_blocked, or nil when it is drainable
+      Target = Data.define(:token, :subject, :problem) do
+        # @return [Boolean]
+        def drainable? = problem.nil?
+      end
+
+      # What became of one plan.
+      #
+      # @!attribute [r] subject
+      #   @return [OpenLanes::Plans::Subject] as the folder stands *now*
+      # @!attribute [r] ok
+      #   @return [Boolean] whether the agent ran without failing
+      # @!attribute [r] note
+      #   @return [String] one line about how it went
+      # @!attribute [r] before
+      #   @return [Array<Question>] open before the agent ran
+      # @!attribute [r] after
+      #   @return [Array<Question>] open now
+      Outcome = Data.define(:subject, :ok, :note, :before, :after) do
+        # @return [OpenLanes::Plans::Ordinal]
+        def ordinal = subject.feature.ordinal
+
+        # @return [Array<Integer>] the questions this run actually disposed of
+        def folded = before.map(&:number) - after.map(&:number)
+
+        # @return [Boolean] `blocked.md` is gone, so the plan is out of the block
+        def cleared? = !subject.file?("blocked.md")
+
+        # @return [Boolean] a `blocked.md` no program can read
+        def unreadable? = subject.unreadable_block?
+
+        # @return [Array<Question>] still open, with an answer sitting unfolded
+        def waiting = after.select(&:answered)
+      end
+
+      # The questions a folder still names, in the order the file names them.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<Question>]
+      def self.questions(subject)
+        answered = subject.block_answers
+
+        subject.read("blocked.md").to_s.lines.grep(Plans::OPEN_BLOCK).map do |line|
+          number = line[Plans::OPEN_BLOCK, 1].to_i
+          Question.new(number:, heading: line.strip.sub(/\A\#+[ \t]*/, ""), answered: answered.include?(number))
+        end
+      end
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param agent [OpenLanes::Agents::Agent]
+      # @param executor [#call] receives (agent, subject, root:) and yields each
+      #   phrase describing what the agent is doing
+      # @param root [String] the repository the agent works in
+      # @param commit [Boolean] false plans the invocation and changes nothing
+      def initialize(tree:, agent:, executor:, root: nil, commit: false)
+        @tree = tree
+        @agent = agent
+        @executor = executor
+        @root = root || File.dirname(tree.dir)
+        @commit = commit
+      end
+
+      # @return [OpenLanes::Plans::Tree]
+      attr_reader :tree
+
+      # @return [OpenLanes::Agents::Agent]
+      attr_reader :agent
+
+      # @return [String]
+      attr_reader :root
+
+      # @return [Boolean]
+      def applying? = @commit
+
+      # Work out what each number on the command line refers to.
+      #
+      # Nothing is rejected here and nothing exits: a token that names no folder
+      # is as much a thing the user needs told about as a folder that drained, and
+      # stopping at the first bad one hides the rest of the report.
+      #
+      # The gate is `blocked.md` itself, not the folder's emoji. ⭕️ is *derived*
+      # from the file, so gating on the emoji made the tool circular: a
+      # `blocked.md` whose questions are not numbered `## B<n>` never earns the
+      # emoji, so `unblock` refused it, so the file could never drain and the
+      # folder could never leave 🟡.
+      #
+      # @param tokens [Array<String>] `NNN`, `NNN.MM`, or several comma separated
+      # @return [Array<Target>]
+      def resolve(tokens)
+        tokens.flat_map { |token| token.to_s.split(",") }.map(&:strip).reject(&:empty?).map do |token|
+          subject = tree.find(token)
+          next Target.new(token:, subject: nil, problem: :missing) if subject.nil?
+          next Target.new(token:, subject:, problem: :not_blocked) unless subject.file?("blocked.md")
+
+          Target.new(token:, subject:, problem: nil)
+        end
+      end
+
+      # Hand each folder to the agent, one at a time, and read the file back.
+      #
+      # What the agent claims it did is not evidence. The questions are counted
+      # off disk before and after, so "folded B3" means the heading is gone from
+      # `blocked.md`, not that an agent said so.
+      #
+      # @param subjects [Array<OpenLanes::Plans::Subject>]
+      # @return [Array<Outcome>]
+      def call(subjects)
+        return [] if subjects.empty?
+
+        before = subjects.map { |subject| [subject.feature.ordinal.to_s, self.class.questions(subject)] }.to_h
+        results = UI.concurrently(subjects,
+          headline(subjects),
+          jobs:   1,
+          label:  method(:label),
+          fields: method(:log_fields)) do |subject, progress|
+          # After ctrl-c the plans not yet started stay as they are, blocked.md
+          # untouched, so the next run picks them up from the beginning.
+          next [false, "not started: interrupted by ctrl-c"] if Execution::Control.interrupted?
+
+          invoke(subject, progress)
+        end
+
+        settle
+        subjects.zip(results).map { |subject, result| outcome(subject, result, before) }
+      end
+
+      # One folder, with no spinner and no rename: what the run loop does when
+      # a person has answered every question a blocked plan asked (plan 004).
+      # The loop owns the screen, so nothing here draws on it, and the loop
+      # owns renames, so the folder's name is left to its next `resync dirs`,
+      # which sees `blocked.md` gone. Everything else is {#call}'s: the same
+      # agent, the same invocation, the same count of questions off disk.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @yieldparam progress [Object] whatever the executor reports
+      # @return [Outcome]
+      def drain(subject, &progress)
+        before = { subject.feature.ordinal.to_s => self.class.questions(subject) }
+        result = applying? ? invoke(subject, progress || proc {}) : [false, "not attempted: a dry run"]
+        tree.reload
+        outcome(subject, result, before)
+      end
+
+      private
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param progress [OpenLanes::UI::Line]
+      # @return [Array(Boolean, String)]
+      def invoke(subject, progress)
+        @executor.call(agent, subject, root:, &progress)
+      rescue StandardError => e
+        [false, "#{e.class}: #{e.message.lines.first.to_s.strip}"]
+      end
+
+      # The same pass the run loop makes after every round, for the same reason:
+      # a drained folder is only *named* differently once something reads the
+      # file the agent just deleted.
+      #
+      # @return [void]
+      def settle
+        Resync::Dirs.new(tree:).call(commit: true) if applying?
+        tree.reload
+      end
+
+      # @param subject [OpenLanes::Plans::Subject] as it was before the run
+      # @param result [Array, Exception]
+      # @param before [Hash{String => Array<Question>}]
+      # @return [Outcome]
+      def outcome(subject, result, before)
+        ok, note = result.is_a?(Exception) ? [false, result.message.lines.first.to_s.strip] : result
+        current = tree.find(subject.feature.ordinal) || subject
+
+        Outcome.new(subject: current,
+          ok: !!ok,
+          note: note.to_s,
+          before: before.fetch(subject.feature.ordinal.to_s, []),
+          after: self.class.questions(current))
+      end
+
+      # @param subjects [Array<OpenLanes::Plans::Subject>]
+      # @return [String]
+      def headline(subjects)
+        "#{applying? ? "handing" : "would hand"} #{subjects.size} plan#{"s" unless subjects.size == 1} " \
+          "to #{agent.name} in #{root}"
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def label(subject) = "#{subject.feature.ordinal} → #{agent.name}"
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Hash] the columns this plan's log lines carry
+      def log_fields(subject) = { plan: subject.feature.ordinal.to_s, status: subject.status.to_s, agent: agent.name }
+    end
+  end
+end

data/lib/openlanes/lifecycle.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # Operations that change which plans exist or what they are called:
+  # minting a folder, drafting its brief, adopting an orphan pull request,
+  # reconciling names with contents, and draining answered questions.
+  module Lifecycle
+    module_function
+
+    # @param dir [String] the `.plans` directory
+    # @param options [Hash] passed to {Creator#create}
+    # @return [Dry::Monads::Result] Success(path) or Failure(message)
+    def create(dir:, **) = Creator.new(dir:).create(**)
+
+    # @param tree [OpenLanes::Plans::Tree]
+    # @return [OpenLanes::Lifecycle::Resync::Dirs]
+    def resync_dirs(tree:, **) = Resync::Dirs.new(tree:, **)
+
+    # @return [OpenLanes::Lifecycle::Resync::Prs]
+    def resync_prs(**) = Resync::Prs.new(**)
+
+    # @return [OpenLanes::Lifecycle::Brief]
+    def brief(**) = Brief.new(**)
+
+    # @return [OpenLanes::Lifecycle::Unblocker]
+    def unblocker(**) = Unblocker.new(**)
+  end
+end

data/lib/openlanes/linear/api.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module OpenLanes
+  module Linear
+    # Linear's GraphQL API, wrapped as thinly as {OpenLanes::Vcs::GitHub} wraps
+    # `gh`, and for the same reason: it is a seam. Every example in the suite
+    # injects a transport here, so nothing in the tests reaches Linear.
+    #
+    # Only the dozen operations an import needs are here. This is not a client
+    # library, and it should not grow into one — anything Linear can do that
+    # `.plans` cannot express does not belong in a tool whose whole premise is
+    # that the folder is the source of truth.
+    class API
+      ENDPOINT = "https://api.linear.app/graphql"
+
+      # The environment variable holding a personal API key.
+      TOKEN_VARIABLE = "LINEAR_API_KEY"
+
+      # @return [String, nil] the token, from the environment
+      def self.token_from_env = ENV[TOKEN_VARIABLE].to_s.strip.then { |t| t.empty? ? nil : t }
+
+      # @param token [String] a Linear personal API key
+      # @param transport [#call, nil] `(query, variables) -> Hash`, for tests
+      # @param endpoint [String]
+      def initialize(token: nil, transport: nil, endpoint: ENDPOINT)
+        @token = token
+        @transport = transport
+        @endpoint = endpoint
+        return if transport || (token && !token.empty?)
+
+        raise Error,
+          "no Linear token. Set #{TOKEN_VARIABLE}, or use the MCP transport:\n  " \
+          "openlanes linear import <TEAM> -p <PROJECT> --format json"
+      end
+
+      # The team, its workflow states and its labels, in one round trip.
+      #
+      # @param key [String] the team key, e.g. "TAX"
+      # @return [Hash] `{id:, name:, key:, states: [...], labels: [...]}`
+      # @raise [OpenLanes::Error] when no team wears that key
+      def team(key)
+        node = query(TEAM, key: key.to_s.upcase).dig("teams", "nodes")&.first
+        raise Error, "no Linear team has the key #{key.to_s.upcase}" unless node
+
+        { id: node["id"], name: node["name"], key: node["key"],
+         states: node.dig("states", "nodes").to_a, labels: node.dig("labels", "nodes").to_a }
+      end
+
+      # @param team_id [String]
+      # @return [Array<Hash>] `{id:, name:, url:}`
+      def projects(team_id) = query(PROJECTS, teamId: team_id).dig("team", "projects", "nodes").to_a
+
+      # @param input [Hash] `{name:, teamIds:, content:, icon:}`
+      # @return [Hash] `{id:, name:, url:}`
+      def create_project(input) = unwrap(query(PROJECT_CREATE, input:), "projectCreate", "project")
+
+      # @param id [String]
+      # @param input [Hash]
+      # @return [Hash]
+      def update_project(id, input) = unwrap(query(PROJECT_UPDATE, id:, input:), "projectUpdate", "project")
+
+      # @param input [Hash] `{teamId:, projectId:, title:, description:, stateId:, labelIds:}`
+      # @return [Hash] `{id:, identifier:, url:}`
+      def create_issue(input) = unwrap(query(ISSUE_CREATE, input:), "issueCreate", "issue")
+
+      # @param id [String] a UUID or an identifier such as "TAX-41"
+      # @param input [Hash]
+      # @return [Hash]
+      def update_issue(id, input) = unwrap(query(ISSUE_UPDATE, id:, input:), "issueUpdate", "issue")
+
+      # @param name [String]
+      # @param team_id [String]
+      # @return [Hash] `{id:, name:}`
+      def create_label(name, team_id)
+        unwrap(query(LABEL_CREATE, input: { name:, teamId: team_id }), "issueLabelCreate", "issueLabel")
+      end
+
+      # @param issue_id [String]
+      # @param url [String]
+      # @param title [String]
+      # @return [void]
+      def link(issue_id:, url:, title:)
+        query(ATTACHMENT_CREATE, input: { issueId: issue_id, url:, title: })
+      end
+
+      # @param query [String] a GraphQL document
+      # @param variables [Hash]
+      # @return [Hash] the `data` object
+      # @raise [OpenLanes::Error] on a transport or GraphQL error
+      def query(query, **variables)
+        body = transport.call(query, variables)
+        errors = body["errors"]
+        raise Error, "Linear rejected the request: #{describe(errors)}" if errors&.any?
+
+        body.fetch("data") { raise Error, "Linear returned no data" }
+      end
+
+      private
+
+      # @return [String, nil]
+      attr_reader :token
+
+      # @return [String]
+      attr_reader :endpoint
+
+      # @return [#call]
+      def transport = @transport ||= method(:post)
+
+      # Linear reports a failed mutation as `success: false` rather than as an
+      # error, so the envelope has to be checked as well as the errors array.
+      #
+      # @param data [Hash]
+      # @param mutation [String]
+      # @param field [String]
+      # @return [Hash]
+      def unwrap(data, mutation, field)
+        payload = data[mutation] or raise Error, "Linear returned no #{mutation} payload"
+        raise Error, "Linear declined the #{mutation}" unless payload["success"]
+
+        payload.fetch(field)
+      end
+
+      # @param errors [Array<Hash>]
+      # @return [String]
+      def describe(errors)
+        Array(errors).map { |e| e["message"] || e.to_s }.join("; ")
+      end
+
+      # @param document [String]
+      # @param variables [Hash]
+      # @return [Hash] the parsed response body
+      def post(document, variables)
+        uri = URI(endpoint)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = token
+        request.body = JSON.generate(query: document, variables:)
+
+        response = Net::HTTP.start(uri.hostname,
+          uri.port,
+          use_ssl:      uri.scheme == "https",
+          open_timeout: 10,
+          read_timeout: 30) { |http| http.request(request) }
+
+        parse(response)
+      rescue JSON::ParserError, IOError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise Error, "could not reach Linear at #{endpoint}: #{e.message}"
+      end
+
+      # @param response [Net::HTTPResponse]
+      # @return [Hash]
+      def parse(response)
+        return JSON.parse(response.body.to_s) if response.is_a?(Net::HTTPSuccess)
+
+        hint = if ["400", "401"].include?(response.code)
+                 "\n\nCheck #{TOKEN_VARIABLE}. A personal API key is sent verbatim, without a `Bearer` prefix."
+               end
+        raise Error, "Linear returned HTTP #{response.code}#{hint}"
+      end
+
+      TEAM = <<~GRAPHQL
+        query Team($key: String!) {
+          teams(filter: { key: { eq: $key } }, first: 1) {
+            nodes {
+              id name key
+              states(first: 100) { nodes { id name type position } }
+              labels(first: 250) { nodes { id name } }
+            }
+          }
+        }
+      GRAPHQL
+
+      PROJECTS = <<~GRAPHQL
+        query Projects($teamId: String!) {
+          team(id: $teamId) {
+            projects(first: 250) {
+              nodes { id name url description content status { name type } }
+            }
+          }
+        }
+      GRAPHQL
+
+      PROJECT_CREATE = <<~GRAPHQL
+        mutation CreateProject($input: ProjectCreateInput!) {
+          projectCreate(input: $input) { success project { id name url } }
+        }
+      GRAPHQL
+
+      PROJECT_UPDATE = <<~GRAPHQL
+        mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
+          projectUpdate(id: $id, input: $input) { success project { id name url } }
+        }
+      GRAPHQL
+
+      ISSUE_CREATE = <<~GRAPHQL
+        mutation CreateIssue($input: IssueCreateInput!) {
+          issueCreate(input: $input) { success issue { id identifier url } }
+        }
+      GRAPHQL
+
+      ISSUE_UPDATE = <<~GRAPHQL
+        mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
+          issueUpdate(id: $id, input: $input) { success issue { id identifier url } }
+        }
+      GRAPHQL
+
+      LABEL_CREATE = <<~GRAPHQL
+        mutation CreateLabel($input: IssueLabelCreateInput!) {
+          issueLabelCreate(input: $input) { success issueLabel { id name } }
+        }
+      GRAPHQL
+
+      ATTACHMENT_CREATE = <<~GRAPHQL
+        mutation CreateAttachment($input: AttachmentCreateInput!) {
+          attachmentCreate(input: $input) { success attachment { id } }
+        }
+      GRAPHQL
+    end
+  end
+end

data/lib/openlanes/linear/attribution.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Linear
+    # Which plan a pull request belongs to, when its title does not say.
+    #
+    # `resync prs` puts an `[NNN.MM]` on every title it can resolve, and most
+    # of them resolve. What is left is the tail: work that shipped before the
+    # convention existed, or from a branch named after nothing in particular.
+    # Those pull requests are real work with no home, and dropping them means
+    # the issues that stand for a plan are missing pieces of it.
+    #
+    # The rule is word overlap between the pull request's title and the
+    # folder's name. It works here, where it did not work for matching plans
+    # to projects, because the candidates are different: a folder slug is
+    # `ledger-carryforward-vintages`, three specific words about one thing,
+    # and there are twenty of them to choose between. A project is called
+    # "US Tax Law: Self Contained Ruby Gem" and there are four.
+    #
+    # It is still a guess, and it says so. A tie is refused rather than broken,
+    # because two folders matching equally well is evidence that neither is
+    # right rather than a reason to pick the first.
+    class Attribution
+      # One pull request, placed.
+      #
+      # @!attribute [r] pull
+      #   @return [OpenLanes::Plans::PullRequest]
+      # @!attribute [r] subject
+      #   @return [OpenLanes::Plans::Subject, nil] nil when nothing matched
+      # @!attribute [r] score
+      #   @return [Integer] words the title and the folder name shared
+      # @!attribute [r] rivals
+      #   @return [Array<String>] folders that matched equally well
+      Placed = Data.define(:pull, :subject, :score, :rivals, :widened) do
+        # @return [Boolean]
+        def placed? = !subject.nil?
+
+        # @return [String]
+        def percent = "#{(score * 100).round}%"
+
+        # @return [String] where the matching words came from
+        def source = widened ? "title and description" : "title"
+
+        # @return [String]
+        def why
+          return "matched no folder at all" if subject.nil? && score.zero?
+          return "#{percent} of a folder name is not enough" if subject.nil? && rivals.empty?
+          # `rivals` already holds every tied folder — there is no winner to
+          # add back in, and `+ 1` here once reported a two-way tie as three.
+          return "#{rivals.size} folders matched equally well (#{percent})" if subject.nil?
+
+          "#{source}: covers #{percent} of the folder name"
+        end
+      end
+
+      # Words too common in this domain to carry a match on their own. Every
+      # plan in a tax engine says "tax"; a pull request that says it too has
+      # told you nothing.
+      # How much of a folder's name a title must cover to claim it.
+      FLOOR = 0.5
+
+      # And how much a description must cover, which is more.
+      #
+      # A title is written to say what the change is. A description is written
+      # to get the change reviewed, and it opens with whatever this repository
+      # puts at the top of every one of them — a stacking note, a diff
+      # summary, a checklist. Read at the same bar as a title it produced two
+      # placements here and both were wrong, one of them on the word
+      # "documents" inside "diff includes nineteen documents".
+      WIDER_FLOOR = 0.75
+
+      # Words, not just a fraction. Half of a two-word folder name is one
+      # word, which is the case that was already established as too thin —
+      # "core" alone claiming `deterministic-core-and-as-of`.
+      MINIMUM_WORDS = 3
+
+      NOISE = %w[the and for with from into that this add adds added fix fixes
+                 update updates use uses spec plan pull request pr tax app web api].freeze
+
+      # @param tree [OpenLanes::Plans::Tree]
+      def initialize(tree:)
+        @tree = tree
+      end
+
+      # How much of a pull request's description to read when its title was
+      # not enough. The opening sentence or two of a description says what the
+      # change is for; further down it turns into checklists, test plans and
+      # generated tables, which are the same words on every pull request in
+      # the repository and match everything equally.
+      OPENING_WORDS = 20
+
+      # @param pulls [Array<OpenLanes::Plans::PullRequest>] the ones with no number
+      # @param bodies [Hash{String => String}] descriptions, by pull request number
+      # @return [Array<OpenLanes::Linear::Attribution::Placed>]
+      def call(pulls, bodies: {})
+        pulls.map do |pull|
+          found = place(pull, words(pull.title))
+          next found if found.placed?
+
+          # Second pass. A title is a headline and sometimes says nothing
+          # useful — "Add the Drake reference-return worklist" names a vendor
+          # rather than the work. The description usually opens by saying what
+          # the change is actually about.
+          opening = opening_words(bodies[pull.number.to_s])
+          next found if opening.empty?
+
+          wider = place(pull, words(pull.title) | opening, floor: WIDER_FLOOR)
+          wider.placed? ? wider.with(widened: true) : found
+        end
+      end
+
+      # @param body [String, nil]
+      # @return [Array<String>]
+      def opening_words(body)
+        text = body.to_s
+                   .gsub(/<!--.*?-->/m, "")
+                   .gsub(/```.*?```/m, "")
+                   .gsub(/^\s*[-*|#>]+/, " ")
+        words(text.split(/\s+/).first(OPENING_WORDS * 3).join(" ")).first(OPENING_WORDS)
+      end
+
+      private
+
+      # @return [OpenLanes::Plans::Tree]
+      attr_reader :tree
+
+      # @param pull [OpenLanes::Plans::PullRequest]
+      # @param wanted [Array<String>] the words to match on
+      # @param floor [Float] how much of a folder name is enough
+      # @return [OpenLanes::Linear::Attribution::Placed]
+      def place(pull, wanted, floor: FLOOR)
+        return Placed.new(pull:, subject: nil, score: 0.0, rivals: [], widened: false) if wanted.empty?
+
+        ranked = tree.subjects.filter_map { |s|
+          overlap = shared(folder_words(s), wanted)
+          [s, overlap] if overlap.positive?
+        }.sort_by { |_, overlap| -overlap }
+
+        best, score = ranked.first
+
+        # One word in common is not evidence. "Add year-keyed tax rules" shares
+        # "rules" with `rules-retirement-and-engine-convergence` and has
+        # nothing to do with it.
+        enough = best && score >= floor && (score * folder_words(best).size).round >= MINIMUM_WORDS
+        return Placed.new(pull:, subject: nil, score: score.to_f, rivals: [], widened: false) unless enough
+
+        tied = ranked.select { |_, overlap| overlap == score }
+        return Placed.new(pull:, subject: best, score:, rivals: [], widened: false) if tied.one?
+
+        Placed.new(pull:, subject: nil, score:, rivals: tied.map { |s, _| s.feature.dirname }, widened: false)
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<String>]
+      def folder_words(subject)
+        (@folder_words ||= {})[subject.feature.path] ||=
+          words(subject.feature.slug.tr("-", " ")) | words(subject.feature.title)
+      end
+
+      # @param text [String]
+      # @return [Array<String>]
+      def words(text)
+        text.to_s.downcase.gsub(/[^a-z0-9]+/, " ").split
+            .reject { |w| w.length < 4 || NOISE.include?(w) }.uniq
+      end
+
+      # How much of a folder's name a pull request title actually said.
+      #
+      # A pull request said `signed_off` where its folder says `sign-off`, and
+      # `vintages` where the folder says `vintage`. Compared literally those
+      # are strangers, and the first cost a placement a human makes instantly
+      # — one a later, numbered pull request went on to prove correct.
+      #
+      # Matching on a shared prefix rather than by stripping suffixes, because
+      # stripping is destructive and gets it wrong in both directions:
+      # `corpus` is not a plural, and turning it into `corpu` reads as a typo
+      # in every diagnostic that prints it.
+      #
+      # @param folder [Array<String>]
+      # @param title [Array<String>]
+      # @return [Float] 0.0 to 1.0
+      def shared(folder, title) = Fuzzy.coverage(folder, title)
+    end
+  end
+end