openlanes 3.0.0

data/lib/openlanes/lifecycle/adoption.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "parallel"
+
+module OpenLanes
+  module Lifecycle
+    # Gives a plan folder to every pull request that has no plan to point at.
+    #
+    # `resync prs` can resolve most pull requests from their branch or their
+    # diff. What it cannot resolve it used to flag for a human — "diff touches
+    # 021.00, 022.00, 024.00 and none is obviously primary" — and stop. That is
+    # honest but not useful: the work exists, it is unspecified, and leaving it
+    # unnumbered means it never appears in the index at all.
+    #
+    # So an orphan is adopted instead. It gets a retroactive plan of its own,
+    # numbered in the gap after the furthest plan it can see, holding the pull
+    # request that produced it.
+    #
+    # == Why the numbering is allocated serially
+    #
+    # The obvious parallel design — every worker reads the highest number and
+    # adds `.01` — is deterministic but not unique, and the collision is the
+    # common case rather than the rare one. Fifteen open pull requests branched
+    # off the same main all see the same highest number and all compute the same
+    # slot. Determinism is not the property that matters here; distinctness is.
+    #
+    # So the pipeline is **gather in parallel, allocate serially, apply in
+    # parallel**. The allocation is pure arithmetic over an array that is
+    # already in memory, so the serial section costs microseconds; the two
+    # expensive phases — reading each branch and writing each folder — keep the
+    # whole fan-out. And because the slots are handed out before any worker
+    # starts, no worker can want a number another worker holds: no locks, no
+    # retries, and the same input produces the same numbers every run.
+    class Adoption
+      # One pull request and the plan it is being given.
+      #
+      # @!attribute [r] pull
+      #   @return [Hash] as returned by {GitHub#pulls}
+      # @!attribute [r] ordinal
+      #   @return [OpenLanes::Plans::Ordinal] the slot it was allocated
+      # @!attribute [r] major
+      #   @return [Integer] the furthest plan its branch or diff could see
+      # @!attribute [r] path
+      #   @return [String, nil] the folder, once created
+      Adoptee = Data.define(:pull, :ordinal, :major, :path) do
+        # @return [String] the folder name this pull request earns
+        def dirname = OpenLanes::Plans.plan_dirname(ordinal, Plans::STATUS_BY_KEY.fetch(:retroactive), slug)
+
+        # The PR title, stripped of any prefix, as the folder's tail.
+        #
+        # @return [String]
+        def slug = Creator.slugify(pull[:title].to_s.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
+
+        # @return [String] a single auditable line
+        def to_s = "##{pull[:number]} → #{dirname}"
+      end
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param github [OpenLanes::Vcs::GitHub]
+      # @param root [String] repository root, for reading branches
+      # @param jobs [Integer] workers for the two parallel phases
+      def initialize(tree:, github: Vcs::GitHub.new, root: nil, jobs: UI.default_jobs)
+        @tree = tree
+        @github = github
+        @root = root || File.dirname(tree.dir)
+        @jobs = jobs
+      end
+
+      # @return [OpenLanes::Plans::Tree]
+      attr_reader :tree
+
+      # @return [OpenLanes::Vcs::GitHub]
+      attr_reader :github
+
+      # @return [String]
+      attr_reader :root
+
+      # @return [Integer]
+      attr_reader :jobs
+
+      # Work out what each orphan would be given, without creating anything.
+      #
+      # @param pulls [Array<Hash>] the orphans, from {Resync::Prs}
+      # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>] in pull request order
+      def plan(pulls)
+        allocate(gather(pulls))
+      end
+
+      # Adopt every orphan: create its folder and record its pull request.
+      #
+      # @param pulls [Array<Hash>]
+      # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>] with `path` filled in
+      def call(pulls)
+        adoptees = plan(pulls)
+        return adoptees if adoptees.empty?
+
+        created = Parallel.map(adoptees, in_threads: jobs) { |adoptee| adopt(adoptee) }
+        tree.reload
+        created
+      end
+
+      private
+
+      # Phase one, in parallel: ask each pull request's branch how far the
+      # sequence had got when the work started. Branches are not all rebased
+      # onto the same main, so this is per-branch rather than tree-wide, and it
+      # is a network-free `ls-tree` per pull request.
+      #
+      # @param pulls [Array<Hash>]
+      # @return [Array<Array(Hash, Integer)>] each pull with its major
+      def gather(pulls)
+        ordered = pulls.sort_by { |pull| pull[:number].to_i }
+
+        Parallel.map(ordered, in_threads: jobs) { |pull| [pull, major_for(pull)] }
+      end
+
+      # The furthest whole plan this pull request can see: on its own branch
+      # first, then whatever it touched, then the tree we are standing in. A
+      # pull request whose branch is long gone still has a diff.
+      #
+      # @param pull [Hash]
+      # @return [Integer]
+      def major_for(pull)
+        candidates = OpenLanes.plans_on_ref(root, pull[:branch].to_s)
+        candidates = touched(pull) if candidates.empty?
+        candidates = tree.subjects.map { |s| s.feature.ordinal } if candidates.empty?
+
+        candidates.map(&:major).max.to_i
+      end
+
+      # @param pull [Hash]
+      # @return [Array<OpenLanes::Plans::Ordinal>]
+      def touched(pull)
+        Array(pull[:files]).filter_map { |path|
+          parts = path.to_s.split("/")
+          index = parts.index(OpenLanes::PLANS_DIR)
+          index && parts[index + 1] && Plans::Ordinal.from_dirname(parts[index + 1])
+        }.uniq
+      end
+
+      # Phase two, serial and deliberately so. Minors are handed out per major,
+      # continuing past every slot the tree already holds, in ascending pull
+      # request order — so the numbers follow the order the work was opened in,
+      # and two pull requests cannot be given the same one.
+      #
+      # @param gathered [Array<Array(Hash, Integer)>]
+      # @return [Array<OpenLanes::Lifecycle::Adoption::Adoptee>]
+      def allocate(gathered)
+        taken = Hash.new { |h, major| h[major] = minors_taken(major) }
+
+        gathered.filter_map do |pull, major|
+          minor = ((taken[major].max || 0) + 1)
+          next if minor > Plans::Ordinal::MAX_MINOR
+
+          taken[major] << minor
+          Adoptee.new(pull:, major:, ordinal: Plans::Ordinal.new(major:, minor:), path: nil)
+        end
+      end
+
+      # @param major [Integer]
+      # @return [Array<Integer>] minors already used under this major
+      def minors_taken(major)
+        tree.subjects.map { |s| s.feature.ordinal }.select { |o| o.major == major }.map(&:minor)
+      end
+
+      # Phase three, in parallel: each worker owns a number nobody else can
+      # want, so it can create its folder without coordinating with anyone.
+      #
+      # @param adoptee [OpenLanes::Lifecycle::Adoption::Adoptee]
+      # @return [OpenLanes::Lifecycle::Adoption::Adoptee]
+      def adopt(adoptee)
+        path = File.join(tree.dir, adoptee.dirname)
+        return adoptee if File.exist?(path)
+
+        FileUtils.mkdir_p(path)
+        File.write(File.join(path, Plans::PullRequests::FILENAME),
+          Plans::PullRequests.render([pull_request_for(adoptee)]))
+
+        adoptee.with(path:)
+      end
+
+      # The body is what a specification would be written from, so it is worth
+      # a second request. A failure here costs the description, not the folder.
+      #
+      # @param adoptee [OpenLanes::Lifecycle::Adoption::Adoptee]
+      # @return [Hash]
+      def pull_request_for(adoptee)
+        pull = adoptee.pull
+        github.pull_request(pull[:number].to_s)
+      rescue OpenLanes::Error
+        { number: pull[:number], title: pull[:title], url: pull[:url],
+         state: pull[:state] || "Unknown", body: "" }
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/brief.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "tty/command"
+
+module OpenLanes
+  module Lifecycle
+    # A new plan's opening brief: four questions, and a best-effort first pass
+    # at answering them from what the project already has on disk.
+    #
+    # This is for work that does not exist yet. A plan created `--after` a
+    # shipped pull request already has its facts — {CLI::Create} hands those to
+    # `yoda-writer`, which reconstructs a specification from a diff, not this.
+    # Guessing at a diff and guessing at a feature nobody has built are
+    # different jobs, and conflating them is how a retroactive spec ends up
+    # full of hedges about something that already, provably, happened.
+    #
+    # The four headings are the brief `leah-researcher` and `yoda-writer` both
+    # read *before* their own chapters: what research needs to settle is a
+    # question about the gaps in `## What already exists`, so a scaffold
+    # missing that heading forces both of them to first reconstruct a boundary
+    # this class already had for free — it just created the folder.
+    class Brief
+      # The half-agent's name. It has no `agents/*.md` of its own on purpose —
+      # a roster entry would put it in `Runner`'s routing, and this pass runs
+      # only inside `create`. The name exists so the UI can show it the same
+      # way it shows `leah-researcher` and `yoda-writer` on their spinner lines.
+      AGENT_NAME = "anakin-briefster"
+
+      HEADINGS = [
+        "What we are trying to achieve",
+        "Why it matters",
+        "What already exists",
+        "What research needs to settle"
+      ].freeze
+
+      # Read whole into the drafting prompt, in order, so the model sees the
+      # project's own account of itself before it sees the topic.
+      CONTEXT_FILES = %w[CLAUDE.md AGENTS.md README.md].freeze
+
+      # Relative to the repository root. Not every project keeps one — a
+      # missing backlog is silently skipped, not an error.
+      BACKLOG_FILE = File.join(OpenLanes::PLANS_DIR, "BACKLOG.md")
+
+      # Long enough for a handful of Read/Grep/Glob calls over a local
+      # checkout; short enough that a hung `claude` does not stall `create`
+      # past the point where the scaffold is already there to open by hand.
+      TIMEOUT = 60
+
+      # The fastest model, and the draft is disposable: the prompt prefers an
+      # honest blank over a clever inference, so there is no reasoning premium
+      # worth paying a larger model for inside a 60-second budget.
+      BRIEF_MODEL = "haiku"
+
+      # Read-only, and no `Bash` — this pass surveys what the repository
+      # already says about itself, it does not go looking further. That is
+      # `leah-researcher`'s job, and denying her tools here is what keeps the
+      # two from quietly doing the same work twice.
+      ALLOWED_TOOLS = %w[Read Grep Glob Edit].freeze
+      DENIED_TOOLS = %w[WebFetch WebSearch Bash].freeze
+
+      # The `stdout:` and `stderr:` sections of a {TTY::Command::ExitError}
+      # message. stdout runs until stderr starts; stderr runs to the end, because
+      # what `claude` prints there is not guaranteed to be one line.
+      STDOUT_SECTION = /^[ \t]*stdout:[ \t]*(.*?)(?=\n[ \t]*stderr:|\z)/m
+      STDERR_SECTION = /^[ \t]*stderr:[ \t]*(.*)\z/m
+
+      # How much of what `claude` said survives into a one-line report.
+      REASON_LIMIT = 300
+
+      # A one-line account of a failed `claude` run, built from the error rather
+      # than its first line: that first line is the escaped prompt, several
+      # thousand characters of it, and reporting it says an invocation failed,
+      # at length, and never why.
+      #
+      # Both streams are kept because they carry different halves. `claude`
+      # reports its own failures on stdout; the line naming the *cause* of a 401
+      # (`ANTHROPIC_API_KEY ... takes precedence over your claude.ai login`) is
+      # on stderr. {Executor} used to own this; it now reads a child process
+      # directly and has no exit error to parse, so the briefer keeps it.
+      #
+      # @param error [TTY::Command::ExitError]
+      # @return [String]
+      def self.failure_reason(error)
+        status = error.message[/^[ \t]*exit status:[ \t]*(\S+)/, 1]
+        outcome = status ? "exited #{status}" : "failed"
+        said = [STDOUT_SECTION, STDERR_SECTION]
+               .filter_map { |section| tail(error.message[section, 1]) }
+               .join(" | ")
+
+        said.empty? ? "#{outcome} and said nothing" : "#{outcome}: #{said}"
+      end
+
+      # @param text [String, nil]
+      # @return [String, nil] the last few meaningful lines, on one line
+      def self.tail(text)
+        lines = text.to_s.split("\n").map(&:strip).reject { |line| line.empty? || line == "Nothing written" }
+        return nil if lines.empty?
+
+        joined = lines.last(3).join(" ")
+        joined.length > REASON_LIMIT ? "#{joined[0, REASON_LIMIT - 1]}..." : joined
+      end
+      private_class_method :tail
+
+      # @param path [String] the new plan folder, absolute
+      # @param title [String] the feature's proper name, e.g. "Tax Rule DSL"
+      # @param root [String] repository root, for project context and `--add-dir`
+      # @param command [TTY::Command]
+      # @param timeout [Integer] seconds before the drafting attempt is abandoned
+      # @param dry_run [Boolean] plan the invocation, do not run it
+      # @param seed [String, nil] what the author already wrote about the
+      #   feature (`create --from`); opens spec.md and outranks the repo survey
+      def initialize(
+        path:,
+        title:,
+        root:,
+        command: TTY::Command.new(printer: :null),
+        timeout: TIMEOUT,
+        dry_run: false,
+        seed: nil
+      )
+        @path = path
+        @title = title
+        @root = File.expand_path(root)
+        @command = command
+        @timeout = timeout
+        @dry_run = dry_run
+        @seed = seed.to_s.strip.then { |s| s.empty? ? nil : s }
+      end
+
+      # @return [String]
+      attr_reader :path, :title, :root
+
+      # @return [String, nil]
+      attr_reader :seed
+
+      # @return [String] absolute path to the spec, whether or not it exists yet
+      def spec_path = File.join(path, "spec.md")
+
+      # The title and four empty headings — and, when `create --from` supplied
+      # one, the author's own prose between them, so the file already says
+      # something even if the drafting attempt never returns.
+      #
+      # @return [String]
+      def scaffold
+        opening = seed ? "#{seed}\n\n" : ""
+        "# #{title}\n\n#{opening}" + HEADINGS.map { |h| "## #{h}\n\n" }.join("\n")
+      end
+
+      # @return [String] where it was written
+      def write_scaffold!
+        File.write(spec_path, scaffold)
+        spec_path
+      end
+
+      # Make a best-effort attempt at the four headings, in place, by shelling
+      # out to `claude` the same way {Executor} does for a specialist agent.
+      # A failure here is not this method's to hide: the scaffold {#write_scaffold!}
+      # already wrote stands on its own, so the caller reports the failure and
+      # moves on rather than treating it as fatal to `create`.
+      #
+      # @return [Array(Boolean, String)] ok, and a one-line note
+      def attempt!
+        return [true, "dry run — would draft from project context"] if @dry_run
+
+        begin
+          @command.run(*invocation, timeout: @timeout)
+        rescue TTY::Command::TimeoutExceeded
+          return [false, "timed out after #{@timeout}s"]
+        rescue TTY::Command::ExitError => e
+          return [false, "claude #{self.class.failure_reason(e)}"]
+        end
+
+        [true, "drafted"]
+      end
+
+      # Exposed so a spec can assert the boundary without running anything.
+      #
+      # @return [Array<String>]
+      def invocation
+        # Lean for the same reason every agent is: the draft has fifty
+        # seconds, and the operator's plugins would spend some of them loading.
+        ["claude",
+         "-p", prompt, "--add-dir", root,
+         "--model", BRIEF_MODEL,
+         *Adapters::Claude::LEAN,
+         "--allowedTools", ALLOWED_TOOLS.join(","),
+         "--disallowedTools", DENIED_TOOLS.join(",")]
+      end
+
+      private
+
+      # @return [String]
+      def prompt
+        <<~PROMPT
+          #{author_statement}A new plan folder was just created for a feature that does not exist
+          yet: "#{title}".
+
+          You have 50 seconds. Explore the codebase for the first thirty and
+          write for the last twenty; the process is killed at sixty and an
+          unwritten draft is lost.
+
+          #{spec_path} holds a title and four empty headings:
+
+          #{HEADINGS.map { |h| "  * #{h}" }.join("\n")}
+
+          Make a best-effort first pass at each, drawn only from what THIS
+          project already has on disk under #{root} — its own docs, its own
+          conventions, code already built, and anything already downloaded or
+          gathered that bears on "#{title}". Read/Grep/Glob freely to look for
+          it; do not invent facts and do not research the web. Where the
+          repository gives you nothing to go on, leave that heading's body as
+          a short, honest one-line note saying so, e.g. "_Nothing in the repo
+          speaks to this yet — needs research._" A human completes this
+          afterward, and a confident-sounding guess costs them more to unwind
+          than an honest blank.
+
+          `## What already exists` matters most: name specific files, modules
+          or prior work you found, not just that "some code exists" — that is
+          exactly the context a researcher picking this up next cannot see for
+          themselves without being told where to look.
+
+          #{context}
+          #{backlog}
+          Edit #{spec_path} in place. Keep the title#{", the author's opening prose" if seed} and the four `##`
+          headings exactly as they are, in order; add prose under them; write
+          nothing outside them; touch no other file.
+        PROMPT
+      end
+
+      # The author's own words lead the prompt, ahead of even the feature's
+      # announcement, because they outrank everything this pass could survey:
+      # where the seed and the repository disagree, the seed is the intent and
+      # the repository is merely the past.
+      #
+      # @return [String] empty without a seed
+      def author_statement
+        return "" unless seed
+
+        <<~STATEMENT
+          The author has already written the following about this feature. It
+          is the primary source: where it answers one of the headings, draw
+          from it first, and use the repository survey below only to supplement
+          it — never to contradict it.
+
+          #{seed}
+
+        STATEMENT
+      end
+
+      # AGENTS.md is commonly a symlink to CLAUDE.md; realpath-deduping keeps
+      # the shared content from being inlined twice into every drafting prompt.
+      #
+      # @return [String]
+      def context
+        seen = []
+        found = CONTEXT_FILES.filter_map { |name|
+          file = File.join(root, name)
+          next unless File.file?(file)
+
+          real = File.realpath(file)
+          next if seen.include?(real)
+
+          seen << real
+          "### #{name}\n\n#{File.read(file, encoding: "UTF-8")}"
+        }
+        return "" if found.empty?
+
+        "## Project context\n\n#{found.join("\n\n")}\n"
+      end
+
+      # A relevant line in the project's own backlog is worth more than
+      # anything this pass could infer on its own — it is the one place "why
+      # now" might already be written down.
+      #
+      # @return [String]
+      def backlog
+        file = File.join(root, BACKLOG_FILE)
+        return "" unless File.file?(file)
+
+        "## #{BACKLOG_FILE}\n\n" \
+          "If this backlog mentions \"#{title}\", treat that entry as " \
+          "authoritative for `## Why it matters` — it is the project's own " \
+          "statement of intent.\n\n" \
+          "#{File.read(file, encoding: "UTF-8")}\n"
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/completion.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Lifecycle
+    # Copies the spec's `task-completed-when` and `how-to-verify` into
+    # `plan.md`, so the builders and the reviewer read them in the document
+    # they work from rather than only in the frontmatter of another one.
+    #
+    # An agent is asked to copy them; the harness checks. A planner that
+    # paraphrased them, or forgot, would leave the criteria in the one place
+    # the reviewer was not looking, so a missing section is appended after the
+    # agent signs, and a section the agent wrote is never touched.
+    module Completion
+      COMPLETED_WHEN_HEADING = "## Task completed when"
+      HOW_TO_VERIFY_HEADING = "## How to verify"
+
+      module_function
+
+      # The sections for the spec's criteria, in the order a reader needs them.
+      #
+      # @param spec [OpenLanes::Plans::Spec]
+      # @param present [String] the plan's current text; sections it already
+      #   has are left out
+      # @return [String] empty when the spec says nothing, or the plan has it
+      def markdown(spec, present: "")
+        [
+          section(COMPLETED_WHEN_HEADING, spec.completed_when, present),
+          section(HOW_TO_VERIFY_HEADING, spec.how_to_verify, present)
+        ].compact.join("\n")
+      end
+
+      # Append whatever `plan.md` is missing. Writes nothing when it is
+      # complete, so it is safe after every round.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [Boolean] whether the file changed
+      def copy(subject)
+        path = File.join(subject.feature.path, "plan.md")
+        return false unless File.file?(path)
+
+        text = File.read(path, encoding: "UTF-8")
+        missing = markdown(Plans::Spec.for(subject), present: text)
+        return false if missing.empty?
+
+        File.write(path, "#{text.rstrip}\n\n#{missing}")
+        true
+      end
+
+      # @return [String, nil]
+      def section(heading, items, present)
+        return nil if items.empty? || present.match?(/^#{Regexp.escape(heading)}\s*$/i)
+
+        "#{heading}\n\n#{items.map { |item| "- #{item}" }.join("\n")}\n"
+      end
+      private_class_method :section
+    end
+  end
+end

data/lib/openlanes/lifecycle/creator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "fileutils"
+
+module OpenLanes
+  module Lifecycle
+    # Mints new plan folders. Backs `/spec-create`.
+    #
+    # Every failure is a `Failure`, never an exception: creating a folder is the
+    # one place a typo becomes permanent, so the caller is made to look.
+    class Creator
+      include Dry::Monads[:result]
+
+      # The state a new plan opens in — a specification and nothing else yet.
+      DEFAULT_STATUS = :new
+
+      # The state a retroactive plan is born in: the work is live, but it has
+      # neither a specification nor a plan.
+      RETROACTIVE_STATUS = :retroactive
+
+      # @param dir [String] the `.plans` directory
+      def initialize(dir:)
+        @dir = File.expand_path(dir)
+      end
+
+      # @return [String] the `.plans` directory
+      attr_reader :dir
+
+      # Create a plan folder.
+      #
+      # @param words [Array<String>] the topic; becomes the slug
+      # @param after [String, nil] anchor for a retroactive plan, e.g. "002"
+      # @param status [String, Symbol, nil] override the default state
+      # @param prs [Array<Hash>, nil] pull requests to record, already fetched;
+      #   their presence is what makes the folder 🕰️ Retroactive rather than ⚪️
+      # @return [Dry::Monads::Result] Success(absolute path) or Failure(message)
+      def create(words:, after: nil, status: nil, prs: nil)
+        resolved = resolve_status(status, after) or
+          return Failure("unknown status: #{status}")
+
+        slug = self.class.slugify(words)
+        return Failure("the topic produced an empty slug") if slug.empty?
+
+        ordinal = after ? retroactive_ordinal(after) : Plans::Ordinal.next_major(existing)
+        return ordinal if ordinal.is_a?(Dry::Monads::Result)
+
+        build(ordinal, resolved, slug).fmap { |path| record_pull_requests(path, prs) }
+      rescue OpenLanes::Error => e
+        Failure(e.message)
+      end
+
+      # @return [Array<OpenLanes::Plans::Ordinal>] every number already taken
+      def existing
+        @existing ||= begin
+          return [] unless File.directory?(dir)
+
+          Dir.children(dir)
+             .select { |c| File.directory?(File.join(dir, c)) }
+             .filter_map { |c| Plans::Ordinal.from_dirname(c) }
+        end
+      end
+
+      # Turn free text into the kebab tail of a folder name.
+      #
+      # @param words [Array<String>, String]
+      # @return [String] possibly empty, which the caller must reject
+      def self.slugify(words)
+        Array(words).join(" ").downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      end
+
+      private
+
+      # @param status [String, Symbol, nil]
+      # @param after [String, nil]
+      # @return [OpenLanes::Plans::Status, nil]
+      def resolve_status(status, after)
+        return OpenLanes::Plans.status(status) if status
+
+        Plans::STATUS_BY_KEY.fetch(after ? RETROACTIVE_STATUS : DEFAULT_STATUS)
+      end
+
+      # @param after [String]
+      # @return [OpenLanes::Plans::Ordinal, Dry::Monads::Result]
+      def retroactive_ordinal(after)
+        anchor = Plans::Ordinal.parse(after) or return Failure("not a plan number: #{after}")
+
+        unless existing.any? { |o| o.major == anchor.major }
+          return Failure("no plan #{format("%03d", anchor.major)} to anchor against — " \
+                         "a retroactive plan names the plan its work landed after")
+        end
+
+        Plans::Ordinal.next_minor(existing, major: anchor.major)
+      end
+
+      # Write the pull requests the folder was created from, so 🕰️ Retroactive
+      # is justified the moment the folder exists — that state means "the work is
+      # live and undocumented", and it is the recorded pull requests that make
+      # the first half of that true.
+      #
+      # @param path [String] the new folder
+      # @param prs [Array<Hash>, nil]
+      # @return [String] the path, unchanged
+      def record_pull_requests(path, prs)
+        return path if prs.nil? || prs.empty?
+
+        File.write(File.join(path, Plans::PullRequests::FILENAME), Plans::PullRequests.render(prs))
+        path
+      end
+
+      # @param ordinal [OpenLanes::Plans::Ordinal]
+      # @param status [OpenLanes::Plans::Status]
+      # @param slug [String]
+      # @return [Dry::Monads::Result]
+      def build(ordinal, status, slug)
+        target = File.join(dir, OpenLanes::Plans.plan_dirname(ordinal, status, slug))
+        return Failure("already exists: #{File.basename(target)}") if File.exist?(target)
+
+        FileUtils.mkdir_p(target)
+        Plans::PlanState.for(target).state!(status.key)
+        @existing = nil
+        Success(target)
+      end
+    end
+  end
+end