plan_driven 0.1.0 → 0.3.0

data/lib/plan_driven/cli/setup_commands.rb

@@ -83,6 +83,7 @@ module PlanDriven
       end
 
       def check_cursor
+        return check_local_agents if PlanDriven.configuration.agent_provider.to_sym == :local
         return unless Credentials.fetch(:cursor_api_key)
 
         agents = CursorAgents.new
@@ -92,6 +93,15 @@ module PlanDriven
       rescue Error => e
         ui.error "Cursor API: #{e.message}"
       end
+
+      def check_local_agents
+        command = PlanDriven.configuration.agent_command.to_s
+        return ui.error("Agents: local, but config.agent_command isn't set") if command.empty?
+
+        program = Shellwords.split(command).first
+        found = ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, program)) }
+        found ? ui.success("Agents: local, #{command}") : ui.error("Agents: #{program} isn't on the PATH")
+      end
     end
   end
 end

data/lib/plan_driven/cli/ticket_commands.rb

@@ -23,7 +23,7 @@ module PlanDriven
         plan.tickets.select(&:issue_number).each do |ticket|
           ui.muted "  #{ticket.key} -> issue ##{ticket.issue_number}"
         end
-        ui.say "Next: `plan-driven develop #{plan.key}` hands the ready tickets to Cursor agents."
+        ui.say "Next: `plan-driven develop #{plan.key}` hands the ready tickets to the coding agents."
       end
 
       def cmd_prompt(reference = nil)
@@ -36,7 +36,9 @@ module PlanDriven
         return explain_waiting(plan) if starting.empty?
 
         starting.each { |ticket| ui.say "  #{ticket.key} #{ticket.title}" }
-        return ui.muted("Nothing started.") unless ui.confirm?("Start #{starting.size} Cursor cloud agent(s)?")
+        unless ui.confirm?("Start #{starting.size} #{PlanDriven.configuration.agent_provider} agent(s)?")
+          return ui.muted("Nothing started.")
+        end
 
         delivery.develop(plan, only: starting.map(&:key)).each do |ticket|
           ui.success "#{ticket.key} agent started: #{ticket.agent_url}"
@@ -123,6 +125,44 @@ module PlanDriven
         run.passed? ? ui.success(Evidence.summary_line(plan)) : ui.warn("#{run.status}: #{Evidence.summary_line(plan)}")
       end
 
+      def cmd_usage(reference = nil)
+        plan = find_plan(reference)
+        rows = Usage.rows(plan)
+        return ui.muted("No token usage recorded for #{plan.key} yet.") if rows.empty?
+
+        ui.table(%w[Step Ticket Model Tokens Time Cost], rows.map do |row|
+          [row.step.to_s, row.ticket.to_s, row.model.to_s, Usage.format_tokens(row.total_tokens),
+           row.duration_ms ? "#{(row.duration_ms / 60_000.0).round(1)} min" : "", Usage.format_cost(row.cost)]
+        end)
+        totals = Usage.totals(rows)
+        ui.say
+        ui.success "#{Usage.format_tokens(totals[:total_tokens])} tokens" \
+                   "#{", #{Usage.format_cost(totals[:cost])}" if totals[:cost]}"
+        return if totals[:unpriced].empty?
+
+        ui.muted "No price for #{totals[:unpriced].join(", ")}; set config.token_prices to see dollars."
+      end
+
+      def cmd_stats(reference = nil)
+        plan = find_plan(reference)
+        stats = Statistics.new(plan)
+        duration = ->(seconds) { Statistics.duration(seconds) }
+        ui.heading "#{plan.key} #{plan.title}: statistics"
+        stats.phases.each { |label, seconds| ui.say "  #{label.ljust(22)}#{seconds ? duration[seconds] : "not yet"}" }
+        return ui.muted("Ticket statistics start when the tickets are approved.") unless stats.started?
+
+        show_summary(stats.summary)
+        show_time_split(stats)
+        ui.say
+        ui.table(%w[# Est Queued Agent Review Fixes Merge Rounds Total], stats.tickets.map do |row|
+          [row.ticket.key, row.ticket.estimate.to_s,
+           *%w[queued agent review fixes merge].map do |phase|
+             row.seconds(phase).positive? ? duration[row.seconds(phase)] : "-"
+           end,
+           row.review_rounds.to_s, row.merged? ? duration[row.cycle_time] : row.ticket.status.tr("_", " ")]
+        end)
+      end
+
       def cmd_report(reference = nil)
         plan = find_plan(reference)
         paths = delivery.report(plan)
@@ -132,6 +172,27 @@ module PlanDriven
 
       private
 
+      def show_summary(summary)
+        ui.say "  #{"Idea to delivery".ljust(22)}#{Statistics.duration(summary[:lead_time])}"
+        ui.say "  #{"Tickets merged".ljust(22)}#{summary[:merged]} of #{summary[:tickets]}, " \
+               "#{summary[:first_time]} approved the first time"
+        proven = "#{summary[:proven]} of #{summary[:criteria]} acceptance criteria proven"
+        summary[:proven] == summary[:criteria] ? ui.success(proven) : ui.warn(proven)
+      end
+
+      def show_time_split(stats)
+        work = stats.work_seconds
+        return if work.zero?
+
+        ui.say
+        ui.say "Where the time went while tickets were worked on (agents #{stats.agent_share}%):"
+        stats.totals.slice(*Statistics::WORK).each do |phase, seconds|
+          share = seconds * 100.0 / work
+          ui.say "  #{Statistics::PHASES[phase].ljust(22)}#{Statistics.duration(seconds).rjust(10)}  " \
+                 "#{"█" * (share / 4).ceil} #{share.round}%"
+        end
+      end
+
       def explain_waiting(plan)
         running = plan.tickets.count(&:active_agent?)
         if plan.tickets.any?(&:ready?) && running >= PlanDriven.configuration.max_parallel_agents
@@ -147,7 +208,7 @@ module PlanDriven
       def show_tickets(tickets)
         ui.table(%w[# Title Kind Pts Status PR], tickets.map do |ticket|
           [ticket.key, ticket.title.truncate(48), ticket.kind, ticket.estimate, ticket.status.tr("_", " "),
-           ticket.pr_url.to_s]
+           ticket.pr_number ? "##{ticket.pr_number}" : ""]
         end)
       end
     end

data/lib/plan_driven/cli/ui.rb

@@ -42,7 +42,8 @@ module PlanDriven
         answer.empty? ? default.to_s : answer
       end
 
-      # Several lines, finished by an empty line.
+      # Several lines, finished by an empty line. Piped answers (from the wizard, or a script) are
+      # echoed, so the transcript reads like a typed interview.
       def ask_multiline(prompt)
         say paint(prompt, :cyan)
         muted "  (finish with an empty line)"
@@ -50,6 +51,7 @@ module PlanDriven
         loop do
           output.print "  > "
           line = read_line(nil)
+          output.puts(line.to_s.rstrip) if piped?
           break if line.nil? || line.strip.empty?
 
           lines << line.rstrip
@@ -83,8 +85,12 @@ module PlanDriven
         success ok_message if report.errors.empty? && report.warnings.empty?
       end
 
+      MIN_COLUMN = 16
+
+      # The widest columns are cut to fit the terminal's width, so rows don't wrap.
       def table(headers, rows)
-        widths = headers.each_index.map { |i| ([headers[i]] + rows.map { |row| row[i] }).map { |v| v.to_s.length }.max }
+        rows = fit_columns(headers, rows)
+        widths = column_widths(headers, rows)
         line = ->(cells) { cells.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ") }
         say paint(line.call(headers), :bold)
         rows.each { |row| say line.call(row) }
@@ -92,6 +98,39 @@ module PlanDriven
 
       private
 
+      def column_widths(headers, rows)
+        headers.each_index.map { |i| ([headers[i]] + rows.map { |row| row[i] }).map { |v| v.to_s.length }.max }
+      end
+
+      # Cuts the widest columns short, never below MIN_COLUMN, until the table fits the terminal.
+      def fit_columns(headers, rows)
+        columns = terminal_width or return rows
+        widths = column_widths(headers, rows)
+        room = columns - (2 * (widths.size - 1)) - 1
+        while widths.sum > room
+          widest = widths.each_index.max_by { |i| widths[i] }
+          cut = [widths[widest] - (widths.sum - room), MIN_COLUMN, headers[widest].length].max
+          break if cut >= widths[widest]
+
+          widths[widest] = cut
+        end
+        rows.map { |row| row.each_with_index.map { |cell, i| cell.is_a?(String) ? cell.truncate(widths[i]) : cell } }
+      end
+
+      # The terminal's width, or COLUMNS when the output isn't a terminal (the wizard sets it).
+      def terminal_width
+        if output.respond_to?(:tty?) && output.tty? && output.respond_to?(:winsize)
+          output.winsize[1].then { |columns| return columns if columns.positive? }
+        end
+        ENV["COLUMNS"].to_i.then { |columns| columns.positive? ? columns : nil }
+      rescue StandardError
+        nil
+      end
+
+      def piped?
+        !(input.respond_to?(:tty?) && input.tty?)
+      end
+
       def read_line(at_end = "")
         line = input.gets
         line.nil? ? at_end : PlanDriven.utf8(line)

data/lib/plan_driven/cli.rb

@@ -7,6 +7,7 @@ require_relative "cli/ui"
 require_relative "cli/plan_commands"
 require_relative "cli/ticket_commands"
 require_relative "cli/setup_commands"
+require_relative "cli/config_commands"
 
 module PlanDriven
   # bundle exec plan-driven <command> [arguments]
@@ -14,12 +15,13 @@ module PlanDriven
     include PlanCommands
     include TicketCommands
     include SetupCommands
+    include ConfigCommands
 
     COMMANDS = {
       "new" => ["TITLE", "Interview in the terminal, then draft the plan from your answers and the schema"],
       "list" => ["", "Every plan and its phase"],
       "show" => ["PLAN", "Print the plan, or one section with --section"],
-      "edit" => ["PLAN SECTION", "Edit a section in $EDITOR"],
+      "edit" => ["PLAN SECTION", "Edit a section in $EDITOR, or replace it with --from FILE"],
       "redraft" => ["PLAN SECTION \"instruction\"", "Have the model rewrite one section"],
       "check" => ["PLAN", "Run the plan guards"],
       "submit" => ["PLAN", "Send the plan for approval (guards must pass)"],
@@ -29,7 +31,7 @@ module PlanDriven
       "tickets" => ["PLAN [\"instruction\"]", "Draft tickets from the approved plan, or redraft them"],
       "approve-tickets" => ["PLAN", "Approve the tickets (--as ROLE); creates GitHub issues"],
       "prompt" => ["PLAN/TICKET", "Show what the agent will be told"],
-      "develop" => ["PLAN [TICKET...]", "Hand ready tickets to Cursor cloud agents"],
+      "develop" => ["PLAN [TICKET...]", "Hand ready tickets to the coding agents (Cursor cloud, or local)"],
       "status" => ["PLAN", "Poll agents and pull requests, then show every ticket"],
       "review" => ["PLAN/TICKET", "Run the pull request guards"],
       "approve-pr" => ["PLAN/TICKET", "Approve the pull request (guards must pass)"],
@@ -38,11 +40,16 @@ module PlanDriven
       "evidence" => ["PLAN", "Run the plan's Cucumber scenarios and record the results (--from FILE)"],
       "report" => ["PLAN", "Write the delivery report"],
       "log" => ["PLAN", "The audit trail"],
+      "usage" => ["PLAN", "Tokens and cost per step and per agent run"],
+      "stats" => ["PLAN", "Where the time went: phases, agents and people, each ticket"],
+      "questions" => ["", "The interview's questions, with the team's changes"],
+      "question" => ["KEY", "Change or add a question (--title, --ask, --group, --required, --optional, --remove)"],
       "configure" => ["", "Store API keys in ~/.plan_driven/config"],
+      "connect" => ["SERVICE", "Check a key with cursor, openai, anthropic or github, then store it"],
       "doctor" => ["", "Check keys, repository and connections"]
     }.freeze
 
-    NO_APP = %w[configure doctor help version].freeze
+    NO_APP = %w[configure connect doctor help version].freeze
 
     # Plans are UTF-8 whatever the terminal's locale says, so answers typed with č or ž under
     # LANG=C are read as text, not bytes.
@@ -64,7 +71,7 @@ module PlanDriven
       @ui = UI.new(input: @input, output: @output, assume_yes: options[:yes])
       @options = options
       return help if %w[help -h --help].include?(command)
-      return @ui.say(PlanDriven::VERSION) if %w[version -v --version].include?(command)
+      return @ui.say(PlanDriven::VERSION) || 0 if %w[version -v --version].include?(command)
       raise Error, "Unknown command `#{command}`. `plan-driven help` lists them." unless COMMANDS.key?(command)
 
       boot_application unless NO_APP.include?(command)
@@ -109,10 +116,20 @@ module PlanDriven
         parser.on("--section KEY") { |value| options[:section] = value }
         parser.on("--from FILE") { |value| options[:from] = value }
         parser.on("-y", "--yes") { options[:yes] = true }
+        question_options(parser, options)
       end.parse!(argv)
       options
     end
 
+    def question_options(parser, options)
+      parser.on("--title TEXT") { |value| options[:title] = value }
+      parser.on("--ask TEXT") { |value| options[:ask] = value }
+      parser.on("--group NAME") { |value| options[:group] = value }
+      parser.on("--required") { options[:required] = true }
+      parser.on("--optional") { options[:required] = false }
+      parser.on("--remove") { options[:remove] = true }
+    end
+
     def boot_application
       return unless @boot
       return if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.initialized?

data/lib/plan_driven/configuration.rb

@@ -26,8 +26,13 @@ module PlanDriven
     # Where documentation is written, relative to the application root.
     attr_accessor :docs_path, :root
 
-    # Cursor cloud agents.
-    attr_accessor :agent_model, :base_branch, :max_parallel_agents, :skip_reviewer_request
+    # Coding agents: :cursor (Cursor cloud agents), or :local to run a command such as Claude Code
+    # or Codex on this machine, one git worktree per ticket (see LocalAgents).
+    attr_accessor :agent_provider, :agent_command, :agent_model, :base_branch, :max_parallel_agents,
+                  :skip_reviewer_request, :agent_timeout
+
+    # Dollars per million tokens, by model id, for the cost in the delivery report (see Usage).
+    attr_accessor :token_prices
 
     # GitHub.
     attr_accessor :github_repository, :sync_issues, :merge_method, :issue_labels
@@ -45,11 +50,29 @@ module PlanDriven
     # Anything the LLM should know that the schema doesn't show.
     attr_accessor :extra_context
 
+    # The browser wizard at /plan_driven runs commands on this machine. nil means development
+    # only; it answers local requests either way.
+    attr_accessor :wizard_enabled
+
     # The plan's sections. Template.default mirrors the usual Confluence implementation plan.
     attr_writer :template
 
+    # The template with the team's interview changes (config/plan_driven/interview.yml) applied.
     def template
-      @template ||= Template.default
+      file = Interview.path(root_path)
+      stamp = [base_template.object_id, file.to_s, file.exist? && file.mtime]
+      unless @interview_stamp == stamp
+        @interview_template = Interview.apply(base_template, root_path)
+        @interview_stamp = stamp
+      end
+      @interview_template
+    end
+
+    # The template as the initializer set it, before the interview changes.
+    def base_template
+      return @template if @template
+
+      @template = Template.default
     end
 
     def initialize
@@ -68,10 +91,14 @@ module PlanDriven
       @docs_path = "docs/plans"
       @root = nil
 
+      @agent_provider = :cursor
+      @agent_command = nil
       @agent_model = nil
       @base_branch = "main"
       @max_parallel_agents = 3
       @skip_reviewer_request = false
+      @agent_timeout = 3600
+      @token_prices = {}
 
       @github_repository = nil
       @sync_issues = true
@@ -89,6 +116,7 @@ module PlanDriven
       @team_rules = []
       @pdf_renderer = nil
       @extra_context = nil
+      @wizard_enabled = nil
     end
 
     def llm_model

data/lib/plan_driven/connections.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # The services plan_driven talks to, which of them this app's configuration uses, and a check
+  # that a key works before `plan-driven connect` stores it.
+  module Connections
+    Service = Struct.new(:name, :title, :key, :purpose, :url, keyword_init: true) do
+      def env
+        Credentials::KEYS.fetch(key)
+      end
+    end
+
+    SERVICES = [
+      Service.new(name: "cursor", title: "Cursor", key: "cursor_api_key",
+                  purpose: "Cloud agents, one per ticket, and drafting with llm_provider :cursor",
+                  url: "https://cursor.com/dashboard?tab=integrations"),
+      Service.new(name: "openai", title: "OpenAI", key: "openai_api_key",
+                  purpose: "Drafting plans and tickets with llm_provider :openai",
+                  url: "https://platform.openai.com/api-keys"),
+      Service.new(name: "anthropic", title: "Anthropic", key: "anthropic_api_key",
+                  purpose: "Drafting plans and tickets with llm_provider :anthropic",
+                  url: "https://console.anthropic.com/settings/keys"),
+      Service.new(name: "github", title: "GitHub", key: "github_token",
+                  purpose: "Issues, pull requests, reviews and merges",
+                  url: "https://github.com/settings/personal-access-tokens")
+    ].freeze
+
+    module_function
+
+    def find(name)
+      SERVICES.find { |service| service.name == name.to_s.downcase } or
+        raise ArgumentError, "Connect what? One of: #{SERVICES.map(&:name).join(", ")}"
+    end
+
+    # The services this app needs with its current configuration.
+    def needed(config = PlanDriven.configuration)
+      names = ["github"]
+      names << "cursor" if config.agent_provider.to_sym == :cursor || config.llm_provider.to_sym == :cursor
+      names << config.llm_provider.to_s if %i[openai anthropic].include?(config.llm_provider.to_sym)
+      SERVICES.select { |service| names.include?(service.name) }
+    end
+
+    # Who the key belongs to, or a ProviderError when the service refuses it.
+    def verify(service, key, config = PlanDriven.configuration)
+      case service.name
+      when "cursor"
+        info = CursorAgents.new(api_key: key, config: config).me
+        "connected as #{info["userEmail"] || info["apiKeyName"] || "this key"}"
+      when "github"
+        headers = { "Authorization" => "Bearer #{key}", "Accept" => "application/vnd.github+json" }
+        "connected as #{get(service, "https://api.github.com/user", headers)["login"]}"
+      when "openai"
+        base = config.llm_provider.to_sym == :openai && config.llm_api_base ? config.llm_api_base : "https://api.openai.com/v1"
+        get(service, "#{base.chomp("/")}/models", "Authorization" => "Bearer #{key}")
+        "the key works"
+      when "anthropic"
+        get(service, "https://api.anthropic.com/v1/models", "x-api-key" => key, "anthropic-version" => "2023-06-01")
+        "the key works"
+      end
+    end
+
+    def get(service, url, headers)
+      response = HTTP.request(:get, url, headers: headers.merge("User-Agent" => "plan_driven"), timeout: 30)
+      return response.json if response.success?
+
+      raise ProviderError, "#{service.title} refused the key (HTTP #{response.status})"
+    end
+  end
+end

data/lib/plan_driven/cursor_agents.rb

@@ -10,7 +10,7 @@ module PlanDriven
     BASE = "https://api.cursor.com/v1"
     TERMINAL = %w[FINISHED ERROR CANCELLED EXPIRED].freeze
 
-    Run = Struct.new(:id, :agent_id, :status, :result, :branch, :pr_url, keyword_init: true) do
+    Run = Struct.new(:id, :agent_id, :status, :result, :branch, :pr_url, :duration_ms, keyword_init: true) do
       def terminal?
         TERMINAL.include?(status)
       end
@@ -48,6 +48,14 @@ module PlanDriven
       to_run(request(:post, "/agents/#{agent_id}/runs", { prompt: { text: text } }).fetch("run"))
     end
 
+    # Tokens one run spent, in Usage's field names.
+    def usage(agent_id, run_id)
+      data = request(:get, "/agents/#{agent_id}/usage?runId=#{run_id}")
+      tokens = Array(data["runs"]).first.to_h["usage"] || data["totalUsage"] || {}
+      { "input_tokens" => tokens["inputTokens"].to_i, "output_tokens" => tokens["outputTokens"].to_i,
+        "cache_write_tokens" => tokens["cacheWriteTokens"].to_i, "cache_read_tokens" => tokens["cacheReadTokens"].to_i }
+    end
+
     def me
       request(:get, "/me")
     end
@@ -62,7 +70,7 @@ module PlanDriven
     def to_run(data)
       branch = Array(data.dig("git", "branches")).first || {}
       Run.new(id: data["id"], agent_id: data["agentId"], status: data["status"], result: data["result"],
-              branch: branch["branch"], pr_url: branch["prUrl"])
+              branch: branch["branch"], pr_url: branch["prUrl"], duration_ms: data["durationMs"])
     end
 
     def request(method, path, body = nil)

data/lib/plan_driven/delivery.rb

@@ -24,6 +24,7 @@ module PlanDriven
                           guard_report: result.report.to_h)
       plan.log!("plan.drafted", actor: actor, model: llm.label, attempts: result.attempts,
                                 assumptions: result.assumptions)
+      Usage.record_llm(plan, llm, "plan drafted", actor: actor)
       Renderer.write_plan(plan, config: config)
       [plan, result]
     end
@@ -43,6 +44,7 @@ module PlanDriven
     def redraft_section(plan, key, instruction)
       text = drafter.redraft(plan.sections, key, instruction)
       edit_section(plan, key, text)
+      Usage.record_llm(plan, llm, "#{key} redrafted", actor: actor)
       text
     end
 
@@ -76,7 +78,11 @@ module PlanDriven
 
     def draft_tickets(plan, instruction: nil)
       require_status!(plan, %w[approved ticketed])
-      result = TicketGenerator.new(llm: llm, schema: schema, config: config).generate(plan, instruction: instruction)
+      result = begin
+        TicketGenerator.new(llm: llm, schema: schema, config: config).generate(plan, instruction: instruction)
+      ensure
+        Usage.record_llm(plan, llm, instruction ? "tickets redrafted" : "tickets drafted", actor: actor)
+      end
       raise GuardError, result.report.errors unless result.report.ok?
 
       replace_tickets(plan, result)
@@ -190,6 +196,7 @@ module PlanDriven
                                               method: config.merge_method)
       ticket.update!(merged_sha: result["sha"])
       Workflow.ticket_transition!(ticket, "merged")
+      clean_up_agent(ticket)
       ticket.plan.log!("ticket.merged", actor: actor, ticket: ticket, sha: result["sha"])
       finish(ticket.plan)
       ticket
@@ -233,13 +240,14 @@ module PlanDriven
       run = agents.run(ticket.agent_id, ticket.agent_run_id)
       return unless run.terminal?
 
+      Usage.record_agent(ticket, run, agents, actor: actor, config: config)
       if run.finished? && run.pr_url
         ticket.update!(pr_url: run.pr_url, pr_number: GitHub.pr_number(run.pr_url), branch: run.branch)
         Workflow.ticket_transition!(ticket, "pr_open")
-        ticket.plan.log!("ticket.pr_opened", actor: "cursor-agent", ticket: ticket, pr: run.pr_url)
+        ticket.plan.log!("ticket.pr_opened", actor: agent_actor, ticket: ticket, pr: run.pr_url)
       else
         Workflow.ticket_transition!(ticket, "failed")
-        ticket.plan.log!("ticket.agent_failed", actor: "cursor-agent", ticket: ticket, status: run.status,
+        ticket.plan.log!("ticket.agent_failed", actor: agent_actor, ticket: ticket, status: run.status,
                                                 result: run.result.to_s[0, 500])
       end
     end
@@ -250,6 +258,7 @@ module PlanDriven
 
       ticket.update!(merged_sha: pull["merge_commit_sha"])
       Workflow.ticket_transition!(ticket, "merged")
+      clean_up_agent(ticket)
       ticket.plan.log!("ticket.merged", actor: pull.dig("merged_by", "login") || "github", ticket: ticket,
                                         sha: pull["merge_commit_sha"], outside_plan_driven: true)
     end
@@ -262,6 +271,14 @@ module PlanDriven
       plan.log!("plan.delivered", actor: actor)
     end
 
+    def clean_up_agent(ticket)
+      agents.cleanup(ticket.agent_id) if ticket.agent_id && agents.respond_to?(:cleanup)
+    end
+
+    def agent_actor
+      "#{config.agent_provider}-agent"
+    end
+
     def feature_files(files, sha)
       files.select { |file| file["filename"].end_with?(".feature") && file["status"] != "removed" }
            .to_h { |file| [file["filename"], github.file(file["filename"], ref: sha)] }
@@ -344,7 +361,8 @@ module PlanDriven
     end
 
     def llm
-      @llm ||= LLM.new(config)
+      @llm = MeteredLLM.new(@llm || LLM.new(config)) unless @llm.is_a?(MeteredLLM)
+      @llm
     end
 
     def schema
@@ -356,7 +374,7 @@ module PlanDriven
     end
 
     def agents
-      @agents ||= CursorAgents.new(config: config)
+      @agents ||= Agents.build(config)
     end
   end
 end

data/lib/plan_driven/evidence.rb

@@ -17,6 +17,13 @@ module PlanDriven
       end
     end
 
+    # Scenarios commit and wipe data, so they never run against the development database, even
+    # when plan-driven itself was started from a development server (the wizard).
+    CUCUMBER_ENV = { "RAILS_ENV" => "test", "RACK_ENV" => "test" }.freeze
+
+    # Shown before each result in the Markdown report, so it reads at a glance on GitHub too.
+    MARKS = { "passed" => "✅", "failed" => "❌", "not run" => "⏸️", "no scenario" => "⚠️" }.freeze
+
     module_function
 
     def tag_expression(plan)
@@ -29,7 +36,7 @@ module PlanDriven
         shown = command&.join(" ") || %(bundle exec cucumber --tags "#{tag_expression(plan)}")
         command ||= ["bundle", "exec", "cucumber", "--tags", tag_expression(plan), "--format", "json", "--out", out,
                      "--format", "progress"]
-        output, status = Open3.capture2e(*command, chdir: root.to_s)
+        output, status = Open3.capture2e(CUCUMBER_ENV, *command, chdir: root.to_s)
         json = File.exist?(out) ? File.read(out) : "[]"
         record(plan, json, command: shown, actor: actor, exit_ok: status.success?, output: output)
       end
@@ -72,8 +79,8 @@ module PlanDriven
       "not run"
     end
 
-    def matrix(plan)
-      scenarios = plan.evidence_runs.last&.scenarios || []
+    def matrix(plan, run = plan.evidence_runs.last)
+      scenarios = run&.scenarios || []
       plan.tickets.flat_map do |ticket|
         ticket.criteria.each_with_index.map do |criterion, index|
           matching = scenarios.select do |scenario|
@@ -90,7 +97,7 @@ module PlanDriven
 
       rows = matrix(plan).map do |row|
         scenario = row.scenarios.map { |s| "#{s["name"]} (`#{s["file"]}`)" }.join("; ").presence || "-"
-        ["#{row.ticket.key}.#{row.number}", row.criterion, scenario, row.status]
+        ["#{row.ticket.key}.#{row.number}", row.criterion, scenario, "#{MARKS[row.status]} #{row.status}"]
       end
       commit = run.commit_sha.present? ? " on commit `#{run.commit_sha[0, 7]}`" : ""
       intro = "Cucumber, run #{run.created_at.strftime("%-d %b %Y %H:%M")}#{commit}: `#{run.command}`"

data/lib/plan_driven/github.rb

@@ -33,6 +33,10 @@ module PlanDriven
       request(:post, "/repos/#{repository}/issues/#{number}/comments", { body: body })
     end
 
+    def create_pull(title:, head:, base:, body:)
+      request(:post, "/repos/#{repository}/pulls", { title: title, head: head, base: base, body: body })
+    end
+
     def pull(number)
       request(:get, "/repos/#{repository}/pulls/#{number}")
     end