saboteur 0.11.0 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dd9ced23a90f2f769ccf934e50949a8d9b04324fe86aeec72c8d0de896129ed
-  data.tar.gz: 3c9f5628615aefcaecac88474d2badb925e57d32d17066fc0afeef642eced780
+  metadata.gz: 45635354d2b8067e2de9a11025677af615e3eb54da14dfcd26f0afbdcdd00073
+  data.tar.gz: 40a395d6909fb4bcec99596c6b34e4b40edf1b72c76b349ab25cb3ae44b48726
 SHA512:
-  metadata.gz: 44eb555775d94aa27ff1bf1f6b8a425faf973157bc8da3c9cbf66a337551699c63cbeba11dae6e5d9860f80002125dc60a08569d381a8f48034537b99c622a7b
-  data.tar.gz: bd5801edf6723c1442fed00d5c54cc82a278b23875f677427e9d3b3cc47d0c52a26bf0e7d0155a06e4de6c1eba71d25f3e724e1cfe22f180977efa09107e3256
+  metadata.gz: 3f3dd155c87c3c6a45d1fd66a66cc5ec21d8c56dd5113dab2568cd07cc957ee2ba34bfc1b773cf4610aeee822e354bf36cc747418bcee24902365563f5f2b5c2
+  data.tar.gz: 23f785f27b3396a38195f44d6a418d819d6c7359fe34a8ec9f8422855206b53a5ebd634eb70d8c8d40cf622787a9795d99395950932a5870a2418d8651520aa9

data/CHANGELOG.md

@@ -6,6 +6,92 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-10-22
+
+### Added
+
+- A full run warns when an ignore entry's subject never appears, so a
+  renamed or removed method can no longer kill the entry silently
+  (#1250, #1206).
+- Survivor gaps are labeled by kind instead of the blanket
+  `missing_test` label (#1246, #1153, #1064), and the README names
+  `tool_limit` and the gap kinds in the survivor triage labels (#1247).
+- The `explain` command prints a human-readable rationale for any
+  registry operator (#1251).
+- The HTML report lists survivors, timeouts and errors before killed
+  rows inside each file, keeping source order within each group
+  (#1253, #1233).
+- Survivor blocks consult the whole-suite coverage map, ending false
+  survivors from diff-scoped runs (#1252).
+
+### Changed
+
+- Output polish across the terminal, JSON and HTML reports: the flaky
+  check names why it exits 3, `doctor` prints its coverage line and a
+  run without a config says so (#1239); stubbed-test wording, the
+  timeout tally and the replay scope line are clearer (#1240);
+  selection messaging states nothing-to-test once and names the
+  `--since` scope on `--subject` misses (#1241); survivor blocks count
+  blocks, not mutants (#1242); the run opener and coverage-map counts
+  are pluralized (#1244); the clean screen labels its scope, hints at
+  the live reports and summarizes an empty diff (#1245).
+- Docs: the ignore list is named as the one way to accept a survivor,
+  the pre-1.0 policy for test selection and operator defaults is
+  stated, and the CLI-docs rule points at `docs/` rather than the
+  short README (#1248).
+
+## [0.11.1] - 2026-10-22
+
+### Added
+
+- Diff runs echo the real `--since` ref in hints and name the diff
+  scope in the reports (#1235, #1218, #1219), and `survivors` reads the
+  last report by default and refuses ambiguous digest prefixes (#1235,
+  #1189, #1188, #1192).
+- `baseline propose` tolerates untested subjects: proposability is the
+  gate at propose time, while strict evidence completeness stays where
+  it is required (#1168, #1141). The baseline command names what it is
+  doing, the file it writes and the follow-up command at every step,
+  and blockers resolve to subject, operator and reason plus a
+  remediation line (#1217, #1195, #1196).
+- The GitHub Action gains an opt-in `max-duration` input passed to
+  `--max-duration`, summary lines for exits 2/3/4/5/70, an annotation
+  on exit 4, and failure messages that each name the command or
+  setting that fixes them (#1220).
+- Incremental runs report reuse feedback (#1221), and the HTML report
+  gains a copy button on survivor blocks, print rules and aria fixes
+  (#1231).
+
+### Changed
+
+- Warning notices, the baseline tail and the CLI rescue paths render
+  through the colour palette (monochrome output is byte-identical), and
+  first runs are quieter: the Ruby 3.4 fiddle stdlib notice is dropped
+  during the guarded require, Rails mode no longer warns about the
+  harmless AR Pool Reaper thread, and the no-spec stop ends with a
+  clearer custom-map pointer (#1236, #1226, #1229, #1230).
+- Survivors rank by per-statement density first (the statement with
+  the most surviving mutants leads), then by thin coverage; ranking is
+  review priority only, with no score or exit-code effect (#1163).
+- `survivors --show` prints the complete detail - diff, replay command
+  with the run's seed, and a paste-correct ignore template (#1194,
+  #1217) - and unknown-command and doctor include errors are clearer
+  (#1194).
+- First-run DX: the footer ignore template pastes into `.saboteur.rb`
+  unchanged, install prints the next step, and lifecycle warnings are
+  quieter (#1217, #1221). The survivor-confirmation skip notice names
+  the real reason (#1231, #1184, #1177).
+- The HTML report is printable and collapsible, with clearer baseline
+  errors (#1179).
+
+### Fixed
+
+- Survivor confirmation no longer crashes the run (exit 70): a
+  confirmation failure degrades to a warning (#1164, #1140).
+- README hero output shows the right subject count (#1162), and the
+  exit-code docs match the gates (#1231, #1222).
+
+
 ## [0.11.0] - 2026-10-21
 
 ### Added

data/README.md

@@ -17,7 +17,7 @@
 
 ```text
 $ bundle exec saboteur pr
-saboteur 0.11.0: 1 subjects, 10 mutants, wall 0.70 s, seed 1 (repeat with --seed 1)
+saboteur 0.11.0: 2 subjects, 10 mutants, wall 0.70 s, seed 1 (repeat with --seed 1)
 Score: 80.0% (8/10 killed, tested subjects)
 saboteur: 8 killed, 2 survived in 1s - score 80.0%
 ```
@@ -80,7 +80,7 @@ tree refuses with exit 2 and points at the generator. Engine gem with
   assertion, 1 by a crash`), and an error-dominated run prints
   `Score: n/a` instead of a number you would misread.
 - 🔍 **Survivors you can act on.** Survivors group per statement with a
-  triage label (`likely_equivalent`, `arid`, `missing_test`) and their
+  triage label (`likely_equivalent`, `arid`, `tool_limit`, or a gap kind) and their
   covering tests - split into the tests that ran against the mutant and
   the ones that never did. `saboteur survivors` browses them read-only:
   one digest shows the full diff and the exact replay command.

data/lib/saboteur/baseline/command.rb

@@ -20,6 +20,7 @@ module Saboteur
           opts.on("--config PATH", "Config file (default config/saboteur.rb)") { |value| set(:config, value) }
           opts.on("--subject EXPR", "Whole subject filter; repeatable") { |value| add_subject(value) }
           opts.on("--seed N", Integer, "Repeatable run seed") { |value| set(:seed, value) }
+          opts.on("--format FORMAT", "propose: terminal (default) or json") { |value| @format = value }
         end
       end
 
@@ -34,7 +35,7 @@ module Saboteur
           workflow = Baseline::Workflow.new(config: config, err: @err)
           baseline_action(workflow, action)
         end
-        @out.puts(JSON.generate(payload))
+        action == "propose" && @format != "json" ? print_proposal(payload) : @out.puts(JSON.generate(payload))
         payload.fetch("exit_code", CLI::EXIT_OK)
       rescue ConfigError, SystemCallError => e
         @err.puts("saboteur: #{e.message}")
@@ -44,13 +45,17 @@ module Saboteur
         CLI::EXIT_TOOL
       end
 
+      def baseline_path_required(action)
+        "--baseline PATH is required (for example: saboteur baseline #{action} --baseline baseline.json)"
+      end
+
       def parse_baseline(action)
         raise CLI::UsageError, "baseline expects check, propose or accept" unless %w[check propose
                                                                                      accept].include?(action)
 
         baseline_parser.parse!(@argv)
         raise CLI::UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
-        raise CLI::UsageError, "--baseline PATH is required" unless @baseline_path
+        raise CLI::UsageError, baseline_path_required(action) unless @baseline_path
         raise CLI::UsageError, "--proposal PATH is required" if action != "check" && !@proposal_path
         if action == "check" && (@proposal_path || @previous)
           raise CLI::UsageError,
@@ -58,6 +63,15 @@ module Saboteur
         end
         validate_epsilon(action)
         raise CLI::UsageError, "--previous needs a SHA-256" if @previous && !@previous.match?(/\A[0-9a-f]{64}\z/)
+
+        validate_format(action)
+      end
+
+      def validate_format(action)
+        unless @format.nil? || %w[terminal json].include?(@format)
+          raise CLI::UsageError, "--format must be terminal or json"
+        end
+        raise CLI::UsageError, "--format applies to propose only" if @format && action != "propose"
       end
 
       def validate_epsilon(action)
@@ -67,6 +81,36 @@ module Saboteur
         raise CLI::UsageError, "--epsilon must be between 0 and 100" unless (0.0..100.0).cover?(@epsilon)
       end
 
+      def print_proposal(payload)
+        @out.puts("baseline proposal written: #{payload.fetch('proposal')}")
+        survivors = payload.fetch("survivors")
+        @out.puts("  matched mutants: #{payload.fetch('candidates')} " \
+                  "(#{plural(survivors, 'survivor')} to reason about)")
+        gaps = payload.fetch("gaps", [])
+        unless gaps.empty?
+          names = gaps.map { |gap| gap.sub(/\A(subject_skipped|omitted):/, "") }
+          @out.puts("  proposed with #{plural(names.size, 'untested subject')}: #{names.join(', ')} - " \
+                    "the baseline cannot speak for them")
+        end
+        @out.puts("  next step: give each accepted survivor a reason in the proposal, then run: " \
+                  "saboteur baseline accept#{scope_flags} " \
+                  "--baseline #{payload.fetch('destination')} --proposal #{payload.fetch('proposal')}")
+      end
+
+      def plural(count, noun)
+        count == 1 ? "#{count} #{noun}" : "#{count} #{noun}s"
+      end
+
+      # accept re-verifies the recorded run settings, so the printed command
+      # repeats the scope flags this propose ran with.
+      def scope_flags
+        flags = +""
+        Array(options[:subjects]).each { |expr| flags << " --subject #{expr}" }
+        flags << " --seed #{options[:seed]}" if options[:seed]
+        flags << " --config #{options[:config]}" if options[:config]
+        flags
+      end
+
       def baseline_action(workflow, action)
         case action
         when "check" then workflow.check(path: @baseline_path, epsilon: @epsilon)

data/lib/saboteur/baseline/comparison.rb

@@ -62,7 +62,12 @@ module Saboteur
       end
 
       def outcome(current)
-        return "incomplete" unless current.fetch("complete") && issues.empty? && !current.fetch("candidates").empty?
+        # The proposability tier is the comparability gate: a run over soft
+        # gaps still speaks for the subjects it executed. Legacy documents
+        # without the split fall back to the strict flag and full issue list.
+        proposable = current.fetch("proposable") { current.fetch("complete") }
+        blockers = current.fetch("blockers") { current.fetch("issues") }
+        return "incomplete" unless proposable && blockers.empty? && !current.fetch("candidates").empty?
         return "incomplete" unless categories.fetch("errors").empty?
         return "review_required" if %w[new changed unmatched].any? { |name| !categories.fetch(name).empty? }
         return "review_required" if score&.fetch("exceeded")

data/lib/saboteur/baseline/completeness.rb

@@ -6,8 +6,15 @@ module Saboteur
     # Exact planned/result reconciliation, independent of survivor acceptance.
     class Completeness
       EXECUTED = %w[killed survived timeout].freeze
+      # Soft gaps limit what the baseline can speak for; they never refuse a
+      # proposal. Everything else is a hard blocker.
+      SOFT_PREFIXES = %w[subject_skipped: omitted:].freeze
       attr_reader :issues
 
+      def self.soft_gap?(issue)
+        SOFT_PREFIXES.any? { |prefix| issue.start_with?(prefix) }
+      end
+
       def initialize(planned:, results:, subjects:, stable_suite:, stable_inputs:, skipped_subjects:, omitted:,
                      generation_issues:)
         @issues = []
@@ -25,6 +32,20 @@ module Saboteur
         issues.empty?
       end
 
+      def blockers
+        issues.reject { |issue| self.class.soft_gap?(issue) }
+      end
+
+      def gaps
+        issues.select { |issue| self.class.soft_gap?(issue) }
+      end
+
+      # A proposal may be written over soft gaps (they are listed in it);
+      # only hard blockers refuse.
+      def proposable?
+        blockers.empty?
+      end
+
       private
 
       def validate_inventory(planned, subjects)

data/lib/saboteur/baseline/evidence.rb

@@ -10,8 +10,8 @@ module Saboteur
     # Validates the producer document before it can enter the acceptance path.
     # A claimed complete flag alone is never evidence of complete execution.
     class Evidence
-      FIELDS = %w[compatibility snapshot subjects candidates planned complete issues generation_events
-                  omissions discovery_failures inline_suppressions].freeze
+      FIELDS = %w[compatibility snapshot subjects candidates planned complete proposable issues blockers gaps
+                  generation_events omissions discovery_failures inline_suppressions].freeze
       COMPATIBILITY = %w[generator runtime config scope].freeze
       PLAN_FIELDS = %w[id identity context].freeze
 
@@ -27,6 +27,13 @@ module Saboteur
         validate_compatibility
         validate_generation
         validate_plan
+        blockers = @document.fetch("blockers")
+        gaps = @document.fetch("gaps")
+        unless @document.fetch("proposable") == blockers.empty? &&
+               (blockers + gaps).sort == @document.fetch("issues")
+          raise ConfigError, "baseline evidence: completeness tiers disagree"
+        end
+
         # Manifest owns exact candidate, identity, subject and acceptance shapes.
         Manifest.new(manifest(reasons: "validation"))
       rescue ArgumentError, KeyError, TypeError, NoMethodError => e
@@ -34,7 +41,8 @@ module Saboteur
       end
 
       def manifest(reasons: "")
-        metadata = document.fetch("compatibility").merge(document.slice("snapshot", "subjects", "complete", "issues"))
+        metadata = document.fetch("compatibility").merge(document.slice("snapshot", "subjects", "complete",
+                                                                        "proposable", "issues"))
         accepted = document.fetch("candidates").select { |entry| entry.fetch("status") == "survived" }.map do |entry|
           entry.slice("id", "context").merge("reason" => reasons)
         end

data/lib/saboteur/baseline/loader.rb

@@ -24,17 +24,30 @@ module Saboteur
         bytes = File.read(path)
         digest = Digest::SHA256.hexdigest(bytes)
         manifest = Manifest.new(JSON.parse(Text.utf8_strict(bytes)))
+        Evidence.new(restored_evidence(manifest))
+        [manifest, digest]
+      rescue Errno::ENOENT
+        raise ConfigError, "baseline file #{path} does not exist; " \
+                           "create it with saboteur baseline propose --baseline #{path}"
+      rescue SystemCallError, JSON::ParserError, ArgumentError => e
+        raise ConfigError, "baseline file: #{e.message}"
+      end
+
+      # The evidence snapshot a manifest stands for: its metadata, candidates
+      # and plan, with no generation events (nothing was generated).
+      def restored_evidence(manifest)
         metadata = manifest.to_h.fetch("metadata")
         candidates = manifest.candidates.values
-        restored = metadata.slice("snapshot", "subjects", "complete", "issues").merge(
+        issues = metadata.fetch("issues")
+        metadata.slice("snapshot", "subjects", "complete", "issues").merge(
+          "proposable" => metadata.fetch("proposable", metadata["complete"]),
+          "blockers" => issues.reject { |issue| Completeness.soft_gap?(issue) },
+          "gaps" => issues.select { |issue| Completeness.soft_gap?(issue) }
+        ).merge(
           "compatibility" => manifest.compatibility, "candidates" => candidates,
           "planned" => candidates.map { |entry| entry.slice(*Evidence::PLAN_FIELDS) },
           "generation_events" => [], "omissions" => [], "discovery_failures" => [], "inline_suppressions" => []
         )
-        Evidence.new(restored)
-        [manifest, digest]
-      rescue SystemCallError, JSON::ParserError, ArgumentError => e
-        raise ConfigError, "baseline file: #{e.message}"
       end
     end
   end

data/lib/saboteur/baseline/manifest.rb

@@ -4,12 +4,17 @@
 require "digest"
 require "json"
 
+require_relative "completeness"
+
 module Saboteur
   module Baseline
     # Validated, immutable human acceptance and the complete run it describes.
     class Manifest
       FORMAT = 1
-      METADATA = %w[generator runtime config scope snapshot subjects complete issues].freeze
+      METADATA = %w[generator runtime config scope snapshot subjects complete proposable issues].freeze
+      # Baselines written before the two-tier completeness split carry no
+      # proposable key; their strict complete flag is the proposability gate.
+      LEGACY_METADATA = (METADATA - %w[proposable]).freeze
       STATUSES = %w[killed survived timeout].freeze
 
       attr_reader :candidates, :accepted
@@ -48,8 +53,12 @@ module Saboteur
 
       def validate_metadata
         metadata = @document["metadata"]
-        fields!(metadata, METADATA, "metadata")
-        fail!("incomplete evidence") unless metadata["complete"] == true && metadata["issues"] == []
+        fail!("metadata fields") unless metadata.is_a?(Hash)
+        keys = metadata.keys.sort
+        fail!("metadata fields") unless [METADATA.sort, LEGACY_METADATA.sort].include?(keys)
+        proposable = metadata.fetch("proposable", metadata["complete"])
+        hard = metadata.fetch("issues").reject { |issue| Completeness.soft_gap?(issue) }
+        fail!("incomplete evidence") unless proposable == true && hard.empty?
         %w[generator runtime config scope snapshot].each do |name|
           fail!("metadata #{name}") unless metadata[name].is_a?(Hash) && !metadata[name].empty?
         end
@@ -121,7 +130,7 @@ module Saboteur
         current = candidates[entry["id"]]
         fail!("acceptance candidate") unless current && current["status"] == "survived"
         fail!("acceptance context") unless current["context"] == entry["context"]
-        text!(entry["reason"], "reason")
+        text!(entry["reason"], "reason on acceptance #{entry['id'][0, 16]} (write a non-blank reason)")
       end
 
       def fields!(value, fields, name)

data/lib/saboteur/baseline/run_evidence.rb

@@ -46,7 +46,9 @@ module Saboteur
         completeness = assess(observed, stable_suite, skipped_subjects, omissions, errors)
         document = { "compatibility" => compatibility, "snapshot" => @snapshot.to_h, "subjects" => @subjects,
                      "candidates" => observed, "planned" => @planned,
-                     "complete" => completeness.complete?, "issues" => completeness.issues,
+                     "complete" => completeness.complete?, "proposable" => completeness.proposable?,
+                     "issues" => completeness.issues, "blockers" => completeness.blockers,
+                     "gaps" => completeness.gaps,
                      "generation_events" => generation, "omissions" => omissions.map(&:to_h),
                      "discovery_failures" => discovery, "inline_suppressions" => suppressions }
         Engine::RunFingerprint.canonical_value(document)

data/lib/saboteur/baseline/workflow.rb

@@ -3,6 +3,7 @@
 
 require_relative "acceptance"
 require_relative "comparison"
+require_relative "identity"
 require_relative "loader"
 require_relative "../engine"
 require_relative "../text"
@@ -41,21 +42,48 @@ module Saboteur
         payload
       end
 
+      # Blockers carry only a digest and a status. Name the subject, operator
+      # and the engine's recorded reason, and say how to unblock the proposal.
+      def refuse_proposal(evidence, report)
+        blockers = evidence.fetch("blockers")
+        by_id = report.results.to_h do |result|
+          [Identity.new(subject: result.subject, mutation: result.mutation, root: @root).entry.fetch("id"), result]
+        end
+        blockers.each { |issue| @err.puts("saboteur: baseline proposal blocker: #{describe_blocker(issue, by_id)}") }
+        if blockers.any? { |issue| issue.start_with?("unexecuted:") }
+          @err.puts("saboteur: cover the skipped code with specs or narrow include, then propose again")
+        end
+        raise Error, "baseline proposal needs a proposable run"
+      end
+
+      def describe_blocker(issue, by_id)
+        match = /\Aunexecuted:([0-9a-f]{64}):(\w+)\z/.match(issue)
+        result = match && by_id[match[1]]
+        return issue unless result
+
+        detail = "#{result.subject.id} #{result.mutation.operator}"
+        detail += " - #{result.reason}" if result.reason
+        "#{issue} (#{detail})"
+      end
+
       def propose(proposal:, destination:, previous: nil)
         guard_artifacts(proposal, destination)
+        preflight_outputs(proposal, destination, previous)
         report = Engine.new(@config, err: @err, capture_evidence: true).call
-        unless report.run_evidence["complete"] == true
-          raise Error,
-                "baseline proposal requires complete execution evidence"
-        end
+        evidence = report.run_evidence
+        refuse_proposal(evidence, report) unless evidence["proposable"] == true
 
-        captured = Evidence.new(report.run_evidence)
+        captured = Evidence.new(evidence)
         store(captured.document.fetch("snapshot")).propose(document: captured.manifest,
                                                            evidence: captured.document, proposal: proposal,
                                                            destination: destination, previous: previous)
-        { "state" => "proposal", "proposal" => File.expand_path(proposal),
-          "destination" => File.expand_path(destination),
-          "survivors" => captured.manifest.fetch("accepted").size }
+        payload = { "state" => "proposal", "proposal" => File.expand_path(proposal),
+                    "destination" => File.expand_path(destination),
+                    "survivors" => captured.manifest.fetch("accepted").size,
+                    "candidates" => captured.manifest.fetch("candidates").size }
+        gaps = evidence.fetch("gaps")
+        payload["gaps"] = gaps unless gaps.empty?
+        payload
       end
 
       def accept(proposal:, destination:, previous: nil)
@@ -80,12 +108,20 @@ module Saboteur
           extras = saved.inventory.select { |entry| entry.kind == "extra" }.map do |entry|
             { path: input_path(entry.path), required: entry.required }
           end
-          Engine::RunFingerprint.new(config: @config, extra_files: extras).verify(saved).unchanged
+          raise_unless_unchanged(Engine::RunFingerprint.new(config: @config, extra_files: extras).verify(saved))
         end
         Acceptance.new(directory: File.join(Identity.canonical_path(@config.path("cache_dir")), "baseline-evidence"),
                        protected_paths: protected, verify: verifier, require_evidence: true)
       end
 
+      def raise_unless_unchanged(result)
+        return true if result.unchanged
+
+        detail = result.changes.map { |change| "#{change.path} #{change.reason}" }.join(", ")
+        detail = "verification incomplete" if detail.empty?
+        raise ConfigError, "baseline inputs changed or unverified: #{detail}"
+      end
+
       def input_paths(snapshot)
         snapshot.inventory.map { |entry| input_path(entry.path) }
       end
@@ -94,6 +130,18 @@ module Saboteur
         path.start_with?("external:") ? path.delete_prefix("external:") : File.join(@root, path)
       end
 
+      # Cheap pre-checks before the full run; Acceptance re-verifies exclusively after it.
+      def preflight_outputs(proposal, destination, previous)
+        raise ConfigError, "baseline output exists: #{Identity.canonical_path(proposal)}" if File.exist?(proposal)
+
+        # Mirrors Acceptance#verify_previous so a doomed proposal fails before the run.
+        if previous.nil?
+          raise ConfigError, "baseline destination exists" if File.exist?(destination)
+        elsif !File.file?(destination) || Digest::SHA256.file(destination).hexdigest != previous
+          raise ConfigError, "baseline previous destination changed"
+        end
+      end
+
       def guard_artifacts(*paths)
         paths.each do |path|
           expanded = Identity.canonical_path(path)

data/lib/saboteur/baseline_health.rb

@@ -35,7 +35,10 @@ module Saboteur
 
     def call
       expected = @integration.all_tests.map(&:id)
-      raise Error, "baseline has no tests; check rspec_args and spec paths" if expected.empty?
+      if expected.empty?
+        raise Error, "baseline has no tests; check rspec_args and the suite filters, " \
+                     "then run saboteur doctor --suite again"
+      end
 
       first = check_run(1, expected)
       second = check_run(2, expected)

data/lib/saboteur/cli/dirty_tree_notice.rb

@@ -1,6 +1,9 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../reporter/palette"
+require_relative "../reporter/notice"
+
 module Saboteur
   class CLI
     # The uncommitted-work warning printed before a run (#334). Extracted
@@ -21,7 +24,10 @@ module Saboteur
                   else
                     config
                   end
-        DirtyTreeWarning.for(warning, config_path: options[:config])&.then { |text| @err.puts(text) }
+        DirtyTreeWarning.for(warning, config_path: options[:config])&.then do |text|
+          palette = Reporter::Palette.for(@err, mode: @color || :auto, overrides: warning["palette"])
+          @err.puts(Reporter::Notice.paint(palette, text))
+        end
       end
     end
   end

data/lib/saboteur/cli/doctor_command.rb

@@ -22,13 +22,22 @@ module Saboteur
 
       def doctor_command = help_requested? ? show_help("doctor") : doctor
 
+      # The environment is healthy only if a run would have something to
+      # mutate: the same empty source set `run` refuses (exit 2).
+      def doctor_verdict
+        return EXIT_OK unless config.included_files.empty?
+
+        @err.puts("saboteur: #{empty_source_set_message}")
+        EXIT_USAGE
+      end
+
       def doctor
         doctor_parser.parse!(@argv)
         raise UsageError, "unexpected arguments: #{@argv.join(' ')}" if @argv.any?
 
         options[:tests]&.each { |test| require_existing_test(test) }
         Doctor.new(config, out: @out, suite: options[:suite] || options.key?(:tests)).call
-        EXIT_OK
+        doctor_verdict
       rescue ConfigError => e
         @err.puts("saboteur: #{Text.display_safe_lines(e.message)}")
         EXIT_USAGE

data/lib/saboteur/cli/exit_status.rb

@@ -1,11 +1,15 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "flaky_exit"
+
 module Saboteur
   class CLI
     # How a finished run maps to an exit code and a recorded exit cause. Mixed
     # into the CLI, which supplies `config` and the `@err` stream.
     module ExitStatus
+      include FlakyExit
+
       private
 
       def exit_code(report)
@@ -15,7 +19,7 @@ module Saboteur
 
         return EXIT_TOOL if untested_partial?(report)
 
-        return EXIT_TOOL if unverifiable_scope?(report)
+        return EXIT_TOOL if unverifiable_scope?(report) || flaky_disagreement?(report)
 
         return EXIT_TOOL if mostly_errored?(report)
 
@@ -60,9 +64,10 @@ module Saboteur
       # must not exit 0 with score n/a and green-light an untested change.
       def unverifiable_scope?(report)
         if unverifiable_review?(report)
-          report.skipped_subjects.each do |subject, reason|
-            @err.puts(subject.skipped_gate_sentence(reason, report.root))
-          end
+          # A text run already printed each skip up front; json and agent
+          # runs read this sentence as the exit explanation (#1227).
+          skips = %w[json agent].include?(@format) ? report.skipped_subjects : report.unannounced_skips
+          skips.each { |subject, reason| @err.puts(subject.skipped_gate_sentence(reason, report.root)) }
           return true
         end
         return false unless unverifiable_unreachable?(report)
@@ -116,7 +121,7 @@ module Saboteur
         else
           if report.majority_errored?
             "errorMajority"
-          elsif unverifiable_review?(report) || unverifiable_unreachable?(report) ||
+          elsif unverifiable_review?(report) || unverifiable_unreachable?(report) || report.results.any?(&:flaky?) ||
                 (report.early_stop && report.score_breakdown.tested.zero?)
             "incomplete"
           else

data/lib/saboteur/cli/explain_command.rb

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "../help"
+require_relative "../reporter/palette"
+require_relative "../mutation_source/operator_explain"
+
+module Saboteur
+  class CLI
+    # Shared rendering for `saboteur explain <operator>` (#1097): the
+    # curated definition, a before/after example and survive/kill guidance
+    # for one operator, so a survivor's operator can be understood and
+    # targeted without leaving the terminal.
+    module ExplainCommand
+      private
+
+      def explain_command
+        name = @argv.shift
+        raise UsageError, "usage: saboteur explain <operator>" if name.nil?
+
+        entry = MutationSource::OperatorExplain.for(name)
+        if entry.nil?
+          @err.puts("saboteur: unknown operator: #{name}")
+          suggestion = MutationSource::OperatorRegistry.suggestion(name)
+          @err.puts("saboteur: #{suggestion}") unless suggestion.empty?
+          @err.puts("saboteur: operators: #{MutationSource::OperatorRegistry::DESCRIPTIONS.keys.join(', ')}")
+          return EXIT_USAGE
+        end
+
+        @out.puts(render_explain(entry, palette: Reporter::Palette.for(@out, mode: :auto)))
+        EXIT_OK
+      rescue UsageError => e
+        @err.puts("saboteur: #{e.message}")
+        EXIT_USAGE
+      end
+
+      def render_explain(entry, palette: Reporter::Palette.new(enabled: false))
+        original, replacement = entry.example.split(" -> ")
+        [
+          "#{palette.paint(:head, 'Operator:')} #{entry.name}",
+          "#{palette.paint(:head, 'Definition:')} #{entry.definition}",
+          palette.paint(:head, "Example:"),
+          "  #{palette.paint(:fail, "- #{original}")}",
+          "  #{palette.paint(:pass, "+ #{replacement}")}",
+          "#{palette.paint(:warn, 'Survives when:')} #{entry.survives}",
+          "#{palette.paint(:info, 'Kill it with:')} #{entry.kill}"
+        ].join("\n")
+      end
+    end
+  end
+end