agentilda 1.0.3

data/lib/agentilda/linear/push.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Linear
+    # What one {Action} actually did.
+    #
+    # @!attribute [r] action
+    #   @return [Agentilda::Linear::Action]
+    # @!attribute [r] identifier
+    #   @return [String, nil] "TAX-41"
+    # @!attribute [r] url
+    #   @return [String, nil]
+    # @!attribute [r] error
+    #   @return [String, nil] why it did not happen
+    Result = Data.define(:action, :identifier, :url, :error) do
+      # @return [Boolean]
+      def ok? = error.nil?
+    end
+
+    # Applies an {Import} through the {API}, then writes each plan's
+    # `linear.md` so the next run knows what this one did.
+    #
+    # Plans are pushed one at a time and in order. There is no concurrency
+    # here on purpose: within a plan the folder's own issue must exist before
+    # its children can name it as their parent, and across plans the gain
+    # would be a few seconds against the risk of two threads racing to create
+    # the same label on a team that does not have it yet.
+    class Push
+      # @param import [Agentilda::Linear::Import]
+      # @param api [Agentilda::Linear::API]
+      # @param tree [Agentilda::Tree]
+      def initialize(import:, api:, tree:)
+        @import = import
+        @api = api
+        @tree = tree
+      end
+
+      # @return [Array<Agentilda::Linear::Result>] every action attempted,
+      #   skips included, in plan order
+      def call
+        import.actions.group_by(&:ordinal).flat_map { |ordinal, actions| push_plan(ordinal, actions) }
+      end
+
+      private
+
+      # @return [Agentilda::Linear::Import]
+      attr_reader :import
+
+      # @return [Agentilda::Linear::API]
+      attr_reader :api
+
+      # @return [Agentilda::Tree]
+      attr_reader :tree
+
+      # @return [Hash] the team, its states and its labels
+      def team = @team ||= api.team(import.team)
+
+      # @return [String] the project everything is filed under
+      def project_id = import.project["id"]
+
+      # @param ordinal [String]
+      # @param actions [Array<Agentilda::Linear::Action>]
+      # @return [Array<Agentilda::Linear::Result>]
+      def push_plan(ordinal, actions)
+        subject = tree.find(ordinal) or return []
+        parents, children = actions.partition { |a| a.unit == Issues::PARENT }
+        return [] if parents.empty?
+
+        parent = apply(parents.first, subject, nil)
+        results = [parent] + children.map { |action| apply(action, subject, parent) }
+        record(subject, results)
+        results
+      end
+
+      # @param action [Agentilda::Linear::Action]
+      # @param subject [Agentilda::Subject]
+      # @param parent [Agentilda::Linear::Result, nil]
+      # @return [Agentilda::Linear::Result]
+      def apply(action, subject, parent)
+        if parent && !parent.ok?
+          return Result.new(action:, identifier: action.identifier, url: nil,
+            error: "the issue for its plan could not be created")
+        end
+
+        attempt(action) do
+          node = case action.op
+          when :skip then recorded(action, subject)
+          when :update then attach(api.update_issue(action.args[:id], input(action, parent)), action)
+          else attach(api.create_issue(input(action, parent).merge(teamId: team[:id], projectId: project_id)), action)
+          end
+
+          [node["identifier"], node["url"]]
+        end
+      end
+
+      # A child names its parent by the identifier Linear just handed back,
+      # which is why the folder's own issue is pushed first and alone.
+      #
+      # @param action [Agentilda::Linear::Action]
+      # @param parent [Agentilda::Linear::Result, nil]
+      # @return [Hash]
+      def input(action, parent)
+        base = {title: action.args[:title], description: action.args[:description],
+                stateId: state_id(action.args[:state]), labelIds: label_ids(action.args[:labels])}.compact
+        return base unless parent&.identifier
+
+        base.merge(parentId: parent.identifier)
+      end
+
+      # Attaching the pull requests is part of writing the issue, not a
+      # decoration on top of it. Linear keys an attachment on its URL, so
+      # sending the same one again updates it rather than piling up a second
+      # copy — which is what makes this safe on an update.
+      #
+      # @param node [Hash]
+      # @param action [Agentilda::Linear::Action]
+      # @return [Hash]
+      def attach(node, action)
+        Array(action.args[:links]).each { |l| api.link(issue_id: node["id"], url: l[:url], title: l[:title]) }
+        node
+      end
+
+      # @param action [Agentilda::Linear::Action]
+      # @param subject [Agentilda::Subject]
+      # @return [Hash]
+      def recorded(action, subject)
+        was = Issues.new(dir: subject.feature.path).by_unit[action.unit]
+        {"identifier" => was&.identifier || action.identifier, "url" => was&.url}
+      end
+
+      # A team names its own workflow states, so the name we would prefer is a
+      # preference and the type is the contract. Falling back to the type is
+      # what lets this run against a workspace whose "In Progress" is called
+      # something else entirely.
+      #
+      # @param name [String]
+      # @return [String, nil]
+      def state_id(name)
+        placement = PLACEMENTS.values.find { |p| p.name == name }
+        states = team[:states]
+
+        found = states.find { |s| s["name"].to_s.casecmp?(name.to_s) }
+        found ||= states.select { |s| s["type"] == placement&.type }.min_by { |s| s["position"].to_f }
+        found && found["id"]
+      end
+
+      # @param names [Array<String>]
+      # @return [Array<String>]
+      def label_ids(names)
+        Array(names).map do |name|
+          found = team[:labels].find { |l| l["name"].to_s.casecmp?(name) }
+          found ||= api.create_label(name, team[:id]).tap { |made| team[:labels] << made }
+          found["id"]
+        end
+      end
+
+      # Every Linear call is wrapped, so one plan that fails — a state the
+      # team does not have, a title Linear refuses — does not abandon the
+      # twenty plans queued behind it.
+      #
+      # @param action [Agentilda::Linear::Action]
+      # @yieldreturn [Array(String, String)] identifier and url
+      # @return [Agentilda::Linear::Result]
+      def attempt(action)
+        identifier, url = yield
+        Result.new(action:, identifier:, url:, error: nil)
+      rescue Error => e
+        Result.new(action:, identifier: action.identifier, url: nil, error: e.message)
+      end
+
+      # `linear.md` is rewritten from what actually happened, including the
+      # skips — a row dropped because its action was a no-op is a row the next
+      # run would recreate from scratch.
+      #
+      # @param subject [Agentilda::Subject]
+      # @param results [Array<Agentilda::Linear::Result>]
+      # @return [void]
+      def record(subject, results)
+        issues = results.select { |r| r.ok? && r.identifier }.map { |r|
+          Issue.new(unit: r.action.unit, identifier: r.identifier, url: r.url,
+            title: r.action.title, state: r.action.args[:state] || "", digest: r.action.digest)
+        }
+        return if issues.empty?
+
+        Issues.new(dir: subject.feature.path).write(team: import.team, issues:,
+          project: {name: import.project_name, url: import.project["url"]})
+      end
+    end
+  end
+end

data/lib/agentilda/linear/survey.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Linear
+    # What a team already has in Linear, set against what `.plans` holds.
+    #
+    # This exists because the import cannot see Linear at all — that is the
+    # property that makes its dry run trustworthy — and the cost of that
+    # property is a blind spot: a plan whose project someone already made by
+    # hand looks, from disk, exactly like a plan that has none. Proposing to
+    # create it would quietly produce a second project beside the first.
+    #
+    # So the reconciliation is its own read-only command rather than something
+    # smuggled into the import. It answers one question — *is anything here
+    # already in Linear under a different name?* — and answers it by showing
+    # both lists rather than by guessing.
+    class Survey
+      # How a project and a plan were found to be the same thing.
+      #
+      # Both rules are exact after normalising; neither is fuzzy. A near-match
+      # is reported as a near-match, because a project silently adopted by the
+      # wrong plan is worse than one nobody adopted at all.
+      Match = Data.define(:project, :subject, :rule) do
+        # @return [String]
+        def why = {ordinal: "its name carries the plan number", slug: "its name is the plan's slug"}.fetch(rule)
+      end
+
+      # @param tree [Agentilda::Tree]
+      # @param projects [Array<Hash>] `{"id", "name", "url", "status"}` from {API#projects}
+      def initialize(tree:, projects:)
+        @tree = tree
+        @projects = projects
+      end
+
+      # @return [Array<Hash>] every project, as Linear reports it
+      attr_reader :projects
+
+      # @return [Array<Agentilda::Linear::Survey::Match>]
+      def matches = @matches ||= projects.filter_map { |project| match_for(project) }
+
+      # Projects that correspond to no plan. Usually the team's real,
+      # hand-curated projects — the ones an import has no business touching.
+      #
+      # @return [Array<Hash>]
+      def unmatched = projects - matches.map(&:project)
+
+      # Plans with no project. An import would create one for each.
+      #
+      # @return [Array<Agentilda::Subject>]
+      def uncovered = tree.subjects - matches.map(&:subject)
+
+      # Projects whose name shares the plan's words without matching either
+      # rule, best first.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Array<Hash>]
+      def near(subject) = scored(subject).map(&:first)
+
+      # The best guess at which project a plan belongs under, for
+      # `--auto-assign`, with the number of words it agreed on.
+      #
+      # One shared word is not evidence — half these plans mention "tax" — so
+      # a guess needs two. Even then it is reported as a guess wherever it
+      # appears, because `plaid-integration` matching `Plaid Connectivity` is
+      # obvious to a person and, to this, indistinguishable from
+      # `tax-engine-consolidation` matching `Tax Law Engine`, which is wrong.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Array(Hash, Integer), nil] the project and its score
+      def guess(subject)
+        best, score = scored(subject).first
+        return nil unless best && score >= 2
+
+        [best, score]
+      end
+
+      # Projects with nothing written about them.
+      #
+      # A name is three or four words and half of them are the company's. What
+      # makes a plan recognisably one project's business rather than another's
+      # is the sentence saying what the project is for, and where that sentence
+      # is missing there is nothing to match a specification against.
+      #
+      # @return [Array<Hash>]
+      def undescribed = projects.reject { |p| described?(p) }
+
+      # @param project [Hash]
+      # @return [Boolean]
+      def described?(project) = !prose(project).strip.empty?
+
+      # Find one project by whatever the user had to hand: its URL, its name,
+      # or its id. A URL is the thing you can actually copy out of Linear.
+      #
+      # @param reference [String]
+      # @return [Hash]
+      # @raise [Agentilda::Error] when nothing matches it
+      def project(reference)
+        wanted = reference.to_s.strip
+        found = projects.find { |p|
+          p["url"].to_s.casecmp?(wanted) || p["name"].to_s.casecmp?(wanted) ||
+            p["id"] == wanted || p["url"].to_s.end_with?("/#{slugify(wanted)}")
+        }
+        return found if found
+
+        raise Error, "no project matches #{reference.inspect}. This team has:\n" +
+          projects.map { |p| "  #{p["name"]}\n    #{p["url"]}" }.join("\n")
+      end
+
+      private
+
+      # @return [Agentilda::Tree]
+      attr_reader :tree
+
+      # @param project [Hash]
+      # @return [Agentilda::Linear::Survey::Match, nil]
+      def match_for(project)
+        name = project["name"].to_s
+
+        by_ordinal = tree.subjects.find { |s| name.include?(s.feature.ordinal.to_s) }
+        return Match.new(project:, subject: by_ordinal, rule: :ordinal) if by_ordinal
+
+        by_slug = tree.subjects.find { |s| slugify(name) == s.feature.slug }
+        Match.new(project:, subject: by_slug, rule: :slug) if by_slug
+      end
+
+      # Every project that shares a word with this plan, best first.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Array<Array(Hash, Integer)>]
+      def scored(subject)
+        wanted = plan_words(subject)
+        return [] if wanted.empty?
+
+        projects.filter_map { |p|
+          overlap = (project_words(p) & wanted).size
+          [p, overlap] if overlap.positive?
+        }.sort_by { |_, overlap| -overlap }
+      end
+
+      # @param subject [Agentilda::Subject]
+      # @return [Array<String>]
+      def plan_words(subject)
+        words(subject.feature.slug) | words(slugify(subject.feature.title)) |
+          words(slugify(subject.goal.join(" ")))
+      end
+
+      # @param project [Hash]
+      # @return [Array<String>]
+      def project_words(project)
+        (@project_words ||= {})[project["id"]] ||=
+          words(slugify(project["name"])) | words(slugify(prose(project)))
+      end
+
+      # Whatever the project says about itself. Linear keeps a short line and a
+      # long document and a team uses whichever it uses.
+      #
+      # @param project [Hash]
+      # @return [String]
+      def prose(project) = "#{project["description"]} #{project["content"]} #{project["summary"]}"
+
+      # @param text [String]
+      # @return [String]
+      def slugify(text) = text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+
+      # Words too common to carry a match on their own.
+      NOISE = %w[the a an and or of to for app web spec plan].freeze
+
+      # @param slug [String]
+      # @return [Array<String>]
+      def words(slug) = slug.to_s.split("-").reject { |w| w.length < 3 || NOISE.include?(w) }
+    end
+  end
+end

data/lib/agentilda/linear/unit.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Agentilda
+  module Linear
+    # One unit of work inside a plan — the thing that becomes a Linear issue.
+    #
+    # @!attribute [r] key
+    #   @return [String] "PR-1" from a plan.md heading, or "#38" from a pull request
+    # @!attribute [r] title
+    #   @return [String] the heading's words, without the "PR-1 —" part
+    # @!attribute [r] body
+    #   @return [String] everything under the heading, as written
+    # @!attribute [r] pull_requests
+    #   @return [Array<Agentilda::PullRequest>] the ones this unit claims
+    Unit = Data.define(:key, :title, :body, :pull_requests)
+
+    # Reads the work units out of a plan folder.
+    #
+    # `plan.md` is written by an agent for humans, not as a data file, so this
+    # reads the one structure the format has always had: a heading per unit,
+    # naming the pull request it will become. Everything else is prose about
+    # those units.
+    #
+    # Two things about real plans make that harder than it sounds, and both
+    # were found by running this over thirty-eight of them:
+    #
+    #   * The unit headings are all at one level, but *which* level varies by
+    #     document — `## PR-1 — …` in one plan, `### PR 020.01 — …` in the
+    #     next. Deeper headings underneath them (`### PR-1 tests`) name the
+    #     same unit again. Matching every heading that mentions a pull request
+    #     turned one plan's three units into nine.
+    #   * A plan numbers its units either from one (`PR-1`) or from its own
+    #     spec number (`PR 020.01`). The second form is the first form with
+    #     the plan's number glued on, so it is normalised back.
+    #
+    # A plan with no such headings is not an error. Retroactive plans have no
+    # `plan.md` at all, and a small plan is often one pull request with no
+    # internal divisions — both import as a single issue standing for the
+    # whole plan, which is the honest reading of a plan that never divided
+    # itself.
+    class Units
+      # `## 2. PR-1 — …`, `### PR 020.01 — …`, and the several other ways the
+      # same heading gets typed. The hashes are escaped because an unescaped
+      # `#{` in a regexp literal is interpolation.
+      HEADING = /\A(\#{2,4})[ \t]+(?:\d+[.)][ \t]*)?PR[\s_-]?(\d+(?:\.\d+)?)\b[ \t]*(.*)\z/i
+
+      # A fenced block can hold anything, including lines that read as
+      # headings — `plan.md` files are full of shell and SQL whose comments
+      # start with `#`. Scanning without stripping fences invents units.
+      FENCE = /^[ \t]{0,3}(?:```|~~~)/
+
+      # `(✔ #38)`, `(▶︎ in-flight)`, `(⬜ blocked)` — a status glyph in a
+      # trailing parenthetical. It is the state of the unit, which Linear
+      # tracks itself, and leaving it in the title means every title churns
+      # the moment the work moves.
+      GLYPH_NOTE = /\s*\((?:[^\w\s(][^)]*)\)\s*\z/
+
+      # The same thing without the brackets: `… over the law plane ☢️ deferred`.
+      TRAILING_GLYPH = /\s*[\u{2190}-\u{2BFF}\u{1F000}-\u{1FAFF}][^\n]*\z/
+
+      # A plan number the author typed into the heading as well. The issue for
+      # the plan already carries it.
+      OWN_NUMBER = /\A\[\d{1,3}(?:\.\d{2})?\]\s*/
+
+      # Pull request numbers named in the heading: "(✔ #38)".
+      NUMBERED = /#(\d+)\b/
+
+      # @param subject [Agentilda::Subject]
+      def initialize(subject:)
+        @subject = subject
+      end
+
+      # The units of work inside a plan, which become its sub-issues.
+      #
+      # A plan that declares its units in `plan.md` gets those. A plan that
+      # does not — a retroactive one, or one written before the convention —
+      # gets one per pull request instead, because a pull request that shipped
+      # is a unit of work whether or not anybody wrote it down first.
+      #
+      # A plan with neither is legitimately empty: it has been specified and
+      # nothing has been divided or built yet. Its issue stands alone until
+      # somebody plans it.
+      #
+      # @return [Array<Agentilda::Linear::Unit>] possibly empty
+      def all = @all ||= divided.empty? ? from_pull_requests : attach(divided)
+
+      # A pull request title carries the plan number this tool put there, and
+      # often the unit it implements. Neither belongs in an issue title: the
+      # issue for the plan already says which plan, and the attachment already
+      # says which pull request.
+      #
+      # @param title [String]
+      # @return [String]
+      def self.clean_title(title)
+        title.to_s
+          .sub(/\A\[[^\]]*\]\s*/, "")
+          .sub(/\A(?:spec\s*)?\d{1,3}(?:\.\d{2})?\s*[—–:.-]?\s*/i, "")
+          .sub(/\APR[\s_-]?\d+(?:\.\d+)?\s*[—–:.-]?\s*/i, "")
+          .strip
+      end
+
+      private
+
+      # @return [Agentilda::Subject]
+      attr_reader :subject
+
+      # @return [Array<Agentilda::Linear::Unit>] possibly empty
+      def divided = @divided ||= merge(sections).map { |key, title, body| Unit.new(key:, title:, body:, pull_requests: []) }
+
+      # One unit per pull request, for a plan that declared none itself.
+      #
+      # Keyed by pull request number rather than by position, so the key means
+      # something on its own and cannot collide with the `PR-1` keys a
+      # `plan.md` would introduce later.
+      #
+      # @return [Array<Agentilda::Linear::Unit>]
+      def from_pull_requests
+        subject.pull_requests.map do |pr|
+          Unit.new(key: "##{pr.number}", title: clean_pr(pr.title), body: "", pull_requests: [pr])
+        end
+      end
+
+      # @param title [String]
+      # @return [String]
+      def clean_pr(title) = self.class.clean_title(title)
+
+      # @return [Array<Array(String, String, String)>] key, title, body
+      def sections
+        lines = readable
+        level = headings(lines).map(&:first).min
+        return [] unless level
+
+        found = []
+        lines.each do |line|
+          match = HEADING.match(line)
+          if match && match[1].length == level
+            found << [key_for(match[2]), clean(match[3]), +""]
+          elsif found.any?
+            found.last[2] << line << "\n"
+          end
+        end
+        found.reject { |_, title, _| title.empty? }
+      end
+
+      # A heading at the shallowest level that names a pull request starts a
+      # unit; a deeper one is that unit's contents.
+      #
+      # @param lines [Array<String>]
+      # @return [Array<Array(Integer, String)>] level and key
+      def headings(lines)
+        lines.filter_map { |line|
+          match = HEADING.match(line)
+          [match[1].length, key_for(match[2])] if match
+        }
+      end
+
+      # `PR 020.01` inside plan 020.00 is this plan's first unit, written the
+      # long way. Reduced, so its key does not depend on which convention the
+      # author reached for.
+      #
+      # @param number [String] "1" or "020.01"
+      # @return [String]
+      def key_for(number)
+        major, minor = number.split(".")
+        return "PR-#{number}" unless minor
+        return "PR-#{number}" unless major.to_i == subject.feature.ordinal.major
+
+        "PR-#{minor.to_i}"
+      end
+
+      # One unit, headed twice. Bodies join; the first title wins, because a
+      # later heading for the same unit is a continuation and titles itself
+      # like one — "PR-1 tests", "PR-1 parameters".
+      #
+      # @param sections [Array<Array(String, String, String)>]
+      # @return [Array<Array(String, String, String)>]
+      def merge(sections)
+        sections.each_with_object({}) { |(key, title, body), by_key|
+          if by_key.key?(key)
+            by_key[key][2] = "#{by_key[key][2]}\n\n#{body}"
+          else
+            by_key[key] = [key, title, body]
+          end
+        }.values.map { |key, title, body| [key, title, body.strip] }
+      end
+
+      # Which pull requests each unit claims, by the three joins that exist
+      # between `plan.md` and `pull-requests.md`, most explicit first.
+      #
+      # @param units [Array<Agentilda::Linear::Unit>]
+      # @return [Array<Agentilda::Linear::Unit>]
+      def attach(units)
+        claimed = []
+        found = units.map { |unit|
+          prs = (numbered(unit) + named(unit)).uniq - claimed
+          claimed.concat(prs)
+          unit.with(pull_requests: prs)
+        }
+
+        return found unless found.one?
+
+        # With one unit there is nowhere else for a pull request to go. That
+        # is arithmetic rather than a guess, so it is done rather than warned
+        # about — and it is the common case for the small plans.
+        [found.first.with(pull_requests: subject.pull_requests)]
+      end
+
+      # The heading said so: `### PR 020.03 — Clerk webhooks (✔ #44)`.
+      #
+      # @param unit [Agentilda::Linear::Unit]
+      # @return [Array<Agentilda::PullRequest>]
+      def numbered(unit)
+        wanted = heading_for(unit.key).to_s.scan(NUMBERED).flatten
+        subject.pull_requests.select { |pr| wanted.include?(pr.number.to_s) }
+      end
+
+      # The pull request title said so: "Spec 010 PR-2: MAGI registry".
+      #
+      # @param unit [Agentilda::Linear::Unit]
+      # @return [Array<Agentilda::PullRequest>]
+      def named(unit)
+        pattern = /\bPR[\s_-]?#{unit.key[/\d+\z/]}\b/i
+        subject.pull_requests.select { |pr| pr.title.match?(pattern) }
+      end
+
+      # Every heading line that names a unit, grouped by its key — the deeper
+      # continuation headings included, since any of them may be the one
+      # carrying the pull request number.
+      #
+      # @return [Hash{String => Array<String>}]
+      def headlines
+        @headlines ||= readable.each_with_object(Hash.new { |h, k| h[k] = [] }) do |line, found|
+          match = HEADING.match(line)
+          found[key_for(match[2])] << line if match
+        end
+      end
+
+      # @param key [String]
+      # @return [String] every heading this unit was written under
+      def heading_for(key) = headlines[key].join("\n")
+
+      # Every line of `plan.md` that is not inside a fence, fence lines
+      # themselves included in what gets dropped.
+      #
+      # @return [Array<String>]
+      def readable
+        @readable ||= begin
+          fenced = false
+          subject.read("plan.md").to_s.each_line(chomp: true).each_with_object([]) do |line, kept|
+            if line.match?(FENCE)
+              fenced = !fenced
+            elsif !fenced
+              kept << line
+            end
+          end
+        end
+      end
+
+      # @param title [String]
+      # @return [String]
+      def clean(title)
+        title.to_s
+          .sub(/\A\([^)]*\)\s*/, "") # "(010a) — Per-person taxes" — a nickname, not a title
+          .sub(/\A[—–:.-]+\s*/, "")
+          .sub(GLYPH_NOTE, "")
+          .sub(TRAILING_GLYPH, "")
+          .gsub(/[*`]/, "") # before OWN_NUMBER: the number is often inside backticks
+          .sub(/\A_+/, "").sub(/_+\z/, "") # emphasis, but never `signed_off`
+          .sub(OWN_NUMBER, "")
+          .strip
+      end
+    end
+  end
+end

data/lib/agentilda/linear.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Agentilda
+  # `.plans` as Linear projects and issues.
+  #
+  # The folders already are a tracker: a number, a state, a set of pull
+  # requests and a document saying why. What they are not is visible to anyone
+  # who does not have the repository checked out, which is most of the people
+  # who want to know how a piece of work is going. This exports to Linear so
+  # that audience can see it, and it exports *one way* — the folder is the
+  # truth, Linear is the window.
+  #
+  # Four pieces, in the order a run uses them:
+  #
+  #   {Units}   reads `plan.md` and finds the work units inside a plan
+  #   {Import}  decides, from disk alone, what would be created or updated
+  #   {Push}    applies that through {API} and records what it did
+  #   {Issues}  is the record, `linear.md`, that makes the next run idempotent
+  #
+  # {Import} touches nothing but the filesystem, which is what makes the dry
+  # run trustworthy: it is not a description of what a push would do, it is
+  # the object the push consumes.
+  module Linear
+    # Team keys are what Linear puts in front of every issue number.
+    KEY = /\A[A-Z][A-Z0-9]{1,9}\z/
+
+    # @param prefix [String, nil]
+    # @return [String] the normalised team key
+    # @raise [Agentilda::Error] when it could never be one
+    def self.key!(prefix)
+      key = prefix.to_s.strip.upcase
+      return key if key.match?(KEY)
+
+      raise Error, "#{prefix.inspect} is not a Linear team key. A key is 2–10 characters, " \
+                   "letters and digits, as in TAX or ENG — the part before the dash in TAX-41."
+    end
+  end
+end
+
+%w[mapping fuzzy unit issue survey attribution import api push].each do |part|
+  require File.join(__dir__, "linear", "#{part}.rb")
+end