openlanes 3.0.0

data/lib/openlanes/web/events.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Web
+    # One page's event stream (contract.md, `GET /api/events`): a `board`
+    # event whenever any node's snapshot `seq` changes, a `reply` event for
+    # each reply the engine writes, and a `: ping` comment so proxies and the
+    # browser keep the connection open.
+    #
+    # Polled rather than blocked on: a blocking read would hold the thread's
+    # connection for the length of the wait, and the board has to be looked
+    # at every tick anyway.
+    #
+    # A reply carries its stream id as the event's `id:`, so a browser that
+    # reconnects sends `Last-Event-ID` and gets what it missed. The stream
+    # opens with a `cursor` event carrying the id it starts from, so a
+    # browser that drops before the first reply still has one to send;
+    # without it, replies written during that gap were skipped.
+    class Events
+      # @param context [OpenLanes::Web::Context]
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      # @param last_id [String, nil] the `Last-Event-ID` the browser sent
+      # @param clock [Proc] seconds, monotonic
+      # @param sleeper [Proc] waits the given seconds between ticks
+      def initialize(context:, store:, last_id: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+        sleeper: ->(seconds) { sleep seconds })
+        @context = context
+        @store = store
+        @keys = context.keys
+        @last_id = last_id.to_s.match?(/\A\d+-\d+\z/) ? last_id : nil
+        @clock = clock
+        @sleeper = sleeper
+      end
+
+      # Write events to +out+ until the browser leaves, the server stops, or
+      # the context's lifetime runs out.
+      #
+      # @param out [#<<, #closed?]
+      # @return [void]
+      def run(out)
+        started = @clock.call
+        pinged = started
+        cursor = @last_id || newest_reply
+        out << self.class.frame("cursor", { id: cursor }, id: cursor)
+        seqs = nil
+        until over?(out, started)
+          seqs = board(out, seqs)
+          cursor = replies(out, cursor)
+          pinged = ping(out) if @clock.call - pinged >= @context.ping_every
+          @sleeper.call(@context.tick)
+        end
+      rescue Live::Unavailable => e
+        # Ending the stream is the right answer: the page reconnects with
+        # backoff and shows itself as reconnecting meanwhile.
+        out << ": #{e.message.tr("\n", " ")}\n\n"
+      end
+
+      # @param event [String]
+      # @param data [Object]
+      # @param id [String, nil]
+      # @return [String] one server-sent event
+      def self.frame(event, data, id: nil) = "#{"id: #{id}\n" if id}event: #{event}\ndata: #{JSON.generate(data)}\n\n"
+
+      private
+
+      # @return [Boolean]
+      def over?(out, started)
+        out.closed? || @context.stopping.true? || (@context.lifetime && @clock.call - started >= @context.lifetime)
+      end
+
+      # @return [Array] the seqs now, after sending the board if they changed
+      def board(out, seqs)
+        board = Live.board(store: @store, keys: @keys)
+        now = [board[:me], *board[:others]].compact.map { [it.dig("node", "id"), it.dig("node", "checkout"), it["seq"]] }
+        out << self.class.frame("board", board) unless now == seqs
+        now
+      end
+
+      # @return [String] the last reply id sent
+      def replies(out, cursor)
+        Live.replies(store: @store, keys: @keys, after: cursor).each do |id, reply|
+          out << self.class.frame("reply", reply, id:)
+          cursor = id
+        end
+        cursor
+      end
+
+      # @return [Float] when it pinged
+      def ping(out)
+        out << ": ping\n\n"
+        @clock.call
+      end
+
+      # Replies already written before this page connected are not news.
+      # An empty stream starts from `0-0` rather than `0`: the browser echoes
+      # it back as `Last-Event-ID`, and only a full stream id is accepted.
+      #
+      # @return [String]
+      def newest_reply = @store.xrevrange(@keys.replies, count: 1).first&.id || "0-0"
+    end
+  end
+end

data/lib/openlanes/web/launcher.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "tmpdir"
+
+module OpenLanes
+  module Web
+    # The API server beside a `openlanes run` (W7): `openlanes web` as a process
+    # of its own, in its own process group, so a crash in one never takes the
+    # other with it and stopping the run stops the server and nothing else.
+    #
+    #   web = Web.launcher(root:, plans_dir:, port: 11000, redis_url:).start
+    #   web.ready?   # => true once /healthz answers
+    #   web.stop
+    class Launcher
+      # The executable, from this gem rather than whatever is on PATH.
+      EXE = File.join(GEM_ROOT, "exe", "openlanes")
+
+      # Where the server finds this run's Redis. The URL can carry a password,
+      # and argv is world-readable through `ps`; a child's environment is not.
+      REDIS_URL_ENV = "OPENLANES_REDIS_URL"
+
+      # Seconds {#start} waits for `/healthz`.
+      READY_WITHIN = 10.0
+
+      # Seconds {#stop} gives the server after TERM before KILL.
+      STOP_WITHIN = 5.0
+
+      # @param root [String] the checkout the run works in
+      # @param plans_dir [String]
+      # @param port [Integer]
+      # @param redis_url [String]
+      # @param log [String] where the server's output goes
+      # @param ready_within [Float]
+      # @param probe [Proc, nil] answers whether the server is up; `/healthz` by default
+      def initialize(root:, plans_dir:, port:, redis_url:, log: default_log(root), ready_within: READY_WITHIN, probe: nil)
+        @root = root
+        @plans_dir = plans_dir
+        @port = Integer(port)
+        @redis_url = redis_url
+        @log = log
+        @ready_within = ready_within
+        @probe = probe || method(:healthy?)
+      end
+
+      # @return [String]
+      attr_reader :log
+
+      # @return [Integer, nil]
+      attr_reader :pid
+
+      # @return [String]
+      def url = "http://#{HOST}:#{@port}"
+
+      # @return [Array<String>] what is spawned; the Redis URL is in {#env}, never here
+      def argv
+        [EXE, "web", "--port", @port.to_s, "--no-open", "--dir", @plans_dir]
+      end
+
+      # @return [Hash{String => String}] added to the server's environment
+      def env = { REDIS_URL_ENV => @redis_url }
+
+      # Spawn the server and wait for it to answer.
+      #
+      # @return [self]
+      def start
+        @pid = Process.spawn(env, *argv, chdir: @root, pgroup: true, in: File::NULL, %i[out err] => [@log, "a"])
+        @ready = wait_until_ready
+        self
+      end
+
+      # @return [Boolean] whether `/healthz` answered within the wait
+      def ready? = @ready == true
+
+      # TERM to the server's process group, then KILL if it lingers.
+      #
+      # @return [void]
+      def stop
+        return unless @pid
+
+        signal("TERM")
+        deadline = monotonic + STOP_WITHIN
+        sleep 0.05 while alive? && monotonic < deadline
+        signal("KILL") if alive?
+        reap
+        @pid = nil
+      end
+
+      private
+
+      # @return [Boolean]
+      def wait_until_ready
+        deadline = monotonic + @ready_within
+        until monotonic >= deadline
+          return true if @probe.call
+          return false unless alive?
+
+          sleep 0.1
+        end
+        false
+      end
+
+      # @return [Boolean]
+      def healthy?
+        Net::HTTP.start(HOST, @port, open_timeout: 0.5, read_timeout: 1) { it.get("/healthz").code == "200" }
+      rescue SystemCallError, IOError, Net::OpenTimeout, Net::ReadTimeout
+        false
+      end
+
+      # @return [Boolean]
+      def alive?
+        Process.waitpid(@pid, Process::WNOHANG).nil?
+      rescue Errno::ECHILD
+        false
+      end
+
+      # @return [void]
+      def signal(name)
+        Process.kill(name, -@pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      # Blocks: after KILL the child is gone or about to be, and a
+      # non-blocking wait that runs before the kernel has finished with it
+      # returns nil and leaves a zombie behind. ECHILD means {#alive?}
+      # already reaped it.
+      #
+      # @return [void]
+      def reap
+        Process.waitpid(@pid)
+      rescue Errno::ECHILD
+        nil
+      end
+
+      # @return [Float]
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # @return [String]
+      def default_log(root) = File.join(Dir.tmpdir, "openlanes-web-#{File.basename(root)}.log")
+    end
+  end
+end

data/lib/openlanes/web/server.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "puma"
+require "puma/log_writer"
+require "puma/server"
+
+module OpenLanes
+  module Web
+    # The app on Puma, multi-threaded because every open page holds one
+    # thread for its event stream, and bound to {HOST} only.
+    #
+    #   server = Web.server(app:, context:, port: 11000).start
+    #   server.url   # => "http://127.0.0.1:11000"
+    #   server.wait  # until #stop
+    class Server
+      # Threads: one per open event stream plus the requests beside them.
+      MIN_THREADS = 2
+      MAX_THREADS = 64
+
+      # Seconds Puma waits for open streams after {#stop}. They notice the
+      # context's `stopping` within a tick; this is the backstop.
+      SHUTDOWN_AFTER = 2
+
+      # @param app [#call]
+      # @param context [OpenLanes::Web::Context]
+      # @param port [Integer] 0 for any free port
+      # @param host [String]
+      # @param log [IO] where Puma writes its errors
+      def initialize(app:, context:, port: DEFAULT_PORT, host: HOST, log: $stderr)
+        @app = app
+        @context = context
+        @port = Integer(port)
+        @host = host
+        @log = log
+      end
+
+      # @return [String]
+      attr_reader :host
+
+      # Listen, and serve on Puma's own threads.
+      #
+      # @return [self]
+      # @raise [Errno::EADDRINUSE] when the port is taken
+      def start
+        @puma = Puma::Server.new(@app,
+          nil,
+          min_threads:          MIN_THREADS,
+          max_threads:          MAX_THREADS,
+          force_shutdown_after: SHUTDOWN_AFTER,
+          log_writer:           Puma::LogWriter.new(File.open(File::NULL, "w"), @log))
+        @puma.add_tcp_listener(@host, @port)
+        @thread = @puma.run
+        self
+      end
+
+      # @return [Integer] the port listened on, the real one when 0 was asked
+      def port = @puma&.connected_ports&.first || @port
+
+      # @return [String]
+      def url = "http://#{@host}:#{port}"
+
+      # Block until the server stops.
+      #
+      # @return [void]
+      def wait = @thread&.join
+
+      # Stop listening, end every open stream, and wait for Puma.
+      #
+      # @return [void]
+      def stop
+        @context.stopping.make_true
+        @puma&.stop(true)
+        @context.stores.close
+      end
+    end
+  end
+end

data/lib/openlanes/web/stores.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Web
+    # One store per Puma thread. {Live::Store} holds a single Redis
+    # connection, which two threads must not share: an event stream polling
+    # on one thread and a command posted on another would interleave their
+    # replies on the wire.
+    #
+    # Puma's threads are pooled, so the map is bounded by the pool's size.
+    class Stores
+      # Every thread gets the same store: {Live::MemoryStore}, which lives in
+      # this process and is already synchronised.
+      #
+      # @param store [OpenLanes::Live::MemoryStore]
+      # @return [OpenLanes::Web::Stores]
+      def self.shared(store) = new { store }
+
+      # @yieldreturn [OpenLanes::Live::Store] a new store
+      def initialize(&factory)
+        @factory = factory
+        @mutex = Mutex.new
+        @by_thread = {}
+      end
+
+      # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      def current = @mutex.synchronize { @by_thread[Thread.current] ||= @factory.call }
+
+      # @return [void]
+      def close
+        stores = @mutex.synchronize { @by_thread.values.uniq.tap { @by_thread.clear } }
+        stores.each(&:close)
+      end
+    end
+  end
+end

data/lib/openlanes/web.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "securerandom"
+
+module OpenLanes
+  # The control room's API server (plan 004, W3, W7): Sinatra on a threaded
+  # Puma, bound to 127.0.0.1. It holds no run state. Everything it shows is
+  # read from Redis through {Live}, and everything it is told goes back
+  # there as a command for the engine, so a restarted server loses nothing.
+  #
+  #   context = Web.context(stores:, keys:, plans_dir:, url:)
+  #   server  = Web.server(app: Web.app(context), context:, port: 11000).start
+  #   server.wait
+  module Web
+    # Where the gem is, whether run from a checkout or installed.
+    GEM_ROOT = File.expand_path("../..", __dir__)
+
+    # The built page, which the gem ships (W3).
+    DIST = File.join(GEM_ROOT, "web", "dist")
+
+    # The sample board the page's own tests type-check, and {Demo} replays.
+    FIXTURE = File.join(GEM_ROOT, "web", "src", "api", "fixtures", "board.json")
+
+    # Where the server listens unless told otherwise (contract.md).
+    DEFAULT_PORT = 11_000
+
+    # Loopback only: the page can stop agents, and nothing off this machine
+    # may reach it (W3).
+    HOST = "127.0.0.1"
+
+    module_function
+
+    # @param stores [OpenLanes::Web::Stores]
+    # @param keys [OpenLanes::Live::Keys]
+    # @param plans_dir [String] absolute path of the `.plans` directory
+    # @param url [String] the Redis address, shown masked by `/healthz`
+    # @param rest [Hash] {Context}'s other fields
+    # @return [OpenLanes::Web::Context]
+    def context(stores:, keys:, plans_dir:, url:, **rest)
+      Context.new(stores:, keys:, plans_dir:, url:, csrf: SecureRandom.hex(32), **rest)
+    end
+
+    # @param context [OpenLanes::Web::Context]
+    # @return [Class] a Rack application
+    def app(context) = App.serving(context)
+
+    # @param app [#call]
+    # @param context [OpenLanes::Web::Context]
+    # @param port [Integer]
+    # @return [OpenLanes::Web::Server]
+    def server(app:, context:, port: DEFAULT_PORT, **) = Server.new(app:, context:, port:, **)
+
+    # @return [OpenLanes::Web::Demo]
+    def demo(**) = Demo.new(**)
+
+    # @return [OpenLanes::Web::Launcher]
+    def launcher(**) = Launcher.new(**)
+
+    # Whether a browser can be opened here (W1): not under CI, not over
+    # SSH, not without a terminal, and on Linux only with a display.
+    #
+    # @param env [Hash]
+    # @param tty [Boolean] whether a person is at the terminal
+    # @param os [String] `RbConfig::CONFIG["host_os"]`
+    # @return [Boolean]
+    def display?(env: ENV, tty: $stderr.tty?, os: RbConfig::CONFIG["host_os"])
+      return false if !tty || present?(env["CI"]) || present?(env["SSH_CONNECTION"]) || present?(env["SSH_TTY"])
+      return true if os.match?(/darwin|mswin|mingw/)
+
+      present?(env["DISPLAY"]) || present?(env["WAYLAND_DISPLAY"])
+    end
+
+    # Open +url+ in the browser, when there is one to open.
+    #
+    # @param url [String]
+    # @param display [Boolean]
+    # @return [Boolean] whether a browser was asked to open it
+    def open(url, display: display?)
+      return false unless display
+
+      require "launchy"
+      Launchy.open(url)
+      true
+    rescue Launchy::Error, SystemCallError
+      false
+    end
+
+    # @return [Boolean]
+    def present?(value) = !value.to_s.strip.empty?
+  end
+end

data/lib/openlanes.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Help screens come from dry-cli-help, which prepends itself to Dry::CLI the
+# moment it loads, so it has to load before the registry's `help` block runs.
+require "dry/cli"
+require "dry/cli/help"
+
+require "dry/inflector"
+require "fileutils"
+require "shellwords"
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "openlanes"  => "OpenLanes",
+  "api"        => "API",
+  "cli"        => "CLI",
+  "github"     => "GitHub",
+  "issue"      => "Issues",
+  "list_plans" => "ListPlans",
+  "unit"       => "Units",
+  "ui"         => "UI"
+)
+loader.collapse("#{__dir__}/openlanes/support")
+loader.collapse("#{__dir__}/openlanes/cli/create")
+loader.collapse("#{__dir__}/openlanes/cli/docs")
+loader.collapse("#{__dir__}/openlanes/cli/eval")
+loader.collapse("#{__dir__}/openlanes/cli/index")
+loader.collapse("#{__dir__}/openlanes/cli/init")
+loader.collapse("#{__dir__}/openlanes/cli/list_plans")
+loader.collapse("#{__dir__}/openlanes/cli/run")
+loader.collapse("#{__dir__}/openlanes/cli/start")
+loader.collapse("#{__dir__}/openlanes/cli/states")
+loader.collapse("#{__dir__}/openlanes/cli/unblock")
+loader.collapse("#{__dir__}/openlanes/cli/version")
+loader.collapse("#{__dir__}/openlanes/cli/web")
+loader.collapse("#{__dir__}/openlanes/cli/worktree")
+loader.collapse("#{__dir__}/openlanes/cli/agents/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/linear/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/mail/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/state/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/resync/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/skills/subcommands")
+loader.ignore("#{__dir__}/openlanes/cli/linear/linear.rb")
+loader.ignore("#{__dir__}/openlanes/cli/mail/mail.rb")
+loader.ignore("#{__dir__}/openlanes/cli/state/state.rb")
+loader.ignore("#{__dir__}/openlanes/linear/mapping.rb")
+loader.setup
+
+# Spec → Plan → Build.
+#
+# Three phases, each with a file that proves it happened, and a guarded state
+# machine that refuses to let a plan folder claim a phase it has not reached.
+#
+#   spec   ⚪️ New          spec.md
+#   plan   ⭐️ Ready        plan.md
+#   build  🟡 → ✅         pull-requests.md
+#
+# The conventions are not documented anywhere else by hand: the status
+# vocabulary, the numbering rules and the transition table live here and are
+# emitted by `openlanes docs`. Three hand-maintained copies of that table
+# have already drifted apart, which is why there is now exactly one.
+
+# © 2026 Konstantin Gredeskoul
+module OpenLanes
+  # The folder every project keeps its plans in.
+  PLANS_DIR = ENV.fetch("PLANS_DIR", ".plans")
+
+  # Prefix for a pull request that deliberately implements no plan —
+  # dependency bumps, CI work, hotfixes, developer tooling.
+  #
+  # Lower case, and not a number, so it cannot be mistaken for one. It used to
+  # be `DEV.00`, which read as a plan number and sorted among them.
+  NO_PLAN_PREFIX = "dev"
+
+  # What it used to be. Titles still wearing it are rewritten rather than
+  # skipped as already-prefixed.
+  STALE_NO_PLAN_PREFIX = "DEV.00"
+
+  # Prefix for a pull request that implements *something* nothing could name.
+  # Unlike `dev` this asserts nothing; it marks a question left open.
+  NONE_PREFIX = "none"
+
+  # @return [Dry::Inflector] shared Inflector
+  def self.inflector = @inflector ||= ::Dry::Inflector.new
+
+  # Move a directory, preferring `git mv` so its history follows it.
+  #
+  # Both the state machine and `resync dirs` move plan folders, and a folder
+  # that loses its history because one of them used `FileUtils` is a folder
+  # nobody can `git log`.
+  #
+  # @param source [String] absolute
+  # @param target [String] absolute
+  # @return [Boolean] false when the target was already occupied
+  def self.move_directory(source, target)
+    return false if File.exist?(target)
+
+    parent = File.dirname(source)
+    tracked = system("git",
+      "-C",
+      parent,
+      "ls-files",
+      "--error-unmatch",
+      source,
+      out: File::NULL,
+      err: File::NULL)
+    moved = tracked && system("git",
+      "-C",
+      parent,
+      "mv",
+      source,
+      target,
+      out: File::NULL,
+      err: File::NULL)
+    FileUtils.mv(source, target) unless moved
+    true
+  end
+
+  # Plan numbers visible in `.plans` on a git ref, without checking it out.
+  #
+  # A pull request's branch is the only place that knows how far the sequence
+  # had got when the work started, and branches are not all rebased onto the
+  # same main. Reading the ref directly costs one `ls-tree` and no worktree.
+  #
+  # @param root [String] repository root
+  # @param ref [String] a branch name; `origin/` is tried first
+  # @return [Array<OpenLanes::Plans::Ordinal>] possibly empty
+  def self.plans_on_ref(root, ref)
+    ["origin/#{ref}", ref].each do |candidate|
+      out = `git -C #{root.shellescape} ls-tree -d --name-only #{candidate.shellescape} #{PLANS_DIR}/ 2>/dev/null`
+      next if out.to_s.strip.empty?
+
+      return out.lines.filter_map { |line| Plans::Ordinal.from_dirname(File.basename(line.strip)) }
+    end
+    []
+  end
+
+  # The agent that writes a specification for work that already shipped.
+  # Named here rather than in the CLI so the definition file stays the single
+  # source of truth about who does what.
+  RETROACTIVE_WRITER = "yoda-writer"
+
+  class Error < StandardError; end
+end
+
+# plans/status.rb and plans/feature.rb define methods on OpenLanes::Plans (`status`,
+# `plan_dirname`, `titleize` and friends) beside the class each is named for.
+# Zeitwerk loads a file when its constant is first named, and a caller of
+# `Plans.status` names no constant, so without this those methods exist
+# or not depending on what happened to load first.
+%w[status feature].each { |name| loader.load_file("#{__dir__}/openlanes/plans/#{name}.rb") }

data/openlanes.gemspec

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "lib/openlanes/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "openlanes"
+  spec.version = OpenLanes::VERSION
+  spec.authors = ["Konstantin Gredeskoul"]
+  spec.email = ["kigster@gmail.com"]
+
+  spec.summary = "Agentic specification-driven development: spec, plan, build, review"
+  spec.description = <<~TEXT
+    Keeps a project's specifications, plans and pull requests joined up, and
+    drives specialist agents over them in parallel. A feature's state is its
+    folder name under .plans, so a transition renames a directory rather than
+    updating a row, and nothing can claim a phase whose document is missing.
+  TEXT
+  spec.homepage = "https://github.com/kigster/openlanes"
+
+  spec.required_ruby_version = ">= 3" # rubocop:disable Gemspec/RequiredRubyVersion -- the floor users get, not the Ruby the cops lint for
+
+  spec.metadata = {
+    "homepage_uri"          => spec.homepage,
+    "source_code_uri"       => spec.homepage,
+    "rubygems_mfa_required" => "true"
+  }
+
+  # Globbed rather than taken from `git ls-files`, so building the gem does not
+  # require a git checkout — the same reason the executables resolve their own
+  # bundle rather than trusting the caller's working directory.
+  spec.files = Dir.chdir(__dir__) do
+    # web/dist is the built page the API server serves; board.json is what
+    # `openlanes web --demo` replays.
+    # Source maps stay out: they double the page's size for nobody who installs it.
+    globbed = Dir.glob(["*.gemspec", "lib/**/*.rb", "agents/*.md", "schemas/*.json", "evals/cases/**/*", "skills/**/*",
+                        "exe/*", "bin/*", "web/dist/**/*", "web/src/api/fixtures/board.json"])
+    globbed.select { |f| File.file?(f) && !f.end_with?(".map") }
+  end
+
+  # A gem built without the page installs a control room that serves a 404.
+  # Only `gem build` is stopped (which `rake build` and `just publish` run):
+  # Bundler, rspec and rubocop load this file too, in checkouts that have
+  # never run npm. `abort` rather than `raise`, because Gem::Specification.load
+  # swallows a StandardError into a warning and a puzzling "not found".
+  building = File.basename($PROGRAM_NAME) == "gem" && ARGV.first == "build"
+  if building && !File.file?(File.join(__dir__, "web", "dist", "index.html"))
+    abort "openlanes.gemspec: web/dist/index.html is missing, so the gem would ship without its control room.\n" \
+          "Build the page first: just web-build (or: cd web && npm ci && npm run build)."
+  end
+
+  spec.bindir = "exe"
+  # `depot` and `lanes` are symlinks to `openlanes` in the checkout; named here
+  # so that installing the gem writes all three, rather than only the one git
+  # recorded.
+  spec.executables = %w[openlanes depot lanes]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "aasm"
+  spec.add_dependency "concurrent-ruby"
+  spec.add_dependency "dry-cli"
+  spec.add_dependency "dry-cli-autocomplete", "~> 0.5"
+  # 0.5.1 is the first release whose help screen survives `example [""]`,
+  # which four commands here declare.
+  spec.add_dependency "dry-cli-help", ">= 0.5.1", "< 0.6"
+  spec.add_dependency "dry-cli-ui", "~> 0.5"
+  spec.add_dependency "dry-inflector"
+  spec.add_dependency "dry-monads"
+  spec.add_dependency "fuzzy-string-match"
+  # Opens the control room in the browser when `openlanes run` starts the API server.
+  spec.add_dependency "launchy", "~> 3.1"
+  spec.add_dependency "parallel"
+  spec.add_dependency "pastel"
+  # The API server (plan 004, W3, W7): Sinatra on a threaded Puma, so SSE streams hold a thread each.
+  spec.add_dependency "puma", ">= 6.4"
+  spec.add_dependency "rack-protection", "~> 4.2"
+  spec.add_dependency "rackup", "~> 2.1"
+  # The live run (plan 004) lives in Redis: board and command streams, plan claims.
+  spec.add_dependency "redis-client", "~> 0.31"
+  spec.add_dependency "sinatra", "~> 4.2"
+  spec.add_dependency "tty-box"
+  spec.add_dependency "tty-command"
+  spec.add_dependency "tty-cursor"
+  spec.add_dependency "tty-prompt"
+  spec.add_dependency "tty-screen"
+  spec.add_dependency "unicode-display_width"
+  spec.add_dependency "zeitwerk"
+end