polyrun 1.5.0 → 2.1.2

data/lib/polyrun/cli/run_shards_parallel_children.rb

@@ -46,7 +46,8 @@ module Polyrun
             shard: shard,
             matrix_index: mx,
             matrix_total: mt,
-            failure_fragments: ctx[:merge_failures]
+            failure_fragments: ctx[:merge_failures],
+            spec_quality_fragments: ctx[:merge_spec_quality]
           )
           child_env = child_env.merge("POLYRUN_HOOK_ORCHESTRATOR" => "0")
           child_env = hook_cfg.merge_worker_ruby_env(child_env)

data/lib/polyrun/cli/run_shards_parallel_wait.rb

@@ -2,6 +2,10 @@
 module Polyrun
   class CLI
     # Wait, wall/idle timeout, and +after_shard+ hooks for parallel workers (+run-shards+ / +ci-shard-*+).
+    #
+    # Per-worker wait states: running → normal_exit | wall_timeout (124) | idle_timeout (125).
+    # When wall or idle caps are set, the multiplex loop polls every live PID each tick so timeouts
+    # apply fairly across shards (not only the worker currently in Process.wait).
     module RunShardsParallelWait
       WORKER_TIMEOUT_EXIT_STATUS = 124
       WORKER_IDLE_TIMEOUT_EXIT_STATUS = 125
@@ -215,7 +219,7 @@ module Polyrun
         ping_suffix = (loc && !loc.to_s.strip.empty?) ? "; last ping #{loc.to_s.strip}" : ""
         Polyrun::Log.orchestration_warn "polyrun run-shards: WORKER IDLE TIMEOUT after #{idle_sec}s since last per-example progress ping — shard #{h[:shard]} pid #{h[:pid]}#{ping_suffix}."
         Polyrun::Log.warn "polyrun run-shards: idle shard file sample: #{sample}#{suffix}"
-        Polyrun::Log.warn "polyrun run-shards: use Polyrun::RSpec.install_worker_ping! / Polyrun::Minitest.install_worker_ping! (Polyrun Quick calls ping! each example); exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
+        Polyrun::Log.warn "polyrun run-shards: enable per-example worker progress pings in your test setup so idle timeouts reflect real work; exit #{WORKER_IDLE_TIMEOUT_EXIT_STATUS}."
       end
 
       def run_shards_wait_or_force_stop_status(pid)

data/lib/polyrun/cli/run_shards_plan_boot_phases.rb

@@ -1,3 +1,4 @@
+# rubocop:disable Polyrun/FileLength -- run-shards boot phases A/B
 require "shellwords"
 
 module Polyrun
@@ -27,17 +28,35 @@ module Polyrun
         [:ok, o, cmd]
       end
 
+      # rubocop:disable Metrics/AbcSize -- items + costs + plan emit for run-shards
       def run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
         items, paths_source, err = run_shards_resolve_items(o[:paths_file], pc)
         return [err, nil] if err
 
-        costs, strategy, err = run_shards_resolve_costs(o[:timing_path], o[:strategy], o[:timing_granularity])
+        costs, strategy, err = run_shards_resolve_costs(
+          o[:timing_path],
+          o[:strategy],
+          o[:timing_granularity],
+          strategy_explicit: o[:strategy_explicit]
+        )
         return [err, nil] if err
 
         run_shards_plan_ready_log(o, cfg, strategy, cmd, paths_source, items.size)
 
         constraints = load_partition_constraints(pc, o[:constraints_path])
-        plan = run_shards_make_plan(items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity])
+        stable = load_stable_assignment(pc)
+        plan = run_shards_make_plan(
+          items, o[:workers], strategy, o[:seed], costs, constraints, o[:timing_granularity], stable,
+          shard_weights: pc["shard_weights"] || pc[:shard_weights]
+        )
+
+        partition_emit_diagnostics!(
+          plan: plan,
+          items: items,
+          costs: costs,
+          timing_path: o[:timing_path],
+          granularity: o[:timing_granularity]
+        )
 
         run_shards_debug_shard_sizes(plan, o[:workers])
         Polyrun::Log.warn "polyrun run-shards: #{items.size} paths → #{o[:workers]} workers (#{strategy})" if @verbose
@@ -47,6 +66,7 @@ module Polyrun
 
         [nil, run_shards_plan_context_hash(o, cmd, cfg, plan, run_t0, parallel, config_path)]
       end
+      # rubocop:enable Metrics/AbcSize
 
       def run_shards_plan_boot(argv, config_path)
         run_t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -69,6 +89,7 @@ module Polyrun
           strategy: strategy,
           merge_coverage: o[:merge_coverage],
           merge_failures: run_shards_merge_failures_flag(o, cfg),
+          merge_spec_quality: run_shards_merge_spec_quality_flag(o, cfg),
           command: cmd,
           timing_path: o[:timing_path],
           paths_source: paths_source,
@@ -76,6 +97,26 @@ module Polyrun
         )
       end
 
+      def run_shards_merge_spec_quality_flag(o, cfg)
+        return true if o[:merge_spec_quality]
+        return true if %w[1 true yes].include?(ENV["POLYRUN_MERGE_SPEC_QUALITY"].to_s.downcase)
+
+        rep = cfg.reporting
+        v = rep["merge_spec_quality"] || rep[:merge_spec_quality]
+        v == true || %w[1 true yes].include?(v.to_s.downcase)
+      end
+
+      def run_shards_merge_spec_quality_output_opt(o, cfg)
+        x = o[:merge_spec_quality_output]
+        return x if x && !x.to_s.strip.empty?
+
+        x = ENV["POLYRUN_MERGED_SPEC_QUALITY_OUT"]
+        return x if x && !x.to_s.strip.empty?
+
+        rep = cfg.reporting
+        rep["merge_spec_quality_output"] || rep[:merge_spec_quality_output]
+      end
+
       def run_shards_merge_failures_flag(o, cfg)
         return true if o[:merge_failures]
         return true if %w[1 true yes].include?(ENV["POLYRUN_MERGE_FAILURES"].to_s.downcase)
@@ -121,6 +162,9 @@ module Polyrun
           merge_failures: run_shards_merge_failures_flag(o, cfg),
           merge_failures_output: run_shards_merge_failures_output_opt(o, cfg),
           merge_failures_format: run_shards_merge_failures_format_opt(o, cfg),
+          merge_spec_quality: run_shards_merge_spec_quality_flag(o, cfg),
+          merge_spec_quality_output: run_shards_merge_spec_quality_output_opt(o, cfg),
+          report_spec_quality: o[:report_spec_quality] != false,
           config_path: config_path,
           worker_timeout_sec: run_shards_resolved_worker_timeout_sec(o),
           worker_idle_timeout_sec: run_shards_resolved_worker_idle_timeout_sec(o)
@@ -157,3 +201,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/cli/run_shards_plan_options.rb

@@ -18,6 +18,7 @@ module Polyrun
           workers: env_int("POLYRUN_WORKERS", Polyrun::Config::DEFAULT_PARALLEL_WORKERS),
           paths_file: nil,
           strategy: (pc["strategy"] || pc[:strategy] || "round_robin").to_s,
+          strategy_explicit: !!(pc["strategy"] || pc[:strategy]),
           seed: pc["seed"] || pc[:seed],
           timing_path: nil,
           constraints_path: nil,
@@ -28,6 +29,9 @@ module Polyrun
           merge_failures: false,
           merge_failures_output: nil,
           merge_failures_format: nil,
+          merge_spec_quality: false,
+          merge_spec_quality_output: nil,
+          report_spec_quality: true,
           worker_timeout_sec: nil,
           worker_idle_timeout_sec: nil
         }
@@ -41,11 +45,14 @@ module Polyrun
 
       # rubocop:disable Metrics/AbcSize -- one argv block for run-shards
       def run_shards_plan_options_register!(opts, st)
-        opts.banner = "usage: polyrun run-shards [--workers N] [--worker-timeout SEC] [--worker-idle-timeout SEC] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--] <command> [args...]"
+        opts.banner = "usage: polyrun run-shards [--workers N] [--worker-timeout SEC] [--worker-idle-timeout SEC] [--strategy NAME] [--paths-file P] [--timing P] [--timing-granularity VAL] [--constraints P] [--seed S] [--merge-coverage] [--merge-output P] [--merge-format LIST] [--merge-failures] [--merge-failures-output P] [--merge-failures-format jsonl|json] [--merge-spec-quality] [--merge-spec-quality-output P] [--no-report-spec-quality] [--] <command> [args...]"
         opts.on("--workers N", Integer) { |v| st[:workers] = v }
         opts.on("--worker-timeout SEC", Float, "Max seconds per worker since spawn (also POLYRUN_WORKER_TIMEOUT_SEC); kills stuck workers (exit 124)") { |v| st[:worker_timeout_sec] = v }
-        opts.on("--worker-idle-timeout SEC", Float, "Max seconds since last valid WorkerPing timestamp in POLYRUN_WORKER_PING_FILE (needs prior ping); RSpec/Minitest: install_worker_ping!; Quick: automatic; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
-        opts.on("--strategy NAME", String) { |v| st[:strategy] = v }
+        opts.on("--worker-idle-timeout SEC", Float, "Max seconds since last worker progress ping (POLYRUN_WORKER_PING_FILE); enable pings in test setup; exit 125") { |v| st[:worker_idle_timeout_sec] = v }
+        opts.on("--strategy NAME", String) do |v|
+          st[:strategy] = v
+          st[:strategy_explicit] = true
+        end
         opts.on("--seed VAL") { |v| st[:seed] = v }
         opts.on("--paths-file PATH", String) { |v| st[:paths_file] = v }
         opts.on("--constraints PATH", String) { |v| st[:constraints_path] = v }
@@ -54,9 +61,12 @@ module Polyrun
         opts.on("--merge-coverage", "After success, merge coverage/polyrun-fragment-*.json (Polyrun coverage must be enabled)") { st[:merge_coverage] = true }
         opts.on("--merge-output PATH", String) { |v| st[:merge_output] = v }
         opts.on("--merge-format LIST", String) { |v| st[:merge_format] = v }
-        opts.on("--merge-failures", "After all workers exit, merge tmp/polyrun_failures/polyrun-failure-fragment-*.jsonl (use Polyrun::RSpec.install_failure_fragments!)") { st[:merge_failures] = true }
+        opts.on("--merge-failures", "After all workers exit, merge failure fragments from tmp/polyrun_failures (requires failure fragments in test setup)") { st[:merge_failures] = true }
         opts.on("--merge-failures-output PATH", String) { |v| st[:merge_failures_output] = v }
         opts.on("--merge-failures-format VAL", "jsonl (default) or json") { |v| st[:merge_failures_format] = v }
+        opts.on("--merge-spec-quality", "After workers exit, merge spec-quality fragments from coverage (enable spec-quality collection in test setup)") { st[:merge_spec_quality] = true }
+        opts.on("--merge-spec-quality-output PATH", String) { |v| st[:merge_spec_quality_output] = v }
+        opts.on("--no-report-spec-quality", "Skip printing spec-quality report after merge") { st[:report_spec_quality] = false }
       end
       # rubocop:enable Metrics/AbcSize
     end

data/lib/polyrun/cli/run_shards_planning.rb

@@ -23,13 +23,10 @@ module Polyrun
         run_shards_plan_phase_b(o, cmd, cfg, pc, run_t0, config_path)
       end
 
-      def run_shards_default_timing_path(pc, timing_path, strategy)
+      def run_shards_default_timing_path(pc, timing_path, _strategy = nil)
         return timing_path if timing_path
 
-        tf = pc["timing_file"] || pc[:timing_file]
-        return tf if tf && (Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy))
-
-        nil
+        pc["timing_file"] || pc[:timing_file]
       end
 
       def run_shards_validate_workers!(o)
@@ -70,8 +67,13 @@ module Polyrun
         [items, paths_source, nil]
       end
 
-      def run_shards_resolve_costs(timing_path, strategy, timing_granularity)
+      def run_shards_resolve_costs(timing_path, strategy, timing_granularity, strategy_explicit: false)
+        strategy = strategy.to_s
         if timing_path
+          if strategy_explicit && strategy == "round_robin"
+            return [nil, strategy, nil]
+          end
+
           costs = Polyrun::Partition::Plan.load_timing_costs(
             File.expand_path(timing_path.to_s, Dir.pwd),
             granularity: timing_granularity
@@ -80,12 +82,16 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: timing file missing or empty: #{timing_path}"
             return [nil, nil, 2]
           end
-          unless Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.hrw_strategy?(strategy)
+          if Polyrun::Partition::Plan.timing_load_strategy?(strategy)
+            return [costs, strategy, nil]
+          end
+          unless strategy_explicit
             Polyrun::Log.warn "polyrun run-shards: using cost_binpack (timing data present)" if @verbose
-            strategy = "cost_binpack"
+            return [costs, "cost_binpack", nil]
           end
-          [costs, strategy, nil]
-        elsif Polyrun::Partition::Plan.cost_strategy?(strategy)
+
+          [nil, strategy, nil]
+        elsif Polyrun::Partition::Plan.cost_strategy?(strategy) || Polyrun::Partition::Plan.lazy_robin_strategy?(strategy)
           Polyrun::Log.warn "polyrun run-shards: --timing or partition.timing_file required for strategy #{strategy}"
           [nil, nil, 2]
         else
@@ -93,7 +99,7 @@ module Polyrun
         end
       end
 
-      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity)
+      def run_shards_make_plan(items, workers, strategy, seed, costs, constraints, timing_granularity, stable_assignment = nil, shard_weights: nil)
         Polyrun::Debug.time("Partition::Plan.new (partition #{items.size} paths → #{workers} shards)") do
           Polyrun::Partition::Plan.new(
             items: items,
@@ -103,7 +109,9 @@ module Polyrun
             costs: costs,
             constraints: constraints,
             root: Dir.pwd,
-            timing_granularity: timing_granularity
+            timing_granularity: timing_granularity,
+            stable_assignment: stable_assignment,
+            shard_weights: shard_weights
           )
         end
       end

data/lib/polyrun/cli/run_shards_run.rb

@@ -1,5 +1,6 @@
 require "shellwords"
 require "rbconfig"
+require "json"
 
 require_relative "run_shards_planning"
 require_relative "run_shards_worker_interrupt"
@@ -22,13 +23,15 @@ module Polyrun
         run_shards_workers_and_merge(ctx)
       end
 
-      # rubocop:disable Metrics/AbcSize -- orchestration: hooks, merge, worker failures
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- orchestration: hooks, merge, worker failures
       def run_shards_workers_and_merge(ctx)
         hook_cfg = Polyrun::Hooks.from_config(ctx[:cfg])
         suite_started = false
         exit_code = 1
         merged_failures_path = nil
         merge_failures_errored = false
+        merge_spec_quality_errored = false
+        spec_quality_strict_failed = false
 
         begin
           env_suite = ENV.to_h.merge(
@@ -64,6 +67,20 @@ module Polyrun
             Polyrun::Log.warn "polyrun run-shards: finished #{pids.size} worker(s)" + (failed.any? ? " (some failed)" : " (exit 0)")
           end
 
+          if ctx[:merge_spec_quality]
+            begin
+              merged_sq_path = merge_spec_quality_after_shards(ctx)
+              if merged_sq_path && ctx[:report_spec_quality]
+                cfg = load_spec_quality_config(nil)
+                merged = JSON.parse(File.read(merged_sq_path))
+                spec_quality_strict_failed = cfg["strict"] && Polyrun::SpecQuality::Report.gate_violations(merged, cfg).any?
+              end
+            rescue Polyrun::Error, JSON::ParserError => e
+              Polyrun::Log.warn e.message.to_s
+              merge_spec_quality_errored = true
+            end
+          end
+
           if ctx[:merge_failures]
             begin
               merged_failures_path = merge_failures_after_shards(ctx)
@@ -79,13 +96,13 @@ module Polyrun
               merge_failures: ctx[:merge_failures]
             )
             exit_code = 1
-            exit_code = 1 if wait_hook_err != 0
             return exit_code
           end
 
           exit_code = run_shards_merge_or_hint_coverage(ctx)
           exit_code = 1 if wait_hook_err != 0 && exit_code == 0
-          exit_code = 1 if merge_failures_errored && exit_code == 0
+          exit_code = 1 if merge_spec_quality_errored && exit_code == 0
+          exit_code = 1 if spec_quality_strict_failed && exit_code == 0
           exit_code
         ensure
           if suite_started
@@ -103,7 +120,7 @@ module Polyrun
           end
         end
       end
-      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def run_shards_warn_interleaved(parallel, pid_count)
         return unless parallel && pid_count > 1
@@ -145,7 +162,7 @@ module Polyrun
           Polyrun::Log.warn "polyrun run-shards: shard #{s} re-run (same spec list, no interleave): #{rerun}"
         end
         unless merge_failures
-          Polyrun::Log.warn "polyrun run-shards: one merged failure report — use run-shards --merge-failures with Polyrun::RSpec.install_failure_fragments!; POLYRUN_MERGED_FAILURES_PATH is set on after_suite when merge runs."
+          Polyrun::Log.warn "polyrun run-shards: for one combined failure report, add --merge-failures (requires failure fragments enabled in your test setup)"
         end
       end
     end

data/lib/polyrun/cli/spec_quality_commands.rb

@@ -0,0 +1,140 @@
+require "json"
+require "optparse"
+
+require_relative "../spec_quality"
+
+module Polyrun
+  class CLI
+    module SpecQualityCommands
+      private
+
+      def cmd_merge_spec_quality(argv)
+        inputs = []
+        output = "coverage/polyrun-spec-quality.json"
+        parser = OptionParser.new do |opts|
+          opts.banner = "usage: polyrun merge-spec-quality [-i FILE]... [-o OUT] [FILE...]"
+          opts.on("-i", "--input FILE", "Spec quality JSONL fragment (repeatable)") { |f| inputs << f }
+          opts.on("-o", "--output PATH", String) { |v| output = v }
+        end
+        parser.parse!(argv)
+        inputs.concat(argv) if inputs.empty?
+
+        if inputs.empty?
+          inputs = Dir.glob(Polyrun::SpecQuality::Fragment.glob_pattern).sort
+        end
+
+        if inputs.empty?
+          Polyrun::Log.warn "merge-spec-quality: need -i FILE or coverage/polyrun-spec-quality-fragment-*.jsonl"
+          return 2
+        end
+
+        out_abs = File.expand_path(output)
+        Polyrun::SpecQuality::Merge.merge_and_write(inputs.map { |p| File.expand_path(p) }, out_abs)
+        Polyrun::Log.puts out_abs
+        0
+      end
+
+      # rubocop:disable Metrics/AbcSize -- report argv + gate output
+      def cmd_report_spec_quality(argv)
+        input = nil
+        out_file = nil
+        top = 30
+        profile = nil
+        config_path = nil
+        strict = false
+        json_out = false
+        plan_paths = []
+
+        OptionParser.new do |opts|
+          opts.banner = "usage: polyrun report-spec-quality -i FILE [-o PATH] [--top N] [--profile LIST] [--strict] [--json]"
+          opts.on("-i", "--input PATH", "Merged polyrun-spec-quality.json") { |v| input = v }
+          opts.on("-o", "--output PATH", "Write report to file instead of stdout") { |v| out_file = v }
+          opts.on("--top N", Integer) { |v| top = v }
+          opts.on("--profile LIST", "cpu,mem,io,wall (comma-separated)") { |v| profile = v }
+          opts.on("-c", "--config PATH", "polyrun_spec_quality.yml path") { |v| config_path = v }
+          opts.on("--plan PATH", "Partition plan JSON (repeatable; polyrun plan output per shard)") { |v| plan_paths << v }
+          opts.on("--strict", "Exit 1 when gate thresholds fail") { strict = true }
+          opts.on("--json", "Write analysis JSON instead of text report") { json_out = true }
+        end.parse!(argv)
+        input ||= argv.first
+
+        unless input && File.file?(input)
+          Polyrun::Log.warn "report-spec-quality: need -i FILE"
+          return 2
+        end
+
+        merged = JSON.parse(File.read(File.expand_path(input)))
+        cfg = load_spec_quality_config(config_path)
+        strict = true if cfg["strict"] || strict
+        plan_shards = Polyrun::SpecQuality::PlanLoader.load_shards(plan_paths)
+
+        text = if json_out
+          JSON.pretty_generate(Polyrun::SpecQuality::Report.analyze(merged, cfg, plan_shards: plan_shards))
+        else
+          Polyrun::SpecQuality::Report.format_report(
+            merged, cfg: cfg, top: top, profile: profile, plan_shards: plan_shards
+          )
+        end
+
+        if out_file
+          File.write(File.expand_path(out_file), text)
+          Polyrun::Log.puts File.expand_path(out_file)
+        else
+          Polyrun::Log.print text
+        end
+
+        violations = Polyrun::SpecQuality::Report.gate_violations(merged, cfg)
+        if strict && violations.any?
+          violations.each { |v| Polyrun::Log.warn "polyrun spec-quality gate: #{v}" }
+          return 1
+        end
+
+        0
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def merge_spec_quality_after_shards(ctx)
+        files = merge_spec_quality_fragment_files
+        if files.empty?
+          Polyrun::Log.warn "polyrun run-shards: --merge-spec-quality: no spec-quality fragments found under coverage (enable spec-quality collection in your test setup)"
+          return nil
+        end
+
+        out = ctx[:merge_spec_quality_output] || "coverage/polyrun-spec-quality.json"
+        Polyrun::Log.warn "polyrun run-shards: merging #{files.size} spec-quality fragment(s) → #{out}"
+        Polyrun::SpecQuality::Merge.merge_and_write(files, File.expand_path(out))
+        report_spec_quality_after_merge(out, ctx)
+        File.expand_path(out)
+      end
+
+      def report_spec_quality_after_merge(merged_path, ctx)
+        return unless ctx[:report_spec_quality]
+
+        cfg = load_spec_quality_config(ctx[:config_path])
+        merged = JSON.parse(File.read(File.expand_path(merged_path)))
+        text = Polyrun::SpecQuality::Report.format_report(merged, cfg: cfg)
+        Polyrun::Log.print text
+
+        violations = Polyrun::SpecQuality::Report.gate_violations(merged, cfg)
+        return if violations.empty?
+
+        violations.each { |v| Polyrun::Log.warn "polyrun spec-quality gate: #{v}" }
+      end
+
+      def merge_spec_quality_fragment_files
+        Dir.glob(Polyrun::SpecQuality::Fragment.glob_pattern).sort
+      end
+
+      def load_spec_quality_config(config_path)
+        root = Dir.pwd
+        path = config_path
+        if path && !path.to_s.empty?
+          path = File.expand_path(path, root)
+        end
+        Polyrun::SpecQuality::Config.load(root: root, config_path: path)
+      rescue
+        Polyrun::SpecQuality::Config::DEFAULTS.dup
+      end
+    end
+  end
+end

data/lib/polyrun/cli.rb

@@ -1,6 +1,8 @@
+# rubocop:disable Polyrun/FileLength -- CLI dispatch + require wiring
 require "optparse"
 
 require_relative "cli/helpers"
+require_relative "cli/partition_diagnostics"
 require_relative "cli/plan_command"
 require_relative "cli/prepare_command"
 require_relative "cli/coverage_commands"
@@ -8,8 +10,10 @@ require_relative "cli/report_commands"
 require_relative "cli/env_commands"
 require_relative "cli/database_commands"
 require_relative "cli/run_shards_command"
+require_relative "cli/run_queue_command"
 require_relative "cli/queue_command"
 require_relative "cli/timing_command"
+require_relative "cli/spec_quality_commands"
 require_relative "cli/init_command"
 require_relative "cli/quick_command"
 require_relative "cli/ci_shard_run_parse"
@@ -28,9 +32,9 @@ module Polyrun
 
     # Keep in sync with +dispatch_cli_command_subcommands+ (+when+ branches). Used for implicit path routing.
     DISPATCH_SUBCOMMAND_NAMES = %w[
-      plan prepare merge-coverage merge-failures report-coverage report-junit report-timing
+      plan prepare merge-coverage merge-failures merge-spec-quality report-coverage report-junit report-timing report-spec-quality
       env config merge-timing db:setup-template db:setup-shard db:clone-shards
-      run-shards parallel-rspec start build-paths init queue quick hook
+      run-shards parallel-rspec start build-paths init queue run-queue quick hook
     ].freeze
 
     # First argv token that is a normal subcommand (not a path); if argv[0] is not here but looks like paths, run implicit parallel.
@@ -39,6 +43,7 @@ module Polyrun
     ).freeze
 
     include Helpers
+    include PartitionDiagnostics
     include PlanCommand
     include PrepareCommand
     include CoverageCommands
@@ -46,8 +51,10 @@ module Polyrun
     include EnvCommands
     include DatabaseCommands
     include RunShardsCommand
+    include RunQueueCommand
     include QueueCommand
     include TimingCommand
+    include SpecQualityCommands
     include InitCommand
     include QuickCommand
     include CiShardRunParse
@@ -159,6 +166,10 @@ module Polyrun
         cmd_config(argv, config_path)
       when "merge-timing"
         cmd_merge_timing(argv)
+      when "merge-spec-quality"
+        cmd_merge_spec_quality(argv)
+      when "report-spec-quality"
+        cmd_report_spec_quality(argv)
       when "db:setup-template"
         cmd_db_setup_template(argv, config_path)
       when "db:setup-shard"
@@ -179,6 +190,8 @@ module Polyrun
         cmd_init(argv, config_path)
       when "queue"
         cmd_queue(argv)
+      when "run-queue"
+        cmd_run_queue(argv, config_path)
       when "quick"
         cmd_quick(argv)
       when "hook"
@@ -196,3 +209,4 @@ module Polyrun
     end
   end
 end
+# rubocop:enable Polyrun/FileLength

data/lib/polyrun/coverage/example_diff.rb

@@ -0,0 +1,122 @@
+module Polyrun
+  module Coverage
+    # Per-example line hit deltas from stdlib +Coverage.peek_result+ snapshots.
+    module ExampleDiff
+      module_function
+
+      # @return [Hash{String=>Hash}] path => +{"lines"=>[...]}+
+      def peek_blob
+        return {} unless coverage_active?
+
+        normalize_peek(::Coverage.peek_result)
+      end
+
+      def coverage_active?
+        defined?(::Coverage) && ::Coverage.respond_to?(:running?) && ::Coverage.running?
+      end
+
+      def normalize_peek(raw)
+        out = {}
+        raw.each do |path, cov|
+          next unless cov.is_a?(Hash)
+
+          lines = cov[:lines] || cov["lines"]
+          next unless lines.is_a?(Array)
+
+          out[path.to_s] = {"lines" => lines.map { |x| x }}
+        end
+        out
+      end
+
+      # @return [Hash] +:unique_lines+, +:line_churn+, +:max_line_churn+, +:lines+ (compact triples)
+      # rubocop:disable Metrics/AbcSize -- per-file coverage delta walk
+      def diff(before_blob, after_blob)
+        before_blob ||= {}
+        after_blob ||= {}
+        files = before_blob.keys | after_blob.keys
+
+        line_entries = []
+        unique = 0
+        churn = 0
+        max_churn = 0
+
+        files.each do |path|
+          b_lines = line_array(before_blob[path])
+          a_lines = line_array(after_blob[path])
+          max_len = [b_lines.size, a_lines.size].max
+
+          (0...max_len).each do |i|
+            b = b_lines[i]
+            a = a_lines[i]
+            next if a.nil? && b.nil?
+
+            delta = (integer_hit(a) - integer_hit(b))
+            next unless delta.positive?
+
+            line_no = i + 1
+            line_entries << [path, line_no, delta]
+            unique += 1
+            churn += delta
+            max_churn = delta if delta > max_churn
+          end
+        end
+
+        {
+          unique_lines: unique,
+          line_churn: churn,
+          max_line_churn: max_churn,
+          lines: line_entries
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def filter_lines(lines, root:, track_under:, ignore_paths: [])
+        root = File.expand_path(root)
+        prefixes = Array(track_under).map { |d| File.join(root, d.to_s) }
+        ignore = Array(ignore_paths).map(&:to_s).reject(&:empty?)
+
+        lines.select do |path, _line, _delta|
+          p = File.expand_path(path.to_s, root)
+          next false if ignore.any? { |pat| path_matches_ignore?(p, pat) }
+
+          prefixes.any? { |pre| p == pre || p.start_with?(pre + "/") }
+        end
+      end
+
+      def apply_track_under(delta, root:, track_under:, ignore_paths: [])
+        filtered = filter_lines(delta[:lines] || [], root: root, track_under: track_under, ignore_paths: ignore_paths)
+        unique = filtered.size
+        churn = filtered.sum { |(_p, _l, d)| d }
+        max_churn = filtered.map { |(_p, _l, d)| d }.max || 0
+        {
+          unique_lines: unique,
+          line_churn: churn,
+          max_line_churn: max_churn,
+          lines: filtered
+        }
+      end
+
+      def path_matches_ignore?(path, pattern)
+        return path.include?(pattern) if pattern.is_a?(String) && !pattern.start_with?("/")
+
+        path.match?(Regexp.new(pattern))
+      rescue RegexpError
+        path.include?(pattern.to_s)
+      end
+
+      def line_array(entry)
+        return [] unless entry.is_a?(Hash)
+
+        arr = entry["lines"] || entry[:lines]
+        arr.is_a?(Array) ? arr : []
+      end
+
+      def integer_hit(value)
+        return 0 if value.nil?
+
+        value.is_a?(Integer) ? value : value.to_i
+      end
+      private_class_method :line_array, :integer_hit
+    end
+  end
+end