binpacker 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfee21fa79b8b157afbe89bba482a2a8c2b95c4ec22dbff36117a269275f47ef
-  data.tar.gz: 636266dc852e315dffb3e1b815f39b615e4a73be4cfa9dac445a01ef7b7d76fc
+  metadata.gz: 991ac5d941b69573b4f6d03c211ff862465a91ee31ddd82f5ce8d8150a2d4f0d
+  data.tar.gz: 8ad2f245f73a46a4fdd64272049835c36d3b2dc4a0bb5df9cf67f851789ae59a
 SHA512:
-  metadata.gz: 3eb4035f35100358451c5efa9ba5ae178932defb326a988d9d1e6da1521c79b201e68ba075f8bd2575f36a4d0ce33d92b40fd5117afbac21068e3eaabb93daf2
-  data.tar.gz: 788f484e43e7d9c6d77519cabe924f6080e77ebff5e4fb1125e38721c165c1bf6bbdd6e0f4a9fa1140a3b1d62da770be746cbcd4f68dce15f36d0ab556d949c9
+  metadata.gz: 4345168c76cd0e072ab8f0775df54fe705e13f873a1f7f8ce764b897f42f91f75c5b4b0dee07329b577200230a7707a90284e73b554a339798575e084ce93f15
+  data.tar.gz: 40408cf8b88b878033226df711fbf3e57c217293b85b6eb7f94f55289eb7740d02dcc66598c5f594a3cd21821b5186eb38942c7e03747838a6487ccc37e018d1

data/lib/binpacker/calibration.rb

@@ -13,10 +13,13 @@ module Binpacker
       @timing = Timing.new(config.timing_file)
     end
 
-    def run(tests)
+    # Runs each Test serially and appends its measured Weight to the Timing file.
+    # With incremental: true, Tests that already have a measured Weight are skipped.
+    def run(tests, incremental: false)
+      targets = incremental ? unmeasured(tests) : tests
       results = []
 
-      tests.each do |test|
+      targets.each do |test|
         elapsed = run_single(test)
         results << { file: test.file, name: test.name, time: elapsed }
       end
@@ -27,21 +30,30 @@ module Binpacker
 
     private
 
+    def unmeasured(tests)
+      measured = @timing.load_raw
+      tests.reject { |test| measured.key?([@timing.normalize_path(test.file), test.name]) }
+    end
+
     def run_single(test)
       outfile = Tempfile.new("binpacker-cal")
       outfile.close
 
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+      # At file granularity the Test's name is its file path (see Test
+      # discovery), so there is no single example/method to filter — run the
+      # whole file. A per-test filter would match nothing and measure only
+      # load time.
+      file_unit = test.name == test.file
+
       case @config.test_runner
       when "rspec"
-        cmd = [
-          "rspec", test.file,
-          "--example", test.name,
-          "--format", "json", "--out", outfile.path
-        ]
+        cmd = ["rspec", test.file, "--format", "json", "--out", outfile.path]
+        cmd.push("--example", test.name) unless file_unit
       when "minitest"
-        cmd = ["ruby", "-Ilib:test", test.file, "--name", "/^#{Regexp.escape(test.name)}$/"]
+        cmd = ["ruby", "-Ilib:test", test.file]
+        cmd.push("--name", "/^#{Regexp.escape(test.name)}$/") unless file_unit
       else
         raise ConfigError, "unsupported runner for calibration: #{@config.test_runner}"
       end

data/lib/binpacker/cli.rb

@@ -15,6 +15,12 @@ module Binpacker
       @profile = nil
       @passthrough = []
       @quiet = false
+      @incremental = false
+      @report_path = nil
+      @skill_list = false
+      @skill_path = false
+      @skill_describe = false
+      @skill_name = nil
       parse!
     end
 
@@ -26,6 +32,10 @@ module Binpacker
         cmd_run
       when "init"
         cmd_init
+      when "skill"
+        cmd_skill
+      when "describe"
+        cmd_describe
       when "--version", "-v"
         puts "binpacker #{Binpacker::VERSION}"
       when "--help", "-h", nil
@@ -58,6 +68,26 @@ module Binpacker
         opts.on("--quiet", "Suppress worker output") do
           @quiet = true
         end
+
+        opts.on("--incremental", "Calibrate only tests without timing data") do
+          @incremental = true
+        end
+
+        opts.on("--report PATH", "(run) Write a JSON run report to PATH") do |v|
+          @report_path = v
+        end
+
+        opts.on("--list", "(skill) List bundled skills") do
+          @skill_list = true
+        end
+
+        opts.on("--path", "(skill) Print the SKILL.md path for <name>") do
+          @skill_path = true
+        end
+
+        opts.on("--describe", "(skill) Report project state and next skill") do
+          @skill_describe = true
+        end
       end
 
       # Extract passthrough arguments after "--"
@@ -67,7 +97,10 @@ module Binpacker
       end
 
       remaining = parser.parse(@args)
-      @command = remaining.shift
+      # A positional command wins; otherwise keep any command an option set
+      # (e.g. --version), so `binpacker --version` isn't clobbered to nil.
+      @command = remaining.shift || @command
+      @skill_name = remaining.shift
     end
 
     def cmd_init
@@ -78,6 +111,11 @@ module Binpacker
       end
 
       framework = detect_framework
+      unless ProjectState::SUPPORTED_FRAMEWORKS.include?(framework)
+        $stderr.puts "Detected #{framework} — binpacker supports rspec and minitest only."
+        $stderr.puts "No binpacker.yml was created."
+        exit 1
+      end
       pattern = framework == "minitest" ? "test/**/*_test.rb" : "spec/**/*_spec.rb"
       runner = framework
 
@@ -89,7 +127,7 @@ module Binpacker
             timing_file: binpacker.timings
             test_pattern: "#{pattern}"
             scheduler:
-              algorithm: lpt
+              algorithm: multifit
               steal_enabled: true
           ci:
             extends: default
@@ -110,21 +148,98 @@ module Binpacker
       discovery_klass = config.test_runner == "rspec" ? RSpecDiscovery : MinitestDiscovery
       tests = discovery_klass.new(config).enumerate
 
-      puts "Calibrating #{tests.size} tests..."
       cal = Calibration.new(config)
-      timings = cal.run(tests)
+
+      if @incremental
+        puts "Calibrating (incremental) #{tests.size} tests..."
+      else
+        puts "Calibrating #{tests.size} tests..."
+      end
+
+      timings = cal.run(tests, incremental: @incremental)
 
       total = timings.sum { |t| t[:time] }
-      puts "Calibration complete: #{tests.size} tests in #{total.round(2)}s"
+      measured = timings.size
+      skipped = tests.size - measured
+      summary = "Calibration complete: #{measured} #{pluralize(measured, 'test')} in #{total.round(2)}s"
+      summary += " (#{skipped} skipped, already measured)" if @incremental && skipped.positive?
+      puts summary
       puts "Timing data written to #{config.timing_file}"
     end
 
+    def cmd_skill
+      return cmd_describe if @skill_describe
+
+      if @skill_path
+        path = Skills.path(@skill_name)
+        if path
+          puts path
+        else
+          $stderr.puts "unknown skill: #{@skill_name}"
+          exit 1
+        end
+      elsif @skill_name && !@skill_list
+        print_skill(@skill_name)
+      else
+        list_skills
+      end
+    end
+
+    def cmd_describe
+      state = ProjectState.new
+      puts "binpacker project state:"
+      puts "  config (binpacker.yml): #{state.config_present? ? 'present' : 'missing'}"
+      puts "  timing data:            #{state.timing_present? ? 'present' : 'missing'}"
+      puts "  test framework:         #{state.framework || 'not detected'}"
+      puts "  CI wired for binpacker: #{state.ci_wired? ? 'yes' : 'no'}"
+      puts ""
+
+      unless state.supported_framework?
+        puts "binpacker supports rspec and minitest; #{state.framework} is not supported yet."
+        puts "Setup cannot proceed against a #{state.framework} suite."
+        return
+      end
+
+      rec = state.recommendation
+      puts "Recommended next skill: #{rec}"
+      puts "Run `binpacker skill #{rec}` to load its instructions."
+    end
+
+    def list_skills
+      skills = Skills.list
+      if skills.empty?
+        puts "No bundled skills found."
+        return
+      end
+      puts "Bundled skills:"
+      skills.each { |s| puts "  #{s[:name]}" }
+      puts ""
+      puts "Print a skill's instructions with `binpacker skill <name>`."
+    end
+
+    def print_skill(name)
+      unless Skills.exist?(name)
+        $stderr.puts "unknown skill: #{name}"
+        $stderr.puts "Run `binpacker skill` to list bundled skills."
+        exit 1
+      end
+
+      puts "# Skill: #{name}"
+      puts "# Source: #{Skills.path(name)}"
+      puts ""
+      puts Skills.body(name)
+    end
+
     def cmd_run
       config = Config.new(profile: @profile)
-      orchestrator = Orchestrator.new(config, passthrough: @passthrough, quiet: @quiet)
+      report_path = @report_path || config.report_file
+      orchestrator = Orchestrator.new(
+        config, passthrough: @passthrough, quiet: @quiet, report_path: report_path
+      )
 
       puts "binpacker starting (#{config.worker_count} workers, profile: #{config.profile})"
       result = orchestrator.run
+      puts "Run report written to #{report_path}" if report_path
       unit = test_unit_label(config)
 
       if result[:passed]
@@ -156,23 +271,30 @@ module Binpacker
           run          Execute tests across worker processes
           calibrate    Run tests serially to generate timing data
           init         Create binpacker.yml with auto-detected settings
+          describe     Report project state and recommend the next skill
+          skill        List or print bundled agent skills
 
         Options:
           --profile NAME   Select profile from binpacker.yml
+          --incremental    (calibrate) Measure only tests without timing data
+          --report PATH    (run) Write a JSON run report to PATH
+          --list           (skill) List bundled skills
+          --path           (skill) Print the SKILL.md path for <name>
+          --describe       (skill) Report project state and next skill
           --help           Show this message
 
         Examples:
           binpacker init
           binpacker run --profile ci
           binpacker run -- --tag ~slow
-          binpacker calibrate
+          binpacker calibrate --incremental
+          binpacker describe
+          binpacker skill binpacker-setup
       HELP
     end
 
     def detect_framework
-      return "minitest" if Dir.glob("test*/**/*_test.rb").any?
-      return "minitest" if Dir.glob("test*/**/test_*.rb").any?
-      "rspec"
+      ProjectState.new.framework || "rspec"
     end
   end
 end

data/lib/binpacker/config.rb

@@ -14,10 +14,11 @@ module Binpacker
       "timing_file" => "binpacker.timings",
       "test_pattern" => "spec/**/*_spec.rb",
       "test_exclude" => [],
+      "report_file" => nil,
       "scheduler" => {
         "strategy" => "static",
         "steal_enabled" => false,
-        "algorithm" => "lpt"
+        "algorithm" => "multifit"
       }
     }.freeze
 

data/lib/binpacker/orchestrator.rb

@@ -4,16 +4,18 @@ module Binpacker
   class Orchestrator
     BATCH_SIZE = 10
 
-    def initialize(config, passthrough: [], quiet: false)
+    def initialize(config, passthrough: [], quiet: false, report_path: nil)
       @config = config
       @passthrough = passthrough
       @quiet = quiet
+      @report_path = report_path
     end
 
     def run
       tests = discover
       timing = Timing.new(@config.timing_file)
       timings = timing.load_with_fallback(tests)
+      @timings = timings
 
       scheduler = Scheduler.for(@config.scheduler["algorithm"])
       queues = scheduler.partition(
@@ -22,6 +24,9 @@ module Binpacker
         timings: timings
       )
 
+      # Capture predicted per-Worker loads before execution drains the queues.
+      @predicted_loads = queues.map { |q| q.total_weight(timings) }
+
       runner_class = TestRunner.for(@config.test_runner)
       workers = queues.map.with_index do |queue, idx|
         Worker.new(idx, runner_class, passthrough: @passthrough, quiet: @quiet).tap(&:start)
@@ -96,6 +101,7 @@ module Binpacker
         }
       end
       progress.summary(worker_stats)
+      write_report(worker_stats, all_timings)
 
       finalize(timing, all_timings, all_passed, total_examples, passed_examples, tests)
     end
@@ -199,11 +205,25 @@ module Binpacker
         }
       end
       progress.summary(worker_stats)
+      write_report(worker_stats, all_timings)
 
       workers.each(&:cleanup)
       finalize(timing, all_timings, all_passed, total_examples, passed_examples, tests)
     end
 
+    def write_report(worker_stats, all_timings)
+      return unless @report_path
+
+      Report.new(
+        profile: @config.profile,
+        algorithm: @config.scheduler["algorithm"],
+        predicted_loads: @predicted_loads,
+        worker_stats: worker_stats,
+        all_timings: all_timings,
+        timings: @timings
+      ).write(@report_path)
+    end
+
     def drain_batch(queue)
       return [] if queue.nil? || queue.empty?
       batch = []

data/lib/binpacker/progress.rb

@@ -45,9 +45,9 @@ module Binpacker
       active.each_with_index do |s, i|
         t = format_time(s[:total_time])
         wid = worker_stats.index(s)
-        $stdout.puts "  Worker #{wid}: #{s[:files]} files, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
+        $stdout.puts "  Worker #{wid}: #{s[:files]} tests, #{t} | #{s[:examples]} examples, #{s[:passed]} passed"
       end
-      total_files = active.sum { |s| s[:files] }
+      total_tests = active.sum { |s| s[:files] }
       total_time = active.sum { |s| s[:total_time] }
       total_examples = active.sum { |s| s[:examples] }
       times = active.map { |s| s[:total_time] }
@@ -56,7 +56,7 @@ module Binpacker
       dev_pct = mean > 0 ? (max_dev / mean * 100).round(1) : 0
 
       $stdout.puts "  ──"
-      $stdout.puts "  Total: #{total_files} files, #{format_time(total_time)} | #{total_examples} examples"
+      $stdout.puts "  Total: #{total_tests} tests, #{format_time(total_time)} | #{total_examples} examples"
       $stdout.puts "  Balance: max deviation #{format_time(max_dev)} (#{dev_pct}%)"
     end
 
@@ -99,14 +99,12 @@ module Binpacker
       @last_ci_output = now
 
       parts = @workers.map.with_index do |w, i|
-        if w[:total] > 0 && w[:done] >= w[:total]
-          "W#{i}: done"
-        else
-          "W#{i}: #{w[:done]}/#{w[:total]}"
-        end
+        ratio = w[:total] > 0 ? "#{w[:done]}/#{w[:total]}" : "0/?"
+        "W#{i}: #{ratio}"
       end
       elapsed = (now - @start).round(1)
       $stdout.puts "[binpacker #{elapsed}s] #{parts.join(' | ')}"
+      $stdout.flush
     end
 
     def format_time(seconds)

data/lib/binpacker/project_state.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # Inspects the working directory to report binpacker's setup state and
+  # recommend the next skill. Backs `binpacker describe`.
+  # See docs/design/agent-workflows.md.
+  class ProjectState
+    CONFIG_FILE = "binpacker.yml"
+    DEFAULT_TIMING_FILE = "binpacker.timings"
+    SUPPORTED_FRAMEWORKS = %w[rspec minitest].freeze
+    TESTUNIT_HINT = %r{test-unit|test/unit}
+
+    def config_present?
+      File.exist?(CONFIG_FILE)
+    end
+
+    def timing_present?
+      File.exist?(timing_file)
+    end
+
+    # "rspec", "minitest", "test-unit", or nil. Minitest and test-unit share
+    # the *_test.rb convention, so they are told apart by dependency hints.
+    def framework
+      return minitest_family if minitest_globs?
+      return "rspec" if Dir.glob("spec/**/*_spec.rb").any?
+      nil
+    end
+
+    # binpacker ships runners for rspec and minitest only. A detected framework
+    # outside that set (e.g. test-unit) is unsupported; nil is merely unknown.
+    def supported_framework?
+      fw = framework
+      fw.nil? || SUPPORTED_FRAMEWORKS.include?(fw)
+    end
+
+    def ci_wired?
+      Dir.glob(".github/workflows/*.{yml,yaml}").any? do |wf|
+        File.read(wf).include?("binpacker run")
+      end
+    end
+
+    # The skill the agent should run next.
+    def recommendation
+      return "binpacker-setup" unless config_present? && timing_present?
+      "binpacker-improve"
+    end
+
+    def to_h
+      {
+        config_present: config_present?,
+        timing_present: timing_present?,
+        framework: framework,
+        ci_wired: ci_wired?,
+        recommendation: recommendation
+      }
+    end
+
+    private
+
+    def minitest_globs?
+      Dir.glob("test*/**/*_test.rb").any? || Dir.glob("test*/**/test_*.rb").any?
+    end
+
+    def minitest_family
+      testunit_hinted? ? "test-unit" : "minitest"
+    end
+
+    def testunit_hinted?
+      sources = Dir.glob("Gemfile") + Dir.glob("*.gemspec") + Dir.glob("test*/**/*_test.rb").first(5)
+      sources.any? { |file| File.read(file).match?(TESTUNIT_HINT) }
+    rescue StandardError
+      false
+    end
+
+    def timing_file
+      return DEFAULT_TIMING_FILE unless config_present?
+      Config.new.timing_file
+    rescue StandardError
+      DEFAULT_TIMING_FILE
+    end
+  end
+end

data/lib/binpacker/report.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Binpacker
+  # Builds the machine-readable Run report: predicted versus actual per-Worker
+  # durations plus the worst per-Test Drift. See docs/design/run-report-format.md.
+  class Report
+    SCHEMA = 1
+    DRIFT_LIMIT = 10
+
+    def initialize(profile:, algorithm:, predicted_loads:, worker_stats:, all_timings:, timings:)
+      @profile = profile
+      @algorithm = algorithm
+      @predicted_loads = predicted_loads
+      @worker_stats = worker_stats
+      @all_timings = all_timings
+      @timings = timings
+    end
+
+    def to_h
+      predicted = @predicted_loads
+      actual = @worker_stats.map { |s| s[:total_time] }
+
+      {
+        schema: SCHEMA,
+        profile: @profile,
+        algorithm: @algorithm,
+        worker_count: @worker_stats.size,
+        predicted_makespan: round(predicted.max || 0.0),
+        actual_makespan: round(actual.max || 0.0),
+        workers: workers,
+        balance: {
+          predicted_deviation_pct: deviation_pct(predicted),
+          actual_deviation_pct: deviation_pct(actual)
+        },
+        drift: drift
+      }
+    end
+
+    def write(path)
+      File.write(path, JSON.pretty_generate(to_h))
+    end
+
+    private
+
+    def workers
+      @worker_stats.map.with_index do |s, i|
+        {
+          id: i,
+          predicted: round(@predicted_loads[i] || 0.0),
+          actual: round(s[:total_time]),
+          tests: s[:files],
+          examples: s[:examples]
+        }
+      end
+    end
+
+    # Drift is reported per file (the scheduling unit), so predicted and actual
+    # are compared at the same granularity even when timings are recorded
+    # per example. Both sides are aggregated to normalized file paths.
+    def drift
+      actual = aggregate_by_file(@all_timings.map { |e| [e[:file], e[:time]] })
+      predicted = aggregate_by_file(@timings.map { |(file, _name), weight| [file, weight] })
+
+      (actual.keys | predicted.keys)
+        .map { |file| drift_entry(file, predicted[file], actual[file]) }
+        .sort_by { |d| -(d[:actual] - d[:predicted]).abs }
+        .first(DRIFT_LIMIT)
+    end
+
+    def drift_entry(file, predicted, actual)
+      {
+        file: file,
+        predicted: round(predicted || Timing::DEFAULT_WEIGHT),
+        actual: round(actual || 0.0)
+      }
+    end
+
+    def aggregate_by_file(pairs)
+      pairs.each_with_object(Hash.new(0.0)) do |(file, time), acc|
+        acc[normalize_file(file)] += time
+      end
+    end
+
+    def normalize_file(file)
+      file.to_s.sub(%r{\A\./}, "")
+    end
+
+    def deviation_pct(loads)
+      return 0.0 if loads.empty?
+      mean = loads.sum / loads.size
+      return 0.0 unless mean.positive?
+      max_dev = loads.map { |t| (t - mean).abs }.max
+      round(max_dev / mean * 100)
+    end
+
+    def round(value)
+      value.to_f.round(3)
+    end
+  end
+end

data/lib/binpacker/skills.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Binpacker
+  # Registry for the gem-shipped, user-facing agent skills. Skills live in the
+  # gem's top-level skills/ directory, each as skills/<name>/SKILL.md.
+  # See docs/adr/0003-agent-driven-install-and-skills.md.
+  module Skills
+    ROOT = File.expand_path("../../skills", __dir__)
+
+    module_function
+
+    # [{ name:, path: }], sorted by name.
+    def list
+      Dir.glob(File.join(ROOT, "*", "SKILL.md")).sort.map do |file|
+        { name: File.basename(File.dirname(file)), path: file }
+      end
+    end
+
+    def exist?(name)
+      !path(name).nil?
+    end
+
+    # Absolute path of a skill's SKILL.md, or nil when unknown.
+    def path(name)
+      file = File.join(ROOT, name, "SKILL.md")
+      File.file?(file) ? file : nil
+    end
+
+    # The SKILL.md body for a skill.
+    def body(name)
+      file = path(name)
+      raise Error, "unknown skill: #{name}" unless file
+      File.read(file)
+    end
+  end
+end

data/lib/binpacker/test_discovery.rb

@@ -69,7 +69,13 @@ module Binpacker
 
   class MinitestDiscovery < TestDiscovery
     def enumerate
-      require "minitest"
+      begin
+        require "minitest"
+      rescue LoadError
+        raise DiscoveryError,
+          "minitest is not available. binpacker supports rspec and minitest; " \
+          "test-unit and other frameworks are not supported."
+      end
       add_project_load_paths
       def Minitest.autorun; end
       Minitest.seed = 42

data/lib/binpacker/timing.rb

@@ -44,6 +44,11 @@ module Binpacker
       Pathname(path).cleanpath.to_s.sub(/\A\.\//, "")
     end
 
+    # True when a measured Weight already exists for this Test.
+    def measured?(file:, name:)
+      load_raw.key?([normalize_path(file), name])
+    end
+
     def weight_for(file:, name:)
       measured = load_raw
       measured.fetch([file, name]) { filesize_weight(file) }

data/lib/binpacker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Binpacker
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/binpacker.rb

@@ -9,6 +9,9 @@ require_relative "binpacker/scheduler"
 require_relative "binpacker/worker"
 require_relative "binpacker/test_runner"
 require_relative "binpacker/calibration"
+require_relative "binpacker/report"
+require_relative "binpacker/skills"
+require_relative "binpacker/project_state"
 require_relative "binpacker/orchestrator"
 require_relative "binpacker/progress"
 

data/sig/binpacker/calibration.rbs

@@ -0,0 +1,6 @@
+module Binpacker
+  class Calibration
+    def initialize: (untyped) -> void
+    def run: (untyped, ?incremental: bool) -> Array[untyped]
+  end
+end

data/sig/binpacker/cli.rbs

@@ -0,0 +1,7 @@
+module Binpacker
+  class CLI
+    def self.start: (untyped) -> nil
+    def initialize: (untyped) -> void
+    def run: () -> nil
+  end
+end

data/sig/binpacker/config.rbs

@@ -0,0 +1,13 @@
+module Binpacker
+  class Config
+    def initialize: (?profile: untyped, ?config_path: untyped) -> void
+    def worker_count: () -> Integer
+    def test_runner: () -> String
+    def timing_file: () -> String
+    def test_pattern: () -> String
+    def test_exclude: () -> Array[String]
+    def test_granularity: () -> String
+    def report_file: () -> String?
+    def profile: () -> String
+  end
+end

data/sig/binpacker/orchestrator.rbs

@@ -0,0 +1,6 @@
+module Binpacker
+  class Orchestrator
+    def initialize: (untyped, ?passthrough: untyped, ?quiet: untyped, ?report_path: untyped) -> void
+    def run: () -> { passed: untyped, total: untyped, passed_count: untyped, timings: Array[untyped], empty_filter: untyped }
+  end
+end

data/sig/binpacker/progress.rbs

@@ -0,0 +1,5 @@
+module Binpacker
+  class ProgressDisplay
+    def initialize: (untyped, ?tty: untyped) -> void
+  end
+end

data/sig/binpacker/project_state.rbs

@@ -0,0 +1,16 @@
+module Binpacker
+  class ProjectState
+    CONFIG_FILE: String
+    DEFAULT_TIMING_FILE: String
+    SUPPORTED_FRAMEWORKS: Array[String]
+    TESTUNIT_HINT: Regexp
+
+    def config_present?: () -> bool
+    def timing_present?: () -> bool
+    def framework: () -> String?
+    def supported_framework?: () -> bool
+    def ci_wired?: () -> bool
+    def recommendation: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/binpacker/report.rbs

@@ -0,0 +1,10 @@
+module Binpacker
+  class Report
+    SCHEMA: Integer
+    DRIFT_LIMIT: Integer
+
+    def initialize: (profile: untyped, algorithm: untyped, predicted_loads: untyped, worker_stats: untyped, all_timings: untyped, timings: untyped) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def write: (untyped) -> untyped
+  end
+end

data/sig/binpacker/scheduler.rbs

@@ -0,0 +1,5 @@
+module Binpacker
+  class Scheduler
+    def self.for: (untyped) -> (Binpacker::LptScheduler | Binpacker::MultifitScheduler)
+  end
+end

data/sig/binpacker/skills.rbs

@@ -0,0 +1,10 @@
+module Binpacker
+  module Skills
+    ROOT: String
+
+    def self.list: () -> Array[Hash[Symbol, String]]
+    def self.exist?: (untyped) -> bool
+    def self.path: (untyped) -> String?
+    def self.body: (untyped) -> String
+  end
+end

data/sig/binpacker/test_discovery.rbs

@@ -0,0 +1,15 @@
+module Binpacker
+  def key: () -> [untyped, String]
+  class TestDiscovery
+    def initialize: (untyped) -> void
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class RSpecDiscovery < TestDiscovery
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class MinitestDiscovery < TestDiscovery
+    def enumerate: () -> Array[Binpacker::Test]
+  end
+  class Test
+  end
+end

data/sig/binpacker/test_runner.rbs

@@ -0,0 +1,13 @@
+module Binpacker
+  class TestRunner
+    def self.runner_name: () -> bot
+    def self.for: (untyped) -> (singleton(Binpacker::MinitestRunner) | singleton(Binpacker::RSpecRunner))
+  end
+  class RSpecRunner
+    def self.runner_name: () -> "rspec"
+    def self.discovery_command: (untyped) -> Array[untyped]
+  end
+  class MinitestRunner
+    def self.runner_name: () -> "minitest"
+  end
+end

data/sig/binpacker/timing.rbs

@@ -0,0 +1,11 @@
+module Binpacker
+  class Timing
+    def initialize: (untyped) -> void
+    def load_raw: () -> (Hash[[String, untyped], untyped] | {})
+    def load_per_file: () -> (Hash[String, untyped] | {})
+    def normalize_path: (untyped) -> String
+    def measured?: (file: untyped, name: untyped) -> bool
+    class Entry
+    end
+  end
+end

data/sig/binpacker/worker.rbs

@@ -0,0 +1,12 @@
+module Binpacker
+  class Worker
+    def initialize: (untyped, untyped, ?passthrough: untyped, ?quiet: untyped) -> void
+    def start: () -> Binpacker::Worker
+    def send_test: (untyped) -> nil
+    def batch_done: () -> nil
+    def wait_for_batch: () -> (nil | { timings: [], exit_code: 0 | 1, examples: untyped, passed: untyped } | { timings: [], exit_code: untyped, examples: untyped, passed: untyped })
+    def collect_results: () -> :finished
+    def timings: () -> Array[untyped]
+    def status: () -> (:crashed | :created | :error | :finished | :ready | :running)
+  end
+end

data/sig/binpacker/worker_queue.rbs

@@ -0,0 +1,6 @@
+module Binpacker
+  class WorkerQueue
+    def initialize: (untyped, ?untyped) -> void
+    def empty?: () -> (false | true)
+  end
+end

data/skills/binpacker-improve/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: binpacker-improve
+description: Tune an already-configured binpacker project from real CI data — fetch recent run reports, analyze the gap between predicted and actual durations, and propose binpacker.yml adjustments. Use when binpacker is set up and running in CI and the user wants to reduce makespan, fix worker imbalance, or refresh stale timing data. Propose-only — never apply changes without confirmation.
+---
+
+# Binpacker Improve
+
+A recurring, **propose-only** workflow. It reads real CI data and proposes config changes; it never edits `binpacker.yml`, commits, or pushes without explicit user confirmation.
+
+Run `binpacker describe` first. If it recommends `binpacker-setup`, the project isn't configured yet — use that skill instead.
+
+## 1. Gather CI data
+
+Fetch recent run reports (see `docs/design/run-report-format.md` for the schema) from CI artifacts:
+
+```sh
+gh run list --workflow <ci-workflow> --limit 10
+gh run download <run-id> --name <report-artifact>
+```
+
+Collect several recent reports so you can see trends, not just one run. Each report holds `predicted_makespan`, `actual_makespan`, per-worker predicted/actual durations, `balance`, and the worst-drift Tests.
+
+## 2. Analyze
+
+Look for patterns across the reports:
+
+- **Persistent worker skew** — the same worker is consistently slowest → the partition or worker count is off.
+- **Predicted vs actual gap** — `actual_makespan` far above `predicted_makespan` → timing data is stale; the scheduler is planning against wrong Weights.
+- **Recurring high-drift files** — the same files top the `drift` list every run → their timing data is stale or they are outliers.
+- **Cache-miss frequency** — if CI logs show frequent timing-cache misses (e.g. after dependency bumps), the runtime cache isn't helping cold starts.
+
+## 3. Propose
+
+Present a concrete `binpacker.yml` diff and/or commands, with the evidence behind each change. Typical levers:
+
+- **`workers`** — raise/lower the `ci` worker count when actual makespan shows consistent under- or over-utilisation.
+- **`scheduler.algorithm`** — `lpt` ↔ `multifit`. Prefer `multifit` for tighter balance; only suggest `lpt` if `multifit` isn't helping.
+- **`scheduler.steal_enabled`** — enable when static balance is poor but runtime stealing would recover it.
+- **Re-calibrate** — when drift is high or timing is stale, recommend `binpacker calibrate --incremental` to refresh the drifting Tests.
+- **Commit a baseline** — when the cache misses often (dependency-bump churn) or timings have stabilised, recommend committing `binpacker.timings` as a durable baseline (cold-start floor). See `docs/adr/0005-two-tier-timing-persistence.md`.
+
+## 4. Confirm and apply
+
+- Show the diff. Explain the expected effect (e.g. "should cut max deviation from 6% toward <3%").
+- Apply only what the user approves. Committing a baseline or editing config both require confirmation.
+- If the user wants, open a PR with `gh`; otherwise leave the working tree changes for them to review.
+
+## Done when
+
+- The user has seen the predicted-vs-actual analysis with evidence.
+- A concrete, confirmed set of changes (or an explicit "no change needed") has been reached.
+- Any commit / PR was made only with confirmation.

data/skills/binpacker-setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: binpacker-setup
+description: Bring a project from zero to a working parallel test run with binpacker — detect the framework, generate config, calibrate timing data, validate a parallel run, and wire CI. Use when binpacker is installed but not yet set up (no binpacker.yml, or no timing data), or when the user asks to set up / configure / adopt binpacker.
+---
+
+# Binpacker Setup
+
+A one-time workflow that takes a project from zero to a working parallel test run. Run `binpacker describe` first — if it recommends `binpacker-improve`, the project is already set up and you want that skill instead.
+
+Assess state as you go and **ask the user at each decision point** rather than assuming. Do not run destructive or outward-facing steps (committing, opening a PR) without explicit confirmation.
+
+## 1. Detect
+
+- Confirm binpacker is installed: `binpacker --version`.
+- Run `binpacker describe` to read current state (config present? timing data? framework? CI wired?).
+- Determine the test framework (rspec / minitest) and the test glob. If `binpacker describe` reports one, trust it; otherwise inspect the repo.
+
+## 2. Config
+
+If `binpacker.yml` is absent, create it with `binpacker init` (it auto-detects the framework and writes `default` + `ci` profiles). Then review the generated file with the user and adjust:
+
+- `workers` — `auto` locally; a fixed number (e.g. `4`) for the `ci` profile matching the CI runner.
+- `test_pattern` / `test_exclude` — match the project's real layout.
+- `scheduler.algorithm` — `multifit` (default) unless there's a reason to use `lpt`.
+- `scheduler.steal_enabled` — `true` to let idle workers steal at runtime.
+- `report_file` (on the `ci` profile) — e.g. `binpacker-report.json`, so CI always emits a run report.
+
+## 3. Calibrate
+
+Seed timing data so the scheduler has real Weights:
+
+```sh
+binpacker calibrate
+```
+
+If some timing data already exists, measure only the gaps:
+
+```sh
+binpacker calibrate --incremental
+```
+
+## 4. Validate
+
+Run the suite in parallel and confirm it is green and balanced:
+
+```sh
+binpacker run
+```
+
+Check the summary's `Balance: max deviation`. A large deviation on the first run is expected before timing data accumulates; note it and move on.
+
+## 5. Wire CI
+
+Add (or extend) a CI workflow so the suite runs under binpacker. The workflow should:
+
+- Install binpacker (via the project's dependency manager or `gem install binpacker`).
+- Restore and save `binpacker.timings` with `actions/cache` (key includes OS + a hash of the test files). This is the runtime timing layer.
+- Run `binpacker run --profile ci` (which emits the run report via `report_file`).
+- Upload the run report with `actions/upload-artifact` so `binpacker-improve` can read it later.
+
+Propose the workflow YAML and let the user review it before writing.
+
+## 6. Handoff
+
+Only after the user confirms:
+
+- Create a branch, commit `binpacker.yml`, the CI workflow, and (if the user wants a committed baseline) `binpacker.timings`.
+- Open a PR with `gh`, summarising what was set up.
+- After CI runs, point the user at `binpacker-improve` to tune from real CI data.
+
+## Done when
+
+- `binpacker run` passes locally across workers.
+- `binpacker.yml` reflects the project's framework, layout, and CI worker count.
+- CI runs `binpacker run` and uploads a run report.
+- The user has confirmed any commit / PR.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binpacker
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - megurine
@@ -9,8 +9,9 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A test runner wrapper that manages worker processes and distributes tests
-  among them using LPT scheduling with optional work-stealing.
+description: A test runner wrapper that models test distribution as an identical-machines
+  scheduling problem and assigns tests to worker processes using LPT scheduling, with
+  optional work-stealing.
 executables:
 - binpacker
 extensions: []
@@ -25,13 +26,32 @@ files:
 - lib/binpacker/config.rb
 - lib/binpacker/orchestrator.rb
 - lib/binpacker/progress.rb
+- lib/binpacker/project_state.rb
+- lib/binpacker/report.rb
 - lib/binpacker/scheduler.rb
+- lib/binpacker/skills.rb
 - lib/binpacker/test_discovery.rb
 - lib/binpacker/test_runner.rb
 - lib/binpacker/timing.rb
 - lib/binpacker/version.rb
 - lib/binpacker/worker.rb
 - lib/binpacker/worker_queue.rb
+- sig/binpacker/calibration.rbs
+- sig/binpacker/cli.rbs
+- sig/binpacker/config.rbs
+- sig/binpacker/orchestrator.rbs
+- sig/binpacker/progress.rbs
+- sig/binpacker/project_state.rbs
+- sig/binpacker/report.rbs
+- sig/binpacker/scheduler.rbs
+- sig/binpacker/skills.rbs
+- sig/binpacker/test_discovery.rbs
+- sig/binpacker/test_runner.rbs
+- sig/binpacker/timing.rbs
+- sig/binpacker/worker.rbs
+- sig/binpacker/worker_queue.rbs
+- skills/binpacker-improve/SKILL.md
+- skills/binpacker-setup/SKILL.md
 homepage: https://github.com/rigortype/binpacker
 licenses:
 - MPL-2.0
@@ -54,6 +74,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Minimize CI test-suite makespan by solving an identical-machines scheduling
-  problem
+summary: Reduce CI test-suite makespan via identical-machines scheduling
 test_files: []