openlanes 3.0.0

data/lib/openlanes/cli/agents/subcommands/list.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes agents …` — the specialist roster.
+    module Agents
+      # `openlanes agents list`
+      class List < Dry::CLI::Command
+        include UI
+
+        desc "List every specialist, what it handles, and what it advances to"
+
+        example ["", "| less -R"]
+
+        # @return [void]
+        def call(**) = $stdout.write(OpenLanes::Agents.roster.list)
+      end
+    end
+  end
+end

data/lib/openlanes/cli/base.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+module OpenLanes
+  module CLI
+    # Shared flags and the plumbing every command needs.
+    class Base < Dry::CLI::Command
+      include UI
+
+      # dry-cli gathers every token a command did not declare an argument for
+      # into :args, and hands it over without a word. `openlanes docs
+      # .plans/README.md` — the `-o` forgotten — therefore ran with every
+      # default, wrote the conventions to the default path, and printed
+      # success for a file the caller never named.
+      #
+      # Prepended rather than called from each `call`, because the command
+      # that forgets this check is the one that needed it.
+      module RefuseStrayArguments
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          stray = Array(options[:args]) - self.class.arguments.flat_map { Array(options[it.name.to_sym]) }
+          unless stray.empty?
+            refuse("This command takes no argument like #{stray.join(" ")}.\n" \
+                   "An option it does take may be the one you meant: run it with -h.",
+              64)
+          end
+
+          super
+        end
+      end
+
+      # Every project command starts at the project root, wherever it was
+      # typed: a `.plans` found relative to a subdirectory is a `.plans` that
+      # does not exist, and the refusal that follows names the wrong problem.
+      #
+      # Prepended for the same reason as {RefuseStrayArguments}: the command
+      # that forgets to look is the one that runs against the wrong tree.
+      module EnterProject
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          enter_project(options) unless self.class.standalone?
+          super
+        end
+      end
+
+      # Marks a command that needs no project — reference output, the agent
+      # roster, completion — so it runs from anywhere without the search.
+      #
+      # @return [void]
+      def self.standalone! = @standalone = true
+
+      # @return [Boolean]
+      def self.standalone? = @standalone == true
+
+      # The name this command is typed as, and the key its section takes
+      # under `commands:` in `.openlanes.yml`: "run", "resync dirs", "list-plans".
+      #
+      # @return [String, nil] nil for a class with no name, as in a spec
+      def self.command_name
+        return nil unless name
+
+        name.delete_prefix("OpenLanes::CLI::").split("::")
+            .map { OpenLanes.inflector.underscore(it).tr("_", "-") }.join(" ")
+      end
+
+      # dry-cli merges what was typed over these, so a `.openlanes.yml` value
+      # placed here sits exactly between the flag and the built-in default.
+      # A file that cannot be read adds nothing at this point; {#enter_project}
+      # reads it again and refuses with the reason.
+      #
+      # @return [Hash{Symbol => Object}]
+      def self.default_params
+        return super if standalone? || command_name.nil?
+
+        root = Project.root or return super
+        known = options.map(&:name)
+        super.merge(OpenLanes::Config.load(root).for(command_name).slice(*known))
+      rescue OpenLanes::Error
+        super
+      end
+
+      # Every `commands:` section must name a command that exists, and every
+      # key in it an option that command takes, with a value it accepts. Each
+      # project command checks the whole file, not only its own section: a
+      # typo under a command you rarely run is still a typo.
+      #
+      # @param config [OpenLanes::Config]
+      # @return [void]
+      # @raise [OpenLanes::Error]
+      def self.check_config!(config)
+        config.commands.each do |name, settings|
+          command = OpenLanes::CLI.get(name.split).then { it.found? ? it.command : nil }
+          unless command.respond_to?(:command_name) && command.command_name == name
+            raise OpenLanes::Error, "#{config.path}: commands.#{name}: no such command"
+          end
+
+          settings.each { |key, value| check_option!(config, command, name, key, value) }
+        end
+      end
+
+      # @return [void]
+      def self.check_option!(config, command, name, key, value)
+        where = "#{config.path}: commands.#{name}.#{key}"
+        option = command.options.find { it.name == key }
+        raise OpenLanes::Error, "#{where}: #{name} takes no such option" unless option
+        raise OpenLanes::Error, "#{where}: a preview is asked for each time, never set as a default" if key == :dry_run
+
+        if option.boolean? && ![true, false].include?(value)
+          raise OpenLanes::Error, "#{where}: #{value.inspect} is not true or false"
+        end
+        return unless option.values && !option.values.map(&:to_s).include?(value.to_s)
+
+        raise OpenLanes::Error, "#{where}: #{value.inspect} is not one of #{option.values.join(", ")}"
+      end
+      private_class_method :check_option!
+
+      def self.inherited(klass)
+        super
+        klass.prepend(EnterProject)
+        klass.prepend(RefuseStrayArguments)
+        klass.option :dir,
+          default: OpenLanes::PLANS_DIR,
+          aliases: ["-D"],
+          desc:    "The .plans directory"
+        klass.option :quiet,
+          type:    :boolean,
+          default: false,
+          aliases: ["-q"],
+          desc:    "Suppress progress output on STDERR"
+      end
+
+      # Declares `-n` / `--dry-run` on a command that changes something.
+      #
+      # @param desc [String] what the preview prints instead of doing
+      # @return [void]
+      def self.dry_run_option(desc)
+        option :dry_run,
+          type:    :boolean,
+          default: false,
+          aliases: ["-n"],
+          desc:
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [OpenLanes::Plans::Tree]
+      def tree_for(options)
+        tree = Plans.tree(options.fetch(:dir, OpenLanes::PLANS_DIR))
+        unless tree.exist?
+          refuse("No #{OpenLanes::PLANS_DIR} directory at\n#{tree.dir}\n\n" \
+                 "Run `openlanes init` to create it, or pass -D.",
+            66)
+        end
+        tree
+      end
+
+      # The directory the command was typed in, before {EnterProject} moved
+      # to the root. A path the user typed (`--prompt notes.md`) means a file
+      # beside them, not one beside `.plans`.
+      #
+      # @return [String]
+      def origin = @origin || Dir.pwd
+
+      # @param path [String, nil]
+      # @return [String, nil] +path+ as the user meant it, from {#origin}
+      def typed_path(path) = path && File.expand_path(path, origin)
+
+      # Finds the root and moves there, saying so when that is somewhere
+      # else. `-D` and `PLANS_DIR` are relative, so they resolve against the
+      # root from here on.
+      #
+      # @param options [Hash]
+      # @return [void]
+      def enter_project(options)
+        @origin = Dir.pwd
+        root = Project.root(from: @origin)
+        unless root
+          refuse("No project here: nothing in #{@origin} or above it holds " \
+                 "#{Project::FILE}, #{OpenLanes::PLANS_DIR}/ or .git.\n\n" \
+                 "Run `openlanes init` to make this directory one.",
+            66)
+        end
+        check_config(root)
+        return if root == Project.expand(@origin)
+
+        Dir.chdir(root)
+        UI.line("Project root: #{root}") unless options.fetch(:quiet, false)
+      end
+
+      # @param root [String]
+      # @return [void]
+      def check_config(root)
+        self.class.check_config!(OpenLanes::Config.load(root))
+      rescue OpenLanes::Error => e
+        refuse(e.message, 65)
+      end
+
+      # Report and stop, in the shape every refusal here takes. The statuses
+      # follow sysexits where one fits: 64 usage, 65 bad data, 66 no input,
+      # 69 a service (GitHub, Linear) refused us.
+      #
+      # @param message [String]
+      # @param status [Integer]
+      # @return [void] never returns
+      def refuse(message, status)
+        error(message)
+        exit status
+      end
+
+      # @param options [Hash]
+      # @return [Boolean]
+      def quiet?(options)
+        quiet = options.fetch(:quiet, false)
+        UI.quiet = quiet
+        quiet
+      end
+
+      # `-n` / `--dry-run`. A command does the work it is named for, so the
+      # preview is what has to be asked for, never the work itself.
+      #
+      # @param options [Hash]
+      # @return [Boolean]
+      def dry_run?(options) = options.fetch(:dry_run, false)
+
+      # `claude` prefers a credential in the environment to a claude.ai login,
+      # so a project `.env` that direnv loads on `cd` can redirect every agent
+      # a run spawns to a key meant for the application itself.
+      #
+      # Say it once, before the run starts, because the failure arrives three
+      # minutes later, once per agent, and reads like an agent problem rather
+      # than an environment one.
+      #
+      # @return [void]
+      def credentials_warning
+        names = Execution::Executor.foreign_credentials
+        return if names.empty?
+
+        one = names.size == 1
+        warn("#{names.join(" and ")} #{one ? "is" : "are"} set in this shell, so every agent authenticates " \
+             "with #{one ? "it" : "them"} rather than with your claude.ai login.\n" \
+             "A stale one fails every agent in the run with `401 API key is invalid`, " \
+             "three minutes at a time.\n" \
+             "If it came from a project .env, run `unset #{names.join(" ")}` first.")
+      end
+
+      # The line every dry run ends with, so nobody mistakes a preview for the
+      # thing having happened.
+      #
+      # @param count [Integer] how much work is pending
+      # @param what [String]
+      # @return [void]
+      def dry_run_footer(count, what)
+        return if count.zero?
+
+        warn("#{count} #{what} pending — nothing was changed.\nRe-run without --dry-run to apply.")
+      end
+    end
+  end
+end

data/lib/openlanes/cli/create/create.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module CLI
+    # `openlanes create <words…>` — backs /spec-create.
+    class Create < Base
+      desc "Create the next numbered plan folder"
+
+      argument :words,
+        type: :array,
+        required: false,
+        default: [],
+        desc:
+          "The topic, two to five words; becomes the folder slug. Omit when --from names it"
+
+      option :from,
+        aliases: ["-f"],
+        desc:
+          "Seed from a markdown file: its frontmatter `title:` names the folder, and its body fills the spec."
+      option :after,
+        aliases: ["-a"],
+        desc:
+          "Create a retroactive plan in the gap after this plan, e.g. 002"
+      option :status,
+        aliases: ["-s"],
+        desc:    "Open in a state other than the default"
+      option :prs,
+        aliases: ["--pr"],
+        desc:
+          "Document work that already shipped: pull request numbers or URLs, comma separated. Requires --after"
+      option :spec,
+        type: :boolean,
+        default: true,
+        desc:
+          "With --prs, write spec.md from what the pull requests did. --no-spec records them and stops, which is fast and offline"
+      option :draft,
+        type: :boolean,
+        default: true,
+        desc:
+          "For a new feature (no --prs), attempt spec.md's four headings from project context via `claude`. --no-draft leaves them bare"
+      option :lane,
+        aliases: ["-l"],
+        values:  Plans::Spec::LANES.map(&:to_s),
+        desc:
+          "Route the plan: full (research, spec, plan, build), plan (skip research and rewriting), " \
+          "quick (one agent does a short mechanical task). Written into spec.md's frontmatter"
+      option :depth,
+        values: Plans::Spec::DEPTHS.map(&:to_s),
+        desc:   "How hard every phase should think: fast, medium or deep. Written into spec.md's frontmatter"
+      option :open,
+        type: :boolean,
+        default: true,
+        desc:
+          "Open the new spec.md in the system editor when done (macOS `open`). --no-open leaves it for you to open"
+
+      # noinspection RubyMismatchedArgumentType
+      example [
+        "tax rule dsl                        # 003.00-⚪️ → tax-rule-dsl, spec.md scaffolded and drafted",
+        "tax rule dsl --no-draft --no-open   # scaffold only, nothing shelled out, nothing opened",
+        "--after 002 schedule k1             # 002.01-🕰️-schedule-k1 (documented after the fact)",
+        "--after 018 --prs 12,15 verify      # …and write spec.md from what those PRs did",
+        "--after 018 --pr https://…/pull/12 verify # verify the pull request by number or URL",
+        "--status ready billing sync         # opens at ⭐️ instead of ⚪️",
+        "--from notes/tax-dsl.md             # title and opening prose from the file's frontmatter and body",
+        "--lane quick split big migration    # r2d2-mechanic does it and opens the PR; no research, spec or plan"
+      ]
+
+      # @param words [Array<String>]
+      # @param options [Hash]
+      # @return [void]
+      def call(words:, **options)
+        dir = options.fetch(:dir, OpenLanes::PLANS_DIR)
+        FileUtils.mkdir_p(dir)
+
+        words, seed = resolve_seed(words, options)
+        prs = fetch_prs(options)
+        result =
+          Lifecycle.create(dir:,
+            words:,
+            after:  options[:after],
+            status: options[:status],
+            prs:)
+
+        result.either(
+          ->(path) { created(path, prs, options, seed:) },
+          ->(message) { refuse("Could not create the plan:\n#{message}", 65) }
+        )
+      end
+
+      private
+
+      # `--from FILE` trades the words argument for a markdown file: the
+      # frontmatter's `title:` names the folder, and the body travels on to
+      # {Brief} as the author's own opening statement. Words and a file are
+      # two answers to one question — the folder's name — so holding both is
+      # refused rather than silently ranked.
+      #
+      # @param words [Array<String>]
+      # @param options [Hash]
+      # @return [Array(Array<String>, String, nil)] the slug words, and the
+      #   seed body when a file supplied them
+      def resolve_seed(words, options)
+        file = typed_path(options[:from])
+        return words, nil unless file
+
+        unless words.empty?
+          refuse(
+            "--from names the topic by its frontmatter title;\n" \
+            "drop the words, or drop --from",
+            64
+          )
+        end
+        if options[:prs]
+          refuse(
+            "--prs reconstructs spec.md from the pull requests, so a seed file\n" \
+            "would be ignored; use one or the other",
+            64
+          )
+        end
+        unless File.file?(file)
+          refuse("Could not read the seed file:\n#{file} does not exist", 66)
+        end
+
+        title, body = parse_seed(File.read(file, encoding: "UTF-8"))
+        if title.to_s.strip.empty?
+          refuse(
+            "The seed file needs a frontmatter title, e.g.\n" \
+            "---\ntitle: Tax Rule DSL\n---",
+            65
+          )
+        end
+
+        [title.split, body]
+      end
+
+      # Frontmatter that will not parse used to be reported as a missing
+      # title, which sends the author looking for a `title:` line that is
+      # sitting right there. Say which of the two actually went wrong.
+      #
+      # @param content [String]
+      # @return [Array(String, String)] title and body
+      def parse_seed(content)
+        meta, body = Frontmatter.split(content)
+        [meta["title"].to_s, body.strip]
+      rescue Psych::Exception => e
+        refuse(
+          "The seed file's frontmatter is not valid YAML:\n#{e.message}",
+          65
+        )
+      end
+
+      # A retroactive plan documents work that landed *somewhere* in the
+      # sequence, and only its author knows where. Guessing would put the
+      # number — the one thing that never changes — in the wrong place.
+      #
+      # @param options [Hash]
+      # @return [Array<Hash>, nil]
+      def fetch_prs(options)
+        return nil unless options[:prs]
+
+        unless options[:after]
+          refuse(
+            "--prs documents work that already shipped;\n" \
+            "name the plan it landed after with --after, e.g. --after 018",
+            64
+          )
+        end
+
+        Vcs.github.pull_requests(Vcs::GitHub.parse_refs(options[:prs]))
+      rescue OpenLanes::Error => e
+        refuse("Could not read the pull requests:\n#{e.message}", 65)
+      end
+
+      # A plan with recorded pull requests already has its facts — hand it to
+      # the writer that reconstructs a specification from a diff. One without
+      # them does not exist yet, and reconstructing is not the job; {#brief} is.
+      #
+      # @param path [String]
+      # @param prs [Array<Hash>, nil]
+      # @param options [Hash]
+      # @return [void]
+      def created(path, prs, options, seed: nil)
+        from_prs = prs && !prs.empty?
+        path =
+          if from_prs
+            synthesize(path, options) if options.fetch(:spec, true)
+          else
+            brief(path, options, seed:)
+          end || path
+        puts path
+        return if quiet?(options)
+
+        feature = Plans::Feature.parse(path)
+        success(
+          "Created #{File.basename(path)}\n\n" \
+          "#{feature.status.emoji} #{feature.status.label} — #{feature.status.note}\n" \
+          "#{next_step(path, feature, from_prs:)}"
+        )
+      end
+
+      # Hand the folder to the writer that already knows how to write a
+      # retroactive specification, then let `resync dirs` decide what the
+      # folder has become — 🕰️ is only true while there is no `spec.md`.
+      #
+      # @param path [String]
+      # @param options [Hash]
+      # @return [String] the folder's path, which the resync may have renamed
+      def synthesize(path, options)
+        agent = OpenLanes::Agents.registry.find(OpenLanes::RETROACTIVE_WRITER) or
+          return path
+        root = options[:root] || File.dirname(path, 2)
+
+        feature = Plans::Feature.parse(path)
+        ok, note = on_agent_row("Writing spec.md from #{UI.paint(File.basename(path).to_s, :yellow)}",
+          agent: agent.name,
+          plan:  feature.ordinal.to_s) do |line|
+          Execution.executor(root:).call(agent, Plans.subject(feature), &line)
+        end
+        warn_about(note) unless ok
+
+        settle(path)
+      end
+
+      # A folder with no pull requests to reconstruct from is a feature that
+      # does not exist yet. {Brief} writes the four headings a human still has
+      # to answer, makes a best-effort pass at them from what the project
+      # already has on disk, and — unless told not to — opens the result for
+      # a human to finish. The folder's state never moves: ⚪️ New only ever
+      # claimed that a specification exists, not that it is complete.
+      #
+      # @param path [String] the path to the folder
+      # @param seed [String, nil] the seed body from the `--from` file
+      # @param options [Hash] the options hash
+      # @return [String] +path+, unchanged
+      def brief(path, options, seed: nil)
+        feature = Plans::Feature.parse(path)
+        return path if feature.status.key == :retroactive
+
+        root = options[:root] || File.dirname(path, 2)
+        brief = Lifecycle.brief(path:, title: feature.title, root:, seed:)
+        brief.write_scaffold!
+
+        if options.fetch(:draft, true)
+          # Painted the way Runner::Task#label paints a roster agent, so the
+          # half-agent reads as one of them on the terminal.
+          label =
+            "#{UI.paint(Lifecycle::Brief::AGENT_NAME, :yellow, :bold)} drafting spec.md from #{seed}"
+          ok, note = on_agent_row(label, agent: Lifecycle::Brief::AGENT_NAME, plan: feature.ordinal.to_s) { brief.attempt! }
+          warn_about_draft(note) unless ok
+        end
+
+        stamp(brief.spec_path, options)
+        open_spec(brief.spec_path) if options.fetch(:open, true)
+        path
+      end
+
+      # One agent writing spec.md, drawn as a spinner line.
+      #
+      # @param label [String] the spinner line's text
+      # @param agent [String]
+      # @param plan [String]
+      # @yieldparam line [OpenLanes::UI::Line]
+      # @return [Object] the block's value
+      def on_agent_row(label, agent:, plan:, &block)
+        Execution.on_interrupt do
+          UI.concurrently([plan],
+            label,
+            jobs:   1,
+            label:  ->(_) { label },
+            fields: ->(_) { { plan:, agent: } }) { |_, line| block.call(line) }.first
+        end
+      end
+
+      # Writes `--lane` and `--depth` into spec.md's frontmatter, after the
+      # draft, so a drafting agent that rewrites the file cannot drop them.
+      #
+      # @param spec_path [String]
+      # @param options [Hash]
+      # @return [void]
+      def stamp(spec_path, options)
+        settings = { "lane" => options[:lane], "depth" => options[:depth] }.compact
+        return if settings.empty? || !File.file?(spec_path)
+
+        meta, body = Frontmatter.split(File.read(spec_path, encoding: "UTF-8"))
+        File.write(spec_path, "#{YAML.dump(meta.merge(settings))}---\n#{body}")
+      end
+
+      # @param spec_path [String]
+      # @return [void]
+      def open_spec(spec_path)
+        return unless macos?
+
+        system("open", spec_path, out: File::NULL, err: File::NULL)
+      end
+
+      # `open` is a macOS command; anywhere else the viewer step is skipped
+      # rather than failed. A named seam so a spec can assert the viewer was
+      # asked for without inheriting the platform CI happens to run on.
+      #
+      # @return [Boolean]
+      def macos? = RbConfig::CONFIG["host_os"].to_s.match?(/darwin/)
+
+      # @param path [String]
+      # @return [String] where the folder ended up
+      def settle(path)
+        tree = Plans.tree(File.dirname(path))
+        change =
+          OpenLanes::Lifecycle::Resync::Dirs
+          .new(tree:)
+          .call(commit: true)
+          .find { |c| c.source == path }
+        change ? change.target : path
+      end
+
+      # @param note [String]
+      # @return [void]
+      def warn_about(note)
+        error(
+          "The folder was created, but spec.md was not written:\n#{note}\n\n" \
+          "The pull requests are recorded. Run `openlanes run` to retry."
+        )
+      end
+
+      # @param note [String]
+      # @return [void]
+      def warn_about_draft(note)
+        error(
+          "spec.md was scaffolded, but the drafting attempt did not finish:\n#{note}\n\n" \
+          "The four headings are there, empty. Fill them in by hand, or hand off to leah-researcher."
+        )
+      end
+
+      # @param path [String]
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [String]
+      def next_step(path, feature, from_prs:)
+        spec = File.join(File.basename(path), "spec.md")
+        unless feature.status.key == :new &&
+               File.file?(File.join(path, "spec.md"))
+          return "Next: write #{spec}"
+        end
+        if from_prs
+          return (
+            "Next: read #{spec} — it was written from the pull requests, so check it against what actually shipped"
+          )
+        end
+
+        "Next: fill in the four headings in #{spec}, then hand off to leah-researcher"
+      end
+    end
+  end
+end

data/lib/openlanes/cli/docs/docs.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenLanes
+  module CLI
+    # `openlanes docs` — regenerate the conventions document.
+    class Docs < Base
+      standalone!
+      desc "Generate the conventions document from the state machine itself"
+
+      # STDOUT unless a file is named. The default used to be a file in the
+      # user's home, so an agent running `openlanes docs` to *read* the
+      # conventions overwrote ~/.agents/context/workflow.md, untracked and
+      # unrecoverable, while the help promised STDOUT.
+      option :output,
+        aliases: ["-o"],
+        desc:    "Write here instead of STDOUT; - for STDOUT"
+
+      example ["                                  # print it", "-o ~/.agents/context/workflow.md  # write it"]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        document = Presentation.documentation
+
+        path = options[:output]
+        if path && path != "-"
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, document)
+          # Argument form, so a path with a space or a quote reaches mdformat whole.
+          system("mdformat", "--wrap", "no", path, err: File::NULL, out: File::NULL)
+          success("created workflow description in [#{path}]") unless quiet?(options)
+        else
+          $stdout.write(document)
+        end
+      end
+    end
+  end
+end