openlanes 3.0.0

data/lib/openlanes/cli/start/start.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes start` — the factory as a long-lived service: the engine and
+    # the control room together, with or without any plans.
+    #
+    # It keeps the board published and the commands read, rescans the tree,
+    # and starts agents as soon as an answer, a new plan or a hand edit makes
+    # something dispatchable. It never ends on its own, not even once every
+    # plan is finished: the page creates the next plan. It ends on Stop All
+    # Local in the page, Ctrl-C or SIGTERM.
+    #
+    # The page is the only way in: every decision a person makes goes through
+    # it, and the terminal is output only. So there is no headless fallback
+    # (Redis and the control room are required, not hoped for), no dry run,
+    # no `--no-web` and no `--until-settled`.
+    class Start < Run
+      desc "web + run in one: the engine and its control room, with or without plans, until Stop All Local"
+
+      # Inherited from `run`, and meaningless here: a dry run publishes no
+      # board, and a run without its page cannot be answered.
+      @options = options.reject { %i[dry_run web until_settled].include?(it.name) }
+
+      option :rescan,
+        default: Engine::Dispatcher::RESCAN.to_s,
+        desc:    "Seconds between rescans of .plans while idle; a command from the page rescans at once"
+
+      example [
+        "                       # engine and control room, until Stop All Local or Ctrl-C",
+        "--no-open              # print the control room's URL, open no browser",
+        "--port 4848 -j 4       # somewhere other than 11000, four agents at a time",
+        "--plan 005             # only plan 005, until stopped"
+      ]
+
+      # Exit status when Redis or the control room is not there to serve.
+      UNAVAILABLE = 69
+
+      # The progress log, echoed to the terminal: the terminal is where a
+      # person watches `start` from when the page is closed, and it takes
+      # no input.
+      #
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        @rescan = Integer(options.fetch(:rescan, Engine::Dispatcher::RESCAN), exception: false)
+        refuse("--rescan takes a whole number of seconds, at least 1.", 64) unless @rescan&.positive?
+
+        tap = UI.tap_log(lambda { |message, fields|
+          next if UI.quiet
+
+          Kernel.warn(Engine::ProgressLog.render(message, **fields.slice(:plan, :status, :agent, :seconds, :round)))
+        })
+        super
+      ensure
+        UI.untap_log(tap) if tap
+      end
+
+      private
+
+      # @param _options [Hash]
+      # @param _web [OpenLanes::Web::Launcher]
+      # @return [Hash]
+      def staying(_options, _web) = { stay: true, rescan: @rescan }
+
+      # @return [void]
+      def without_live(message, _options)
+        refuse("#{message}\n\nopenlanes start needs Redis: its control room is the only way to answer the " \
+               "agents' questions. Start redis-server, or pass --redis-url. " \
+               "`openlanes run` goes on without it, headless.",
+          UNAVAILABLE)
+      end
+
+      # @return [void]
+      def without_web(web, live, _options)
+        live.close
+        refuse("The control room did not answer on #{web.url}, and openlanes start is no use without it. " \
+               "Its log: #{web.log}",
+          UNAVAILABLE)
+      end
+
+      # A project with nothing left to do opens on the idea dialog (W19).
+      #
+      # @return [String]
+      def browser_url(web, tree)
+        open = tree.subjects.reject { Engine::Dispatcher::FINISHED.include?(it.status.key) }
+        open.empty? ? "#{web.url}#start" : web.url
+      end
+
+      # What the service did, and exit 0: stopping it on purpose is not a
+      # failure, and the failed attempts it lived through are listed above
+      # the box.
+      #
+      # @return [void]
+      def finish(runner, attempts, options, seconds:)
+        puts ""
+        puts attempt_lines(attempts)
+        puts("", Engine.tally(attempts:, seconds:).render)
+        unless quiet?(options)
+          blocked = runner.blocked.map { it.feature.ordinal }
+          lines = ["Stopped. Unfinished plans keep their state; openlanes start picks them up again."]
+          lines << "Still waiting for answers: #{blocked.join(", ")}" unless blocked.empty?
+          success("#{attempts.size} invocation#{"s" unless attempts.size == 1}, " \
+                  "#{attempts.count(&:advanced?)} advanced\n\n#{lines.join("\n")}")
+        end
+        exit(0)
+      end
+    end
+  end
+end

data/lib/openlanes/cli/state/state.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes state` — a plan's `state.json`, read and signed. Agents sign
+    # through this rather than editing the file, because the command takes the
+    # lock that keeps two agents on one plan from overwriting each other.
+    module State
+      # Both subcommands name a plan and need its folder.
+      module Locating
+        private
+
+        # @param options [Hash]
+        # @return [OpenLanes::Plans::PlanState]
+        def plan_state_for(options)
+          tree = tree_for(options)
+          ordinal = Plans::Ordinal.parse(options[:plan].to_s)
+          subject = ordinal && tree.find(ordinal)
+          refuse("No plan #{options[:plan]} in #{tree.dir}.\n\nKnown: #{tree.ordinals.join(", ")}", 66) unless subject
+
+          Plans::PlanState.for(subject.feature.path)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/state/subcommands/show.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module CLI
+    module State
+      # `openlanes state show` — the plan's `state.json`, on STDOUT, so it
+      # pipes into `jq`.
+      class Show < Base
+        include Locating
+
+        desc "Print a plan's state.json"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+
+        example [
+          "--plan 003",
+          "--plan 003 | jq '.stages[] | {agent, round, status, model, seconds}'"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          $stdout.puts(JSON.pretty_generate(plan_state_for(options).read))
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/state/subcommands/sign.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module State
+      # `openlanes state sign` — an agent's ledger line, written into the
+      # plan's `state.json`.
+      class Sign < Base
+        include Locating
+
+        desc "Sign a plan's ledger: Started, Completed, Almost completed, Interrupted or Blocked"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+        option :agent, required: true, desc: "The agent signing"
+        option :round, required: true, desc: "Which round this is, as the prompt states it"
+        option :status, required: true, values: Plans::Ledger::STATUSES, desc: "Where the agent stands"
+        option :note, desc: "A word or two the harness reads, e.g. approved, rejected, technical, product"
+        option :next, desc: "Only with Completed: the agent that should go next"
+
+        example [
+          "--plan 003 --agent luke-backend --round 1 --status Started",
+          "--plan 003 --agent hansolo-reviewer --round 1 --status Completed --note approved",
+          "--plan 003 --agent yoda-writer --round 1 --status Completed --next palpatine-planner"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          state = plan_state_for(options)
+          signature = begin
+            state.sign!(agent: options[:agent],
+              round:      Integer(options[:round].to_s, exception: false) || refuse("--round must be a number", 64),
+              status:     options[:status],
+              note:       options[:note],
+              next_agent: options[:next])
+          rescue OpenLanes::Error => e
+            refuse(e.message, 64)
+          end
+
+          return if quiet?(options)
+
+          UI.line("#{signature["agent"]}: #{signature["status"]}, round #{signature["round"]} " \
+                  "in #{File.basename(state.dir)}/#{Plans::PlanState::FILENAME}")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/states/states.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes states` — the state machine, as a terminal diagram.
+    class States < Dry::CLI::Command
+      desc "Print a diagram of every state and the transitions between them"
+
+      example [""]
+
+      # @return [void]
+      def call(**) = $stdout.write(Presentation.diagram)
+    end
+  end
+end

data/lib/openlanes/cli/unblock/unblock.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes unblock NNN…` — hand a stopped plan to the agent that
+    # drains its `blocked.md`.
+    #
+    # Deliberately not part of `run`. ⭕️ and 🅱️ are {StateMachine::SETTLED}, so
+    # the loop never offers a blocked plan to anybody, and that is the property
+    # that makes the state mean anything: the plan waits for a human, and no
+    # agent quietly decides otherwise. Answers arriving is not a fact the tool
+    # can observe, so a human typing this command *is* the signal, and there is
+    # nothing else that could produce it.
+    class Unblock < Base
+      # The agent that knows the shape of `blocked.md`.
+      DEFAULT_AGENT = "lando-broker"
+
+      # What each token turned out to be, for whoever has to fix it.
+      PROBLEMS = {
+        missing:     "no plan of that number",
+        not_blocked: "no blocked.md, so there is nothing to drain"
+      }.freeze
+
+      desc "Fold answered blocks into a plan's documents and retire blocked.md"
+
+      argument :plans,
+        type:     :array,
+        required: true,
+        desc:     "Which plans to drain: NNN or NNN.MM, e.g. 003 005.01"
+
+      dry_run_option "Invoke no agent; print the questions still open"
+      option :agent, default: DEFAULT_AGENT, desc: "Hand the folder to a different agent"
+      option :root, desc: "Repository root the agent works in (default: the .plans parent)"
+
+      example [
+        "003 -n             # what 003 is still waiting on",
+        "003                # fold in whatever has been answered",
+        "003,005            # both"
+      ]
+
+      # @param plans [Array<String>]
+      # @param options [Hash]
+      # @return [void]
+      def call(plans:, **options)
+        tree = tree_for(options)
+        quiet?(options)
+        unblocker = Lifecycle.unblocker(tree:,
+          agent: agent_for(options),
+          root: options[:root],
+          commit: !dry_run?(options),
+          executor: Execution.executor(root: options[:root] || File.dirname(tree.dir),
+            dry_run: dry_run?(options)))
+
+        targets = unblocker.resolve(plans)
+        refused(targets, tree, options)
+        subjects = targets.select(&:drainable?).map(&:subject)
+        exit(worst(targets, [])) if subjects.empty?
+
+        credentials_warning if !dry_run?(options) && !quiet?(options)
+        preflight(subjects, unblocker, options)
+
+        outcomes = Execution.on_interrupt { unblocker.call(subjects) }
+        outcomes.each { |outcome| report(outcome, options) }
+        footer(outcomes, options) unless quiet?(options)
+        exit(worst(targets, outcomes))
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [OpenLanes::Agents::Agent]
+      def agent_for(options)
+        name = options.fetch(:agent, DEFAULT_AGENT)
+        agents = OpenLanes::Agents.registry
+        agents.find(name) or
+          refuse("No agent called #{name}.\n\nKnown: #{agents.all.map(&:name).join(", ")}", 65)
+      end
+
+      # A number that names no folder, or a folder that was never stopped, is
+      # refused rather than skipped. Whoever typed this believes an answer has
+      # arrived; running against a folder nobody blocked and saying nothing is
+      # how you come back later to a plan nobody touched and no record of why.
+      #
+      # Every bad token is reported, not just the first, because stopping at
+      # the first one hides the rest of the answer.
+      #
+      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param options [Hash]
+      # @return [void]
+      def refused(targets, tree, options)
+        problems = targets.reject(&:drainable?)
+        return if problems.empty?
+
+        problems.each do |target|
+          state = target.subject ? target.subject.status.key : "unknown"
+          puts "#{target.token}\t#{state}\t0 open\t#{PROBLEMS.fetch(target.problem)}"
+        end
+        return if quiet?(options)
+
+        error("#{problems.size} of the plans named cannot be drained:\n\n" +
+              problems.map { |t| "  #{t.token} — #{PROBLEMS.fetch(t.problem)}" }.join("\n") +
+              "\n\nThe tree holds: #{tree.ordinals.join(", ")}")
+      end
+
+      # What each folder is waiting on, said BEFORE the agent is invoked.
+      #
+      # This is the half that was missing. A real run hands the folder to an
+      # agent that can take a quarter of an hour, and until it came back the
+      # terminal showed nothing at all — a run that had found nothing to do and
+      # a run still working looked exactly alike.
+      #
+      # @param subjects [Array<OpenLanes::Plans::Subject>]
+      # @param unblocker [OpenLanes::Lifecycle::Unblocker]
+      # @param options [Hash]
+      # @return [void]
+      def preflight(subjects, _unblocker, options)
+        return if quiet?(options)
+
+        subjects.each do |subject|
+          questions = Lifecycle::Unblocker.questions(subject)
+          answered = questions.count(&:answered)
+          say("#{paint(subject.feature.ordinal.to_s, :bright_black)} #{subject.status.emoji} " \
+              "#{subject.feature.title} — #{summary(questions.size, answered)}")
+          detail(subject, questions)
+        end
+      end
+
+      # @param open [Integer]
+      # @param answered [Integer]
+      # @return [String]
+      def summary(open, answered)
+        return "nothing open" if open.zero?
+
+        "#{open} open, #{answered.zero? ? "none answered yet" : "#{answered} with an answer waiting"}"
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param questions [Array<OpenLanes::Lifecycle::Unblocker::Question>]
+      # @return [void]
+      def detail(subject, questions)
+        if subject.unreadable_block?
+          say("  #{paint("blocked.md names no `## B<n>` question, so nothing here can be drained", :red)}",
+            bullet: " ")
+          say("  #{paint("Number each open question `## B1`, `## B2`, and each answer `## A1`, `## A2`.", :yellow)}",
+            bullet: " ")
+        elsif questions.empty?
+          say("  #{paint("nothing left open", :green)}", bullet: " ")
+        else
+          questions.each { |question| say("  #{paint(question.to_s, :yellow)}", bullet: " ") }
+        end
+      end
+
+      # One plan, after the fact: the deliverable line on STDOUT, and what
+      # changed on STDERR.
+      #
+      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
+      # @param options [Hash]
+      # @return [void]
+      def report(outcome, options)
+        moved = movement(outcome, !dry_run?(options))
+        puts "#{outcome.ordinal}\t#{outcome.ok ? outcome.subject.status.key : "failed"}\t" \
+             "#{outcome.after.size} open\t#{moved}\t#{outcome.note}"
+        # A dry run changed nothing, so the preflight above it is still the
+        # whole truth. Printing the same three lines again reads as a second
+        # pass that found the same thing, which is not what happened.
+        return if quiet?(options) || dry_run?(options)
+
+        say("#{paint(outcome.ordinal.to_s, :bright_black)} #{outcome.subject.status.emoji} " \
+            "#{outcome.subject.feature.title} — #{paint(moved, outcome.ok ? :green : :red)}")
+        detail(outcome.subject, outcome.after)
+      end
+
+      # What the file says happened, rather than what the agent claims. The
+      # questions are counted off disk on both sides of the run.
+      #
+      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
+      # @param commit [Boolean]
+      # @return [String]
+      def movement(outcome, commit)
+        return "failed" unless outcome.ok
+        return "not attempted" unless commit
+        return "blocked.md retired" if outcome.cleared?
+        return "nothing folded" if outcome.folded.empty?
+
+        "folded #{outcome.folded.map { |n| "B#{n}" }.join(", ")}"
+      end
+
+      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
+      # @param options [Hash]
+      # @return [void]
+      def footer(outcomes, options)
+        failed = outcomes.reject(&:ok)
+
+        if dry_run?(options)
+          warn("Dry run: no agent was invoked, and #{outcomes.size} " \
+               "plan#{"s" unless outcomes.size == 1} #{outcomes.size == 1 ? "is" : "are"} unchanged.\n" \
+               "Re-run without --dry-run to fold in whatever has been answered.")
+          return
+        end
+
+        return error(failed.map { |o| "#{o.ordinal}: #{o.note}" }.join("\n")) unless failed.empty?
+
+        cleared = outcomes.count(&:cleared?)
+        folded = outcomes.sum { |o| o.folded.size }
+        waiting = outcomes.sum { |o| o.after.size }
+        success("#{folded} question#{"s" unless folded == 1} folded in · " \
+                "#{cleared} plan#{"s" unless cleared == 1} out of the block · " \
+                "#{waiting} still waiting on a human." +
+                (if folded.zero?
+                   "\n\nNothing moved. An answer has to be written into blocked.md as its own " \
+                     "`## A<n>` section, answering the `## B<n>` of the same number, before " \
+                     "there is anything to fold."
+                 else
+                   ""
+                 end))
+      end
+
+      # The most serious thing that happened, as an exit status. A tree that
+      # was partly drained still exits non-zero when part of it could not be.
+      #
+      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
+      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
+      # @return [Integer]
+      def worst(targets, outcomes)
+        problems = targets.map(&:problem)
+        return 66 if problems.include?(:missing)
+        return 65 if problems.include?(:not_blocked)
+        return 1 unless outcomes.all?(&:ok)
+
+        0
+      end
+    end
+  end
+end

data/lib/openlanes/cli/version/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes version`
+    class Version < Dry::CLI::Command
+      desc "Print the version and exit"
+
+      # @return [void]
+      def call(**) = puts("openlanes #{OpenLanes::VERSION}")
+    end
+  end
+end

data/lib/openlanes/cli/web/web.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes web` — the control room's API server on its own. `openlanes run`
+    # starts one beside the engine; this is that server, and with `--demo`
+    # the same server over a pretend engine, for Cypress and front-end work.
+    class Web < Base
+      desc "Serve the control room page and its API on 127.0.0.1"
+
+      option :port,
+        default: OpenLanes::Web::DEFAULT_PORT.to_s,
+        desc:    "Port to listen on"
+      option :redis_url,
+        desc: "Redis the engine publishes to (default: $OPENLANES_REDIS_URL, else .openlanes.yml redis_url, else $REDIS_URL, " \
+              "else #{Live::DEFAULT_URL})"
+      option :open,
+        type:    :boolean,
+        default: true,
+        desc:    "Open the page in the browser; --no-open prints the URL only"
+      option :demo,
+        type:    :boolean,
+        default: false,
+        desc:    "Serve a sample run that moves and answers commands, with no agents. " \
+                 "Uses Redis when it answers, an in-memory store when it does not"
+
+      example [
+        "                 # serve the live run of this checkout",
+        "--demo --no-open # the sample run, for Cypress and npm run dev",
+        "--port 4848      # somewhere other than 11000"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        tree = tree_for(options)
+        root = File.dirname(tree.dir)
+        url = Live.redis_url(option: redis_url_option(options), config: Config.current)
+        stores = stores_for(url, options)
+        node = Live::Node.current(root:)
+        keys = Live.keys(root:, node:)
+        keys = keys.with(repo: "demo/#{keys.repo}") if options[:demo]
+        demo = OpenLanes::Web.demo(store: stores.current, keys:).start if options[:demo]
+        context = OpenLanes::Web.context(stores:, keys:, plans_dir: tree.dir, url: stores.current.url, node:, demo:)
+        server = OpenLanes::Web.server(app: OpenLanes::Web.app(context), context:, port: options[:port])
+        serve(server, options, keys:, node:, url: stores.current.url)
+      ensure
+        demo&.stop
+      end
+
+      private
+
+      # `--redis-url`, else the URL `openlanes run` hands its server through the
+      # environment, so a password never shows in `ps`. Both are passed to
+      # {Live.redis_url} as the option, which keeps the rest of its order.
+      #
+      # @param options [Hash]
+      # @param env [Hash]
+      # @return [String, nil]
+      def redis_url_option(options, env: ENV)
+        [options[:redis_url], env[OpenLanes::Web::Launcher::REDIS_URL_ENV]].find { !it.to_s.strip.empty? }
+      end
+
+      # @return [OpenLanes::Web::Stores]
+      def stores_for(url, options)
+        store = Live.connect(url)
+        store.close
+        OpenLanes::Web::Stores.new { Live.store(url) }
+      rescue Live::Unavailable => e
+        unless options[:demo]
+          refuse("#{e.message}\n\nThe page reads the run from Redis. Start redis-server, pass --redis-url, " \
+                 "or try --demo.",
+            69)
+        end
+        warn("#{e.message}\n\nThe demo keeps its board in memory instead: this page only, no other machine.") unless quiet?(options)
+        OpenLanes::Web::Stores.shared(Live.memory_store)
+      end
+
+      # Listen until INT or TERM.
+      #
+      # @return [void]
+      def serve(server, options, keys:, node:, url:)
+        begin
+          server.start
+        rescue Errno::EADDRINUSE
+          refuse("Port #{options[:port]} is taken: another `openlanes web` may already be serving. " \
+                 "Pass --port to use another.",
+            69)
+        end
+        %w[INT TERM].each { |name| Signal.trap(name) { Thread.new { server.stop } } }
+        unless quiet?(options)
+          info("Control room: #{server.url}#{" (demo)" if options[:demo]}\n" \
+               "Redis: #{Live.mask(url)} as #{node.label} (#{keys.node}), repository #{keys.repo}")
+        end
+        OpenLanes::Web.open(server.url) if options[:open]
+        server.wait
+      end
+    end
+  end
+end

data/lib/openlanes/cli/worktree/worktree.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes worktree` — create and seed worktrees for plans.
+    class Worktree < Base
+      desc "Create and seed a worktree for a plan"
+
+      argument :plan,
+        required: true,
+        desc:     "Plan ordinal (e.g. 002, 002.00, or a plan folder name)"
+
+      option :skip_seed,
+        type:    :boolean,
+        default: false,
+        desc:    "Create the worktree but skip seeding it with .env and credential files"
+
+      example [
+        "002                         # create/seed the worktree for plan 002.00",
+        "002.01                      # create/seed the worktree for plan 002.01",
+        "002.00-⚪️ → update-dsl      # find the plan by its folder name",
+        "--skip-seed 003             # create the worktree but don't seed it"
+      ]
+
+      # @param plan [String] plan identifier
+      # @param options [Hash]
+      # @return [void]
+      def call(plan:, **options)
+        tree = tree_for(options)
+        is_quiet = quiet?(options)
+
+        feature = resolve_plan(tree, plan)
+        unless feature
+          refuse("Could not find plan: #{plan}", 66)
+        end
+
+        root = File.dirname(tree.dir)
+        worktree = OpenLanes::Vcs.worktree(root:)
+
+        checkout = worktree.checkout_for(feature)
+
+        return if is_quiet
+
+        if checkout.created?
+          puts("✓ Created worktree for #{feature.ordinal}: #{checkout.path}")
+        else
+          puts("✓ Using existing worktree for #{feature.ordinal}: #{checkout.path}")
+        end
+
+        unless options[:skip_seed]
+          seeded = worktree.seed(checkout.path)
+          if seeded
+            puts("✓ Seeded with .env and credential files")
+          else
+            warn("⚠ Could not seed worktree, see above for details")
+          end
+        end
+
+        puts("")
+        success("Worktree ready for #{feature.ordinal}")
+        puts("Path: #{checkout.path}")
+        puts("Branch: #{checkout.branch}")
+      end
+
+      private
+
+      # Find the plan that matches the given identifier.
+      #
+      # @param tree [OpenLanes::Plans::Tree] plans directory wrapper
+      # @param plan [String] ordinal, folder name, or slug
+      # @return [OpenLanes::Plans::Feature, nil]
+      def resolve_plan(tree, plan)
+        # Try parsing as an ordinal first
+        ordinal = ::OpenLanes::Plans::Ordinal.parse(plan)
+        if ordinal
+          found = tree.features.find { |f| f.ordinal == ordinal }
+          return found if found
+        end
+
+        # Try matching by folder name
+        tree.features.find { |f| f.dirname == plan }
+      end
+    end
+  end
+end