openlanes 3.0.0

data/lib/openlanes/linear/fuzzy.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fuzzystringmatch"
+
+module OpenLanes
+  module Linear
+    # How alike two short strings are, on a scale rather than a yes or no.
+    #
+    # Counting shared words gives whole numbers, and whole numbers tie. Three
+    # folders scoring 2 against the same pull request is not three good
+    # answers — it is no answer — but a tie has to be *detected* to be
+    # refused, and with a coarse enough score everything ties.
+    #
+    # Jaro-Winkler grades instead, and it is the right measure for these
+    # inputs: it is built for short strings, and its prefix bonus is exactly
+    # the shape of the errors here — a word and its inflection agree from the
+    # front and diverge at the end.
+    module Fuzzy
+      module_function
+
+      # Two words count as the same word above this.
+      #
+      # Calibrated rather than chosen. The prefix bonus that makes
+      # `rounding`/`round` (0.938) work also lifts `plaid`/`plain` (0.920) and
+      # `state`/`statement` (0.926), which are different words that would
+      # wrongly file a pull request. 0.93 is the gap between those two groups.
+      # It costs `corpus`/`corpora` (0.848), which is rarer than either.
+      AKIN = 0.93
+
+      # Deliberately the pure-Ruby implementation. The native one needs a C
+      # extension that does not build everywhere — it fails on this machine
+      # over a jemalloc header — and asking for it prints a compile warning to
+      # STDERR on every single load, which would land in the middle of every
+      # command's output. An import compares a few hundred short strings; that
+      # is nowhere near enough work to be worth a build step.
+      #
+      # @return [FuzzyStringMatch::JaroWinklerPure]
+      def matcher = @matcher ||= FuzzyStringMatch::JaroWinkler.create(:pure)
+
+      # @param one [String]
+      # @param other [String]
+      # @return [Float] 0.0 to 1.0
+      def similarity(one, other) = matcher.getDistance(one.to_s.downcase, other.to_s.downcase)
+
+      # @param one [String]
+      # @param other [String]
+      # @return [Boolean] whether these are the same word, inflections aside
+      def akin?(one, other) = similarity(one, other) >= AKIN
+
+      # What fraction of `wanted` has a counterpart in `found`.
+      #
+      # Asymmetric on purpose. A folder is named for what it is about, in two
+      # or three words; a pull request title is a sentence. Asking how much of
+      # the sentence the folder covers would punish every long title, so the
+      # question is the other way round: how much of this folder's name did
+      # the title actually say?
+      #
+      # @param wanted [Array<String>] the folder's words
+      # @param found [Array<String>] the title's words
+      # @return [Float] 0.0 to 1.0
+      def coverage(wanted, found)
+        return 0.0 if wanted.empty?
+
+        wanted.count { |word| found.any? { |other| akin?(word, other) } }.fdiv(wanted.size)
+      end
+    end
+  end
+end

data/lib/openlanes/linear/import.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Linear
+    # One thing that would happen in Linear.
+    #
+    # `args` is deliberately shaped as the Linear MCP server's `save_issue`
+    # arguments, because that server addresses everything by
+    # the names a human already knows — a team by its key, a project by its
+    # name, a workflow state by its name, an issue by its identifier. Emitting
+    # exactly that shape means the JSON this produces can drive either
+    # transport unchanged: {Push} turns it into GraphQL, and the skill hands
+    # it to the MCP tools as-is. One contract, so the two cannot drift.
+    #
+    # @!attribute [r] kind
+    #   @return [Symbol] `:issue` for a plan, `:subissue` for a unit of one
+    # @!attribute [r] op
+    #   @return [Symbol] `:create`, `:update` or `:skip`
+    # @!attribute [r] ordinal
+    #   @return [String] the plan this belongs to, e.g. "003.00"
+    # @!attribute [r] unit
+    #   @return [String, nil] the {Unit#key}, nil for a plan's own issue
+    # @!attribute [r] identifier
+    #   @return [String, nil] what Linear already calls it, when it exists
+    # @!attribute [r] title
+    #   @return [String] for the human reading the dry run
+    # @!attribute [r] digest
+    #   @return [String] fingerprint of `args`, recorded after a push
+    # @!attribute [r] args
+    #   @return [Hash] the MCP argument shape
+    # @!attribute [r] reason
+    #   @return [String] why this operation and not another
+    Action = Data.define(:kind, :op, :ordinal, :unit, :identifier, :title, :digest, :args, :reason) do
+      # @return [Boolean] whether this would change anything
+      def pending? = op != :skip
+
+      # @return [Boolean] whether this issue hangs off another
+      def child? = kind == :subissue
+
+      # @return [Hash] for `--format json`
+      def to_h_json
+        { kind:, op:, plan: ordinal, unit:, identifier:, title:, digest:, args: }.compact
+      end
+    end
+
+    # What a plan folder would become in Linear, and what has already become
+    # of it. Reads the filesystem; touches nothing else.
+    #
+    # One folder is one issue, and the units inside its `plan.md` are that
+    # issue's children. Projects are never created: a team's project list is
+    # something a human curated, and every plan is filed under one the caller
+    # named on the command line.
+    #
+    # Keeping the whole decision offline is what makes `--dry-run` honest. The
+    # dry run is not an approximation of what a push would do — it is the same
+    # object the push consumes, so what gets printed and what gets sent cannot
+    # disagree. Everything that needs the network — the project, the repository
+    # pull request list — is handed in.
+    class Import
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param team [String] the team key, e.g. "TAX"
+      # @param project [Hash] the Linear project, `{"id", "name", "url"}`
+      # @param adopted [Hash{String => Array<OpenLanes::Plans::PullRequest>}]
+      #   pull requests {Attribution} placed, by folder name
+      # @param since [String, nil] skip plans numbered below this
+      # @param statuses [Array<Symbol>, nil] only these states
+      # @param update_unchanged [Boolean] update everything, matching digest or not
+      def initialize(tree:, team:, project:, adopted: {}, since: nil, statuses: nil, update_unchanged: false)
+        @tree = tree
+        @team = team.to_s.strip.upcase
+        @project = project
+        @adopted = adopted
+        @since = since && Plans::Ordinal.parse(since)
+        @statuses = statuses
+        @update_unchanged = update_unchanged
+      end
+
+      # @return [String] the team key
+      attr_reader :team
+
+      # @return [Hash] the project everything is filed under
+      attr_reader :project
+
+      # @return [String]
+      def project_name = project["name"].to_s
+
+      # @return [Array<OpenLanes::Linear::Action>] each plan's issue,
+      #   followed by that issue's children
+      def actions = @actions ||= subjects.flat_map { |s| actions_for(s) }
+
+      # @return [Array<OpenLanes::Linear::Action>]
+      def pending = actions.select(&:pending?)
+
+      # @return [String] the whole import, for a pipe
+      def to_json(*_args)
+        JSON.pretty_generate(team:, project: project_name, actions: actions.map(&:to_h_json))
+      end
+
+      # Plans in a state nobody has decided how to file, and why not.
+      #
+      # @return [Hash{OpenLanes::Plans::Status => Array<String>}] state => ordinals
+      def unplaced
+        @unplaced ||= (chosen - subjects).group_by(&:status)
+                                         .transform_values { |group| group.map { |s| s.feature.ordinal.to_s } }
+      end
+
+      private
+
+      # @return [OpenLanes::Plans::Tree]
+      attr_reader :tree
+
+      # @return [Hash]
+      attr_reader :adopted
+
+      # @return [OpenLanes::Plans::Ordinal, nil]
+      attr_reader :since
+
+      # @return [Array<Symbol>, nil]
+      attr_reader :statuses
+
+      # @return [Boolean]
+      attr_reader :update_unchanged
+
+      # @return [Array<OpenLanes::Plans::Subject>]
+      def subjects = @subjects ||= chosen.select { |s| OpenLanes::Linear.placement(s.status) }
+
+      # @return [Array<OpenLanes::Plans::Subject>] before the placement question
+      def chosen
+        @chosen ||= tree.subjects.select { |s|
+          (since.nil? || s.feature.ordinal >= since) &&
+            (statuses.nil? || statuses.include?(s.status.key))
+        }
+      end
+
+      # The units a plan's issue will have children for: the ones its
+      # `plan.md` declares, plus any pull request {Attribution} placed here
+      # that none of them already claims.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<OpenLanes::Linear::Unit>]
+      def units_for(subject)
+        (@units ||= {})[subject.feature.path] ||= begin
+          declared = Units.new(subject:).all
+          claimed = declared.flat_map(&:pull_requests).map(&:number)
+          extra = adopted.fetch(subject.feature.dirname, []).reject { |pr| claimed.include?(pr.number) }
+          declared + extra.map { |pr| adopted_unit(pr) }
+        end
+      end
+
+      # @param pull [OpenLanes::Plans::PullRequest]
+      # @return [OpenLanes::Linear::Unit]
+      def adopted_unit(pull)
+        Unit.new(key: "##{pull.number}",
+          title: Units.clean_title(pull.title),
+          body: "",
+          pull_requests: [pull])
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [OpenLanes::Linear::Issues]
+      def record_for(subject) = (@records ||= {})[subject.feature.path] ||= Issues.new(dir: subject.feature.path)
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Array<OpenLanes::Linear::Action>]
+      def actions_for(subject)
+        [plan_action(subject)] + units_for(subject).map { |unit| unit_action(subject, unit) }
+      end
+
+      # The issue that stands for the whole plan folder.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [OpenLanes::Linear::Action]
+      def plan_action(subject)
+        placement = OpenLanes::Linear.placement(subject.status)
+        recorded = record_for(subject).by_unit[Issues::PARENT]
+        title = plan_title(subject)
+
+        args = { team:, project: project_name, title:, description: plan_description(subject),
+                state: placement.name, labels: placement.labels }
+        digest = Issues.digest(args)
+
+        op, reason = decide(recorded&.identifier, recorded&.digest, digest)
+        args = args.merge(id: recorded.identifier).except(:team, :project) if op == :update && recorded
+
+        Action.new(kind: :issue,
+          op:,
+          ordinal: subject.feature.ordinal.to_s,
+          unit: Issues::PARENT,
+          identifier: recorded&.identifier,
+          title:,
+          digest:,
+          args:,
+          reason:)
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param unit [OpenLanes::Linear::Unit]
+      # @return [OpenLanes::Linear::Action]
+      def unit_action(subject, unit)
+        placement = OpenLanes::Linear.placement_for(subject.status, unit.pull_requests)
+        recorded = record_for(subject).by_unit[unit.key]
+        parent = record_for(subject).by_unit[Issues::PARENT]
+
+        args = { team:, project: project_name, title: unit.title,
+                description: unit_description(subject, unit),
+                state: placement.name, labels: placement.labels, links: links_for(unit) }
+        args = args.merge(parentId: parent.identifier) if parent
+        digest = Issues.digest(args.except(:parentId))
+
+        op, reason = decide(recorded&.identifier, recorded&.digest, digest)
+        args = args.merge(id: recorded.identifier).except(:team, :project) if op == :update && recorded
+
+        Action.new(kind: :subissue,
+          op:,
+          ordinal: subject.feature.ordinal.to_s,
+          unit: unit.key,
+          identifier: recorded&.identifier,
+          title: unit.title,
+          digest:,
+          args:,
+          reason:)
+      end
+
+      # The three-way decision, in one place so a plan and a unit cannot
+      # answer it differently.
+      #
+      # @param existing [String, nil] what Linear already calls it
+      # @param was [String, nil] the digest recorded at the last push
+      # @param now [String] the digest of what we would push
+      # @return [Array(Symbol, String)] the operation and its reason
+      def decide(existing, was, now)
+        return [:create, "not recorded in #{Issues::FILENAME}"] if existing.nil?
+        return [:update, "--update-unchanged"] if update_unchanged
+        return [:skip, "unchanged since the last import"] if was == now
+
+        [:update, "the plan has changed since #{existing} was pushed"]
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def plan_title(subject) = "[#{subject.feature.ordinal}] #{heading(subject)}"
+
+      # The specification's own H1 when it has one, because an agent writing
+      # `spec.md` gives it a real sentence — "Tenancy: users, households,
+      # memberships" — while the folder slug can only carry kebab-case.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def heading(subject)
+        line = subject.read("spec.md").to_s[/^[ \t]{0,3}#[ \t]+(.+)$/, 1]
+        cleaned = line.to_s.sub(/\A(?:spec(?:ification)?\s*)?\d+(?:\.\d+)?\s*[—–:.-]\s*/i, "").strip
+        cleaned.empty? ? subject.feature.title : cleaned
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def plan_description(subject)
+        [
+          subject.goal.join("\n\n"),
+          "**State**: #{subject.status} — #{subject.status.note}",
+          "**Folder**: `#{OpenLanes::PLANS_DIR}/#{subject.feature.dirname}`",
+          provenance
+        ].compact.reject(&:empty?).join("\n\n")
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param unit [OpenLanes::Linear::Unit]
+      # @return [String]
+      def unit_description(subject, unit)
+        [
+          truncate(unit.body),
+          "**Plan**: `#{OpenLanes::PLANS_DIR}/#{subject.feature.dirname}` · unit `#{unit.key}`",
+          provenance
+        ].compact.reject(&:empty?).join("\n\n")
+      end
+
+      # A pull request is attached to its issue, not listed in its body.
+      #
+      # Linear has a first-class relationship for this and renders it as what
+      # it is — an artifact implementing the work, carrying its own state. A
+      # markdown bullet is a claim about a relationship; an attachment is the
+      # relationship. Links are keyed on the URL, so re-sending one updates
+      # rather than duplicates.
+      #
+      # @param unit [OpenLanes::Linear::Unit]
+      # @return [Array<Hash>]
+      def links_for(unit)
+        unit.pull_requests.select(&:url).map { |pr| { url: pr.url, title: pr.label } }
+      end
+
+      # A plan section can run to several hundred lines of design notes and
+      # DDL. Linear is where the work is tracked, not where it is specified,
+      # and the folder is one click away.
+      #
+      # @param body [String]
+      # @param limit [Integer]
+      # @return [String]
+      def truncate(body, limit = 6_000)
+        text = body.to_s.strip
+        return text if text.length <= limit
+
+        "#{text[0, limit].rpartition("\n").first.rstrip}\n\n_…truncated; the plan folder has the rest._"
+      end
+
+      # @return [String]
+      def provenance
+        "_Imported by `openlanes linear import`. The plan folder is the source of truth; " \
+          "edits made here do not travel back._"
+      end
+    end
+  end
+end

data/lib/openlanes/linear/issue.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module OpenLanes
+  module Linear
+    # One row of a plan's `linear.md`: an issue this tool has already pushed.
+    #
+    # @!attribute [r] unit
+    #   @return [String] the {Unit#key} it was made from
+    # @!attribute [r] identifier
+    #   @return [String] "TAX-41" — Linear resolves this as an id
+    # @!attribute [r] url
+    #   @return [String, nil]
+    # @!attribute [r] title
+    #   @return [String] as pushed
+    # @!attribute [r] state
+    #   @return [String] as pushed
+    # @!attribute [r] digest
+    #   @return [String] fingerprint of the payload as pushed
+    Issue = Data.define(:unit, :identifier, :url, :title, :state, :digest)
+
+    # A plan's record of what it has put into Linear.
+    #
+    # Without it, a second `linear import` cannot tell an issue it created
+    # last week from one it has never created, and the only two outcomes are
+    # duplicating everything or searching Linear by title on every run. The
+    # file is the memory, and it is a committed artifact rather than a dotfile
+    # so the record travels with the plan and shows up in review.
+    #
+    # The `Synced` column is what makes an update cheap to decide: it is a
+    # digest of the payload last pushed, so a run can tell — with no network
+    # at all — whether anything about this issue has changed since. A digest
+    # that no longer matches is the whole trigger for an update.
+    class Issues
+      # The file this reads and writes.
+      FILENAME = "linear.md"
+
+      # The unit key given to the issue that stands for the whole folder. Its
+      # children carry their own unit keys; it carries this, so one table can
+      # hold a plan and its parts without a second shape to parse.
+      PARENT = "PLAN"
+
+      # Fingerprint of a payload, short enough to read in a table.
+      #
+      # @param payload [Object] anything with a stable #inspect ordering
+      # @return [String] eight hex characters
+      def self.digest(payload) = ::Digest::SHA256.hexdigest(JSON.generate(payload))[0, 8]
+
+      # @param team [String] the team key, e.g. "TAX"
+      # @param project [Hash, nil] `{name:, url:}`
+      # @param issues [Array<OpenLanes::Linear::Issue>]
+      # @return [String]
+      def self.render(team:, project:, issues:)
+        rows = order(issues).map { |i|
+          "| #{i.unit} | #{link(i.identifier, i.url)} | #{escape(i.title)} | #{i.state} | #{i.digest} |"
+        }
+
+        <<~MARKDOWN
+          # Linear
+
+          #{heading(team, project)}
+
+          | Unit | Issue | Title | State | Synced |
+          | :--- | :---- | :---- | ----: | :----- |
+          #{rows.join("\n")}
+
+          <!-- Written by `openlanes linear import`. Do not hand-edit the
+               Synced column: it fingerprints what was last pushed, and a row whose
+               fingerprint no longer matches the plan is what triggers an update. -->
+        MARKDOWN
+      end
+
+      # The folder's own issue first, then its children. A table that opens
+      # with a child reads as a list of unrelated issues.
+      #
+      # @param issues [Array<OpenLanes::Linear::Issue>]
+      # @return [Array<OpenLanes::Linear::Issue>]
+      def self.order(issues)
+        parent, children = issues.partition { |i| i.unit == PARENT }
+        parent + children
+      end
+
+      # @param team [String]
+      # @param project [Hash, nil]
+      # @return [String]
+      def self.heading(team, project)
+        return "Team **#{team}**." unless project
+
+        "Team **#{team}** · project #{link(project[:name], project[:url])}"
+      end
+
+      # @param text [String]
+      # @param url [String, nil]
+      # @return [String]
+      def self.link(text, url) = url ? "[#{escape(text)}](#{url})" : escape(text)
+
+      # @param text [String]
+      # @return [String]
+      def self.escape(text) = text.to_s.gsub("|", "\\|").gsub(/\s+/, " ").strip
+
+      # @param dir [String] absolute path to the plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [Array<OpenLanes::Linear::Issue>] possibly empty
+      def all = @all ||= parse
+
+      # @return [Hash{String => OpenLanes::Linear::Issue}] keyed by unit
+      def by_unit = @by_unit ||= all.to_h { |issue| [issue.unit, issue] }
+
+      # The project this plan was last filed under, if any.
+      #
+      # @return [Hash, nil] `{name:, url:}`
+      def project = (@project ||= [parse_project])[0]
+
+      # The issue standing for the folder itself.
+      #
+      # @return [OpenLanes::Linear::Issue, nil]
+      def parent = by_unit[PARENT]
+
+      # @return [String] absolute path to `linear.md`
+      def path = File.join(dir, FILENAME)
+
+      # @return [Boolean]
+      def exist? = File.file?(path)
+
+      # @param team [String]
+      # @param project [Hash, nil]
+      # @param issues [Array<OpenLanes::Linear::Issue>]
+      # @return [String] the path written
+      def write(team:, project:, issues:)
+        File.write(path, self.class.render(team:, project:, issues:))
+        @all = @by_unit = @project = nil
+        path
+      end
+
+      private
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [String]
+      def text = @text ||= exist? ? File.read(path, encoding: "UTF-8") : ""
+
+      # @return [Array<OpenLanes::Linear::Issue>]
+      def parse
+        table = Markdown.tables(text).find { |t|
+          t[:header].any? { |h| h.match?(/\Aissue\z/i) } && t[:header].any? { |h| h.match?(/\Aunit\z/i) }
+        }
+        return [] unless table
+
+        index = table[:header].each_with_index.to_h { |h, i| [h.downcase.strip, i] }
+        table[:rows].filter_map { |cells| row_to_issue(cells, index) }
+      end
+
+      # @param cells [Array<String>]
+      # @param index [Hash{String => Integer}]
+      # @return [OpenLanes::Linear::Issue, nil]
+      def row_to_issue(cells, index)
+        cell = ->(name) { cells[index[name]].to_s }
+        link = cell["issue"].match(/\[([^\]]+)\]\((\S+?)\)/)
+        identifier = (link ? link[1] : cell["issue"]).gsub(/[*_`]/, "").strip
+        return nil if identifier.empty?
+
+        Issue.new(unit: cell["unit"].strip,
+          identifier:,
+          url: link && link[2],
+          title: cell["title"].gsub(/\\([|\\])/, '\1').strip,
+          state: cell["state"].strip,
+          digest: cell["synced"].gsub(/[`\s]/, ""))
+      end
+
+      # @return [Hash, nil]
+      def parse_project
+        line = text.lines.find { |l| l.match?(/project\s+\[/i) }
+        return nil unless line
+
+        link = line.match(/project\s+\[([^\]]+)\]\((\S+?)\)/i)
+        return nil unless link
+
+        { name: link[1].strip.gsub(/\\([|\\])/, '\1'), url: link[2] }
+      end
+    end
+  end
+end

data/lib/openlanes/linear/mapping.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Linear
+    # What a folder's state means to Linear.
+    #
+    # Linear gives every workflow state a *type* — one of five, fixed across
+    # every workspace — and a *name*, which each team chooses for itself. A
+    # team may call its started state "In Progress", "Doing" or "🚧 WIP", so
+    # matching on the name alone works right up until it meets somebody else's
+    # workspace. Each row here therefore carries both: the type, which is the
+    # contract, and the name we would prefer if the team happens to have one.
+    # {Push} resolves the name first and falls back to the type.
+    #
+    # Several states have no Linear equivalent at all — ⭕️ Technical Block is
+    # a reason, not a position in a workflow — so they map to the nearest
+    # position and carry a label saying which reason.
+    #
+    # Two states are left out entirely; see {UNPLACED}.
+    #
+    # @!attribute [r] type
+    #   @return [String] Linear's canonical type: backlog, unstarted, started,
+    #     completed or canceled
+    # @!attribute [r] name
+    #   @return [String] the state name to prefer when the team has one
+    # @!attribute [r] labels
+    #   @return [Array<String>] labels that carry what the type cannot
+    Placement = Data.define(:type, :name, :labels)
+
+    # Linear's five workflow state types, in lifecycle order.
+    TYPES = %w[backlog unstarted started completed canceled].freeze
+
+    # Every plan state this tool is willing to place, keyed by
+    # {OpenLanes::Plans::Status#key}.
+    #
+    # Between this and {UNPLACED} every entry in {OpenLanes::Plans::STATUSES} is
+    # named exactly once, and a spec asserts it. That is the guard against the
+    # failure this file is most prone to: a sixteenth state gets added,
+    # nothing here changes, and its plans quietly import as Backlog with no
+    # indication anything was missed.
+    PLACEMENTS = {
+      new:                Placement.new(type: "backlog", name: "Backlog", labels: []),
+      researched:         Placement.new(type: "backlog", name: "Backlog", labels: %w[researched]),
+      ready_for_planning: Placement.new(type: "backlog", name: "Backlog", labels: %w[spec-ready]),
+      planned:            Placement.new(type: "unstarted", name: "Todo", labels: []),
+      building:           Placement.new(type: "started", name: "In Progress", labels: []),
+      # Both halves of building are one column on a board. A reader there
+      # wants to know work is under way; which half is under way is this
+      # tool's business, and the label carries it for anyone who does care.
+      building_ui:        Placement.new(type: "started", name: "In Progress", labels: %w[frontend]),
+      ready_for_review:   Placement.new(type: "started", name: "In Review", labels: []),
+      in_review:          Placement.new(type: "started", name: "In Review", labels: []),
+      rejected:           Placement.new(type: "started", name: "In Review", labels: %w[changes-requested]),
+      approved:           Placement.new(type: "completed", name: "Done", labels: []),
+      deployed:           Placement.new(type: "completed", name: "Done", labels: %w[deployed]),
+      blocked:            Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked]),
+      product_blocked:    Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked-on-product]),
+      deferred:           Placement.new(type: "backlog", name: "Backlog", labels: %w[deferred]),
+      retroactive:        Placement.new(type: "completed", name: "Done", labels: %w[retroactive]),
+      discarded:          Placement.new(type: "canceled", name: "Canceled", labels: [])
+    }.freeze
+
+    # States deliberately left out, and why.
+    #
+    # Both are real positions in this tool's lifecycle and neither is
+    # obviously any position on a Linear board. Where they belong is a
+    # statement about how a particular team works, and this tool does not know
+    # that. Guessing would be worse than not knowing: an issue filed in the
+    # wrong column reads exactly like an issue filed in the right one, and
+    # nobody goes looking for a mistake that renders correctly.
+    #
+    # A plan in one of these states is reported and skipped. To import them,
+    # decide where they belong and move the entry into {PLACEMENTS}.
+    UNPLACED = {
+      shit:        "the plan survives and its pull requests do not; whether that is work still to do " \
+                   "or work abandoned depends on what the team does next",
+      rolled_back: "it shipped and was pulled; whether that reopens this work or opens new work " \
+                   "depends on what broke"
+    }.freeze
+
+    # Where one unit of work belongs, which is not always where its plan does.
+    #
+    # A plan in 🟡 Building has some units merged and some not started. Giving
+    # every one of its issues the plan's own state says they are all in
+    # progress, which is false about most of them and useless on a board. A
+    # unit's pull requests are the better evidence, so they are used when
+    # there are any.
+    #
+    # @param status [OpenLanes::Plans::Status] the plan's state
+    # @param pulls [Array<OpenLanes::Plans::PullRequest>] the unit's
+    # @return [OpenLanes::Linear::Placement, nil]
+    def self.placement_for(status, pulls)
+      return placement(status) if pulls.empty?
+      return PLACEMENTS[:building].with(name: "In Review") if pulls.any?(&:open?)
+      return PLACEMENTS[:approved] if pulls.all?(&:merged?)
+
+      placement(status)
+    end
+
+    # Where a plan in this state belongs on a Linear board.
+    #
+    # @param status [OpenLanes::Plans::Status]
+    # @return [OpenLanes::Linear::Placement, nil] nil when nobody has decided
+    def self.placement(status) = PLACEMENTS[status.key]
+
+    # Why a state is not imported, for the report that says so.
+    #
+    # @param status [OpenLanes::Plans::Status]
+    # @return [String] the reason, or the louder one for a state nobody has considered at all
+    def self.reason_unplaced(status)
+      UNPLACED.fetch(status.key) do
+        "no Linear placement has ever been decided for it — add one to Linear::PLACEMENTS"
+      end
+    end
+  end
+end