mutineer 0.6.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b549b3640aa316aa715732f4e91f3be669b7ab8e7ad877b8207d0e31ac12b4aa
-  data.tar.gz: a626241007cf47b4fb0ef3c68dc1fba7f0c8679d0c41db516dca888893fc5f51
+  metadata.gz: bfadc70b171d8778c8afa95021c2989ad33ab2880200a22886fec274e358efcc
+  data.tar.gz: f6f6c91f6e5fffc0a2d05d93b0981df165d6d5b2df1e1434949c7dea1c0f70a6
 SHA512:
-  metadata.gz: ba4d45a6ba52ead7da7f580452eb610bfc23b368501c496e80ffa56e2e364a62fcf896a1e9d37c50b1216727eb8a6a02386ba0917c85397ac61a3f2a9f41d694
-  data.tar.gz: 6be383459b367be9b72135b1672d57c63bd4e4a6c032c3301532f50a1bcb96dff2cc6ecf764979d6009fab9e4c1e4d327fbb1e81cf3652232cb38a2eb6a82558
+  metadata.gz: 01de0a56c54a7b85fd98d92831681a258a4420b3e5b3d34ce932811259a776764c888aae13a8975632c66851798f9b4a53f343864518fd8fe608e7dddff20e07
+  data.tar.gz: 63c802e363a3f87a8ecd43a5bf726d2ce23af2aadf890b87b7ad6616076e9f2461876c0af5faa70c83caf93027fd9e8754bf6866c5ab25e7d2a51bd51f9f3d4c

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and this project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] - 2026-06-30
+
+### Fixed
+- **Singleton methods are now mutated** (#20) — `class << self` and
+  `module_function` methods were discovered but applied to the instance scope, so
+  the mutant never ran on the singleton the caller dispatches to; every such
+  mutant falsely survived and the file read a false 0%. `module_function` methods
+  are now discovered as singletons, and the redefine strategy re-opens
+  `class << self` so the mutation lands on the called method. (Scores for
+  singleton-heavy files will rise to their true values.)
+- **Fork-capture failures are diagnosable** (#19, part 1) — capture/worker pipes
+  are `binmode` (a binary Marshal payload could otherwise be lost to an encoding
+  error and swallowed), and a child that dies without writing now reports how it
+  died (exit status / signal) instead of a silent "produced no result". `--verbose`
+  always surfaces a real reason now. (The residual write-heavy capture failure
+  on some real Rails suites remains under investigation — now diagnosable.)
+
+## [0.7.1] - 2026-06-30
+
+### Added
+- **GitHub Action** (`action.yml`, composite) wrapping the CLI for CI — gate a PR
+  on new survivors / score drop with `sources`, `since`, `baseline`, `threshold`,
+  etc. Inputs are passed via `env` (no `${{ }}` interpolation into the run script)
+  for command-injection safety.
+- Docs site (GitHub Pages) with Open Graph / Twitter Card share image; YARD doc
+  comments across the library.
+
+## [0.7.0] - 2026-06-30
+
+Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
+
+### Added
+- **Equivalent-mutant suppression** (#10) — inline `# mutineer:disable-line [ops]`
+  and a `.mutineer.yml` `ignore:` list keyed on a stable, offset-free mutant id;
+  suppressed mutants are excluded from the score (100% reachable). The stable id
+  (and readable token) is emitted per survivor in JSON.
+- **Source→test auto-pairing + multi-source runs** (#11) — pass a directory or
+  several sources with `--test` omitted; tests are inferred by convention
+  (`app/`,`lib/` → `test/…_test.rb` / `spec/…_spec.rb`) and run under one boot,
+  with per-source results (human + JSON `per_source`).
+- **`--baseline <file.json>` CI gating** (#13) — diff against a prior run by stable
+  id; exit 1 on new survivors or a score drop (with `--baseline-epsilon`), naming
+  what regressed. Combines with `--threshold` via max exit code.
+- **`--verbose`/`--debug`** (#8) — surface the real error when a fork capture fails.
+- **`:uncapturable` status** (#9) — distinct from `no_coverage`; reported separately
+  ("tests failed to run" vs "genuinely uncovered"). Both excluded from the score.
+
+### Fixed
+- **Fork capture no longer drops fixture transactions** (#8) — `reconnect` skips
+  `clear_all_connections!` when a fixture transaction is open, and stops swallowing
+  the child error; write-heavy Rails tests are mutation-testable again.
+
+### Changed
+- JSON `schema_version` → `1.1` (additive: survivor `id`/`token`, `ignored`,
+  `uncapturable`, `per_source`).
+
 ## [0.6.2] - 2026-06-29
 
 ### Fixed
@@ -100,6 +156,9 @@ All notable changes to this project are documented here. The format is based on
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.8.0]: https://github.com/davidteren/mutineer/releases/tag/v0.8.0
+[0.7.1]: https://github.com/davidteren/mutineer/releases/tag/v0.7.1
+[0.7.0]: https://github.com/davidteren/mutineer/releases/tag/v0.7.0
 [0.6.2]: https://github.com/davidteren/mutineer/releases/tag/v0.6.2
 [0.6.1]: https://github.com/davidteren/mutineer/releases/tag/v0.6.1
 [0.6.0]: https://github.com/davidteren/mutineer/releases/tag/v0.6.0

data/README.md

@@ -1,6 +1,8 @@
 # Mutineer
 
-[![Socket Badge](https://badge.socket.dev/rubygems/package/mutineer/0.6.2?platform=ruby)](https://socket.dev/rubygems/package/mutineer/overview/0.6.2?platform=ruby)
+[![Gem Version](https://img.shields.io/gem/v/mutineer?logo=rubygems&color=e23b3b)](https://rubygems.org/gems/mutineer)
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Mutineer%20Ruby-2da44e?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/mutineer-ruby)
+[![Socket Badge](https://badge.socket.dev/rubygems/package/mutineer/0.7.1?platform=ruby)](https://socket.dev/rubygems/package/mutineer/overview/0.7.1?platform=ruby)
 
 A clean-room mutation-testing tool for Ruby. Mutineer mutates your source one
 change at a time, runs your test suite (Minitest or RSpec) against each mutant, and reports the
@@ -49,7 +51,10 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
 | `--framework NAME` | `minitest` (default) or `rspec`; auto-detected as rspec when most `--test` files end in `_spec.rb` |
 | `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`) — ideal for PR CI |
-| `--jobs N` | Parallel worker count (default: processor count) |
+| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (see [CI](#ci-gating)) |
+| `--baseline-epsilon FLOAT` | Score-drop tolerance for `--baseline` (default: 0) |
+| `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
+| `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
 | `--format human\|json` | Report format (default: human) |
 | `--output FILE` | Write the report to FILE instead of stdout |
@@ -96,6 +101,62 @@ Add Mutineer to your Gemfile's test group:
 gem "mutineer", group: :test, require: false
 ```
 
+## Suppressing equivalent mutants
+
+Some mutants are equivalent (behaviour-identical) and survive forever — keeping a
+file off 100%. Suppress them so the score and `--threshold` gate stay meaningful:
+
+- **Inline:** `some_line # mutineer:disable-line` (or scope it: `# mutineer:disable-line comparison`).
+- **Config:** a `.mutineer.yml` `ignore:` list of stable mutant ids. Each survivor's
+  `id` is printed in the JSON report, so copy it straight into `ignore:`.
+
+Suppressed mutants are excluded from the score (so 100% becomes reachable).
+
+## CI gating
+
+Store a JSON run as a baseline, then fail the build only when a PR makes things
+worse:
+
+```sh
+mutineer run app/ --baseline .mutineer/baseline.json   # exit 1 on NEW survivors or a score drop
+```
+
+`--baseline` reports which survivors are new (by stable id) and any score drop. It
+combines with `--threshold` (the worse of the two sets the exit code). Pass a
+directory (or several sources) to audit a whole layer in one boot — tests are
+auto-paired by convention and the report breaks down per source.
+
+### GitHub Action
+
+This repo ships a composite action (`action.yml`) that wraps the CLI for CI:
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }        # --since needs full history
+- uses: ruby/setup-ruby@v1
+  with: { ruby-version: "3.4", bundler-cache: true }
+- uses: davidteren/mutineer@v0
+  with:
+    sources: app/
+    since: origin/${{ github.base_ref }}
+    baseline: .mutineer/baseline.json
+    threshold: "90"
+```
+
+## For AI agents & pipelines
+
+Mutineer is built for programmatic use — versioned JSON, stable mutant ids,
+structured exit codes, and diff-scoped runs. See:
+
+- **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how
+  to avoid infinite loops on equivalent mutants):
+  [rendered](https://davidteren.github.io/mutineer/agentic-coding.html) ·
+  [source](docs/agentic-coding.md)
+- **JSON schema reference** — the `--format json` schema and its versioning
+  contract:
+  [rendered](https://davidteren.github.io/mutineer/json-schema.html) ·
+  [source](docs/json-schema.md)
+
 ## Configuration
 
 Mutineer reads an optional `.mutineer.yml` from the project root (nearest one,

data/lib/mutineer/baseline.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "config" # for Mutineer::ConfigError
+
+module Mutineer
+  # #13: CI baseline/delta gating. A baseline is literally a prior
+  # `mutineer run --format json` document (KTD-1) — no bespoke format to
+  # version.
+  # We diff the current run against it by the #10 stable survivor id (KTD-2):
+  # a NEW survivor (id present now, absent in the baseline) OR a score drop is
+  # a regression the CLI turns into exit 1. Pure data — stdlib `json` only, no
+  # fork, no Rails — so it's testable in isolation from a canned JSON + a hand-
+  # built AggregateResult.
+  class Baseline
+    # The verdict of diffing a current run against the baseline.
+    #   new_survivors   — current Result objects whose stable id is absent from
+    #                     the baseline (the regressions to name).
+    #   fixed_survivors — baseline survivor hashes absent from the current run
+    #                     (informational, never gates).
+    #   score_drop      — current score < baseline score - epsilon. nil on
+    #                     either side skips the check (see #diff).
+    #   regressed       — any new survivors OR a score drop.
+    Delta = Data.define(:new_survivors, :fixed_survivors,
+                        :score_before, :score_after, :score_drop, :regressed)
+
+    # Load a prior --format json run. Raises ConfigError (NOT exit — R8: a data
+    # class must never kill the host) on a missing/unreadable file, unparseable
+    # JSON, or a doc that isn't a baseline shape, so the CLI maps it to exit 2
+    # (usage) like every other bad-path flag.
+    #
+    # @param path [String] baseline JSON file path.
+    # @return [Mutineer::Baseline] baseline object.
+    # @raise [Mutineer::ConfigError] when the file is missing or invalid.
+    def self.load(path)
+      doc = JSON.parse(File.read(path))
+      unless doc.is_a?(Hash) && doc["schema_version"] && doc["survivors"].is_a?(Array)
+        raise ConfigError, "not a Mutineer JSON report: #{path}"
+      end
+
+      new(doc)
+    rescue JSON::ParserError => e
+      raise ConfigError, "invalid baseline JSON in #{path}: #{e.message}"
+    end
+
+    attr_reader :score
+
+    # Builds a baseline from a JSON document.
+    #
+    # The baseline retains the survivor document and score from the JSON report.
+    #
+    # @param doc [Hash] parsed JSON document.
+    def initialize(doc)
+      @survivors = doc["survivors"] || []
+      @score = doc.dig("summary", "score")
+    end
+
+    # Diff a current AggregateResult against this baseline by stable survivor id.
+    # `epsilon` tolerates float jitter on the score (default 0.0 = any drop
+    # gates).
+    #
+    # @param aggregate [Mutineer::AggregateResult] current results.
+    # @param epsilon [Float] score-drop tolerance.
+    # @return [Mutineer::Baseline::Delta] delta summary.
+    def diff(aggregate, epsilon: 0.0)
+      current = aggregate.surviving_mutants
+      current_ids = current.map(&:id)
+      baseline_ids = @survivors.map { |h| h["id"] }
+
+      new_survivors = current.reject { |r| baseline_ids.include?(r.id) }
+      fixed = @survivors.reject { |h| current_ids.include?(h["id"]) }
+
+      current_score = aggregate.mutation_score
+      # nil-score discipline (mirrors Reporter#exit_code): a score absent on
+      # either side can't be compared — skip the drop check, keep the new-
+      # survivor check.
+      score_drop = !@score.nil? && !current_score.nil? &&
+                   current_score < @score - epsilon
+
+      Delta.new(new_survivors: new_survivors, fixed_survivors: fixed,
+                score_before: @score, score_after: current_score,
+                score_drop: score_drop,
+                regressed: !new_survivors.empty? || score_drop)
+    end
+  end
+end

data/lib/mutineer/changed_lines.rb

@@ -4,23 +4,30 @@ require "set"
 require "open3"
 
 module Mutineer
-  # Maps each source file to the set of NEW-side line numbers that changed since a
-  # given git ref, by parsing `git diff --unified=0`. Used to restrict mutations
-  # to only the diff (issue #2): on a PR you care whether the changed code is
-  # tested, so mutating just those lines is fast and actionable.
+  # Maps each source file to the set of NEW-side line numbers changed since a
+  # git ref.
   #
-  # git is an external tool, not a gem dependency — shelling out is fine. The pure
+  # By parsing `git diff --unified=0`, this restricts mutations to only the
+  # diff (issue #2): on a PR you care whether the changed code is tested, so
+  # mutating just those lines is fast and actionable.
+  #
+  # git is an external tool, not a gem dependency — shelling out is fine. The
   # `parse` carries the logic; `git_diff` is injectable so it stays testable
   # without invoking git.
   module ChangedLines
+    # Matches unified-diff hunks and captures the new-file start/count.
     HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
 
     module_function
 
-    # Parse `git diff --unified=0` output into the set of NEW-side line numbers
-    # added/modified. With --unified=0 each hunk's `+c,d` block is exactly the
-    # changed lines: c..c+d-1. `d` absent means 1 line; `d == 0` is a pure
-    # deletion and contributes nothing.
+    # Parses unified diff text into the set of NEW-side line numbers.
+    #
+    # With `--unified=0` each hunk's `+c,d` block is exactly the changed lines:
+    # `c..c+d-1`. `d` absent means 1 line; `d == 0` is a pure deletion and
+    # contributes nothing.
+    #
+    # @param diff_text [String] raw `git diff --unified=0` output.
+    # @return [Set<Integer>] changed line numbers on the new side.
     def parse(diff_text)
       lines = Set.new
       diff_text.each_line do |row|
@@ -34,8 +41,13 @@ module Mutineer
       lines
     end
 
-    # { absolute_file_path => Set<Integer> } of changed new-side lines per file.
-    # `runner` is injected so tests can supply canned diff text per file.
+    # Builds a per-file map of changed new-side lines.
+    #
+    # @param ref [String] git ref to diff against.
+    # @param files [Array<String>] source files to inspect.
+    # @param project_root [String] repository root for `git -C`.
+    # @param runner [#call] injectable diff producer.
+    # @return [Hash<String, Set<Integer>>] absolute file path to changed lines.
     def for(ref:, files:, project_root:, runner: method(:git_diff))
       files.each_with_object({}) do |file, acc|
         abs = File.expand_path(file, project_root)
@@ -43,7 +55,12 @@ module Mutineer
       end
     end
 
-    # stdout of `git -C <root> diff --unified=0 <ref> -- <file>`, "" on failure.
+    # Returns the stdout of `git -C <root> diff --unified=0 <ref> -- <file>`.
+    #
+    # @param ref [String] git ref to diff against.
+    # @param abs_file [String] absolute path of the file being diffed.
+    # @param project_root [String] repository root for `git -C`.
+    # @return [String] diff text, or `""` on failure.
     def git_diff(ref, abs_file, project_root)
       out, _err, status = Open3.capture3(
         "git", "-C", project_root, "diff", "--unified=0", ref, "--", abs_file

data/lib/mutineer/cli.rb

@@ -7,9 +7,11 @@ require_relative "version"
 require_relative "config"
 require_relative "parser"
 require_relative "project"
+require_relative "pairing"
 require_relative "changed_lines"
 require_relative "runner"
 require_relative "reporter"
+require_relative "baseline"
 require_relative "mutator_registry"
 
 module Mutineer
@@ -22,6 +24,7 @@ module Mutineer
   #   2  usage / flag error (unknown subcommand, invalid flag, unknown operator,
   #      out-of-range threshold)
   class CLI
+    # Command-line usage banner.
     BANNER = <<~USAGE
       Usage: mutineer [options] <command> [args]
 
@@ -33,6 +36,9 @@ module Mutineer
         --test FILE          Test file covering the sources (repeatable)
         --operators LIST     Comma-separated operator names (default: Tier 1 set)
         --threshold FLOAT    Fail (exit 1) when score < FLOAT (default: 0 = off)
+        --baseline FILE      Fail (exit 1) on NEW survivors / score drop vs a prior
+                             --format json run (CI delta gate)
+        --baseline-epsilon FLOAT  Score-drop tolerance for --baseline (default: 0)
         --only NAME          Restrict to one fully-qualified subject
         --since REF          Only mutate lines changed since git REF (e.g. origin/main)
         --jobs N             Parallel worker count (default: processor count)
@@ -44,6 +50,7 @@ module Mutineer
         --format human|json  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
+        --verbose            Surface the real error when a fork capture fails (alias: --debug)
 
       Options:
         --list-operators  List available operators (default vs optional) and exit
@@ -57,6 +64,10 @@ module Mutineer
     # Deprecated internal strategy names, mapped to their canonical equivalents.
     STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
 
+    # Parses arguments, executes the command, and exits.
+    #
+    # @param argv [Array<String>] raw command-line arguments.
+    # @return [void]
     def self.start(argv)
       opts = {}            # symbol => value, the CLI-provided Config fields
       explicit = Set.new   # precedence keys the user typed (KTD3)
@@ -84,8 +95,14 @@ module Mutineer
         o.on("--framework NAME") { |v| opts[:framework] = v; explicit << :framework }
         o.on("--boot FILE") { |v| opts[:boot] = v; explicit << :boot }
         o.on("--rails") { opts[:rails] = true }
+        o.on("--verbose") { opts[:verbose] = true }
+        o.on("--debug") { opts[:verbose] = true } # alias of --verbose
         o.on("--format FORMAT") { |v| opts[:format] = v }
         o.on("--output FILE") { |v| opts[:output] = v }
+        # #13: --baseline is also a .mutineer.yml key, so mark it explicit when
+        # typed (CLI wins over the file). --baseline-epsilon is CLI-only.
+        o.on("--baseline FILE") { |v| opts[:baseline] = v; explicit << :baseline }
+        o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = v.to_f }
       end
 
       begin
@@ -118,14 +135,19 @@ module Mutineer
 
       case argv.first
       when "run"
-        config.sources = argv[1..]
-        run(config)
+        # #11: a directory source expands to its **/*.rb files; literal files pass
+        # through. Test inference (when --test is omitted) happens in validate!.
+        config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
+        run(config, explicit)
       else
         warn "mutineer: unknown command '#{argv.first}'"
         exit 2
       end
     end
 
+    # Lists available operators.
+    #
+    # @return [void]
     def self.list_operators
       MutatorRegistry::ALL.each_key do |name|
         state = MutatorRegistry.default?(name) ? "default" : "disabled"
@@ -134,12 +156,17 @@ module Mutineer
       end
     end
 
-    def self.run(config)
+    # Runs the requested command after validation.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
+    def self.run(config, explicit = Set.new)
       if config.sources.empty?
         warn "mutineer: run requires at least one source file"
         exit 2
       end
-      validate!(config)
+      validate!(config, explicit)
 
       config.dry_run ? dry_run(config) : execute(config)
     rescue ArgumentError => e
@@ -163,7 +190,13 @@ module Mutineer
 
     # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
     # taxonomy above — CI can tell "mistyped flag" from "tests too weak."
-    def self.validate!(config)
+    # Validates the run configuration.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
+    def self.validate!(config, explicit = Set.new)
       unless (0.0..100.0).cover?(config.threshold)
         warn "mutineer: --threshold must be between 0 and 100"
         exit 2
@@ -194,6 +227,17 @@ module Mutineer
         exit 2
       end
 
+      validate_since!(config) if config.since
+      preflight_output!(config.output) if config.output
+      preflight_baseline!(config.baseline) if config.baseline
+
+      # #11: when --test is omitted, infer each source's test by convention so the
+      # boot-once/fork-per-test core (which pairs empirically by coverage) gets a
+      # populated config.tests. Runs after every flag/usage check above so a
+      # mistyped flag still reports the flag; skipped under --dry-run (no tests
+      # needed). validate_paths! then sees the inferred (real) tests.
+      autopair!(config, explicit) unless config.dry_run
+
       # Boot mode does no coverage selection — every mutant runs the given tests —
       # so at least one --test file is mandatory (there is nothing to select from).
       if config.boot && config.tests.empty?
@@ -201,13 +245,16 @@ module Mutineer
         exit 2
       end
 
-      validate_since!(config) if config.since
-      preflight_output!(config.output) if config.output
       validate_paths!(config)
     end
 
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
+    # Validates the --since ref.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.validate_since!(config)
       _out, _err, status = Open3.capture3(
         "git", "-C", config.project_root, "rev-parse", "--verify", "--quiet",
@@ -229,6 +276,11 @@ module Mutineer
     # R5: validate path existence up front so a typo is a clean usage error (exit
     # 2), not an Errno::ENOENT backtrace from deep in the run. Flag checks run
     # first so a bad flag still reports the flag, not the missing file.
+    # Validates source and test paths.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.validate_paths!(config)
       missing = (config.sources + config.tests)
                 .reject { |p| File.exist?(File.expand_path(p, config.project_root)) }
@@ -238,6 +290,61 @@ module Mutineer
       exit 2
     end
 
+    # #11: auto-pair sources to tests by path convention when no --test was given
+    # (explicit --test wins — R5). Each source with an inferred test on disk joins
+    # the run; a source with none is dropped with a one-line stderr warning (R3)
+    # and the run continues with the rest. If every source is dropped: in boot mode
+    # the dedicated --boot/--rails-requires-test check reports it; otherwise exit 2
+    # with a usage message. The framework is re-detected from the inferred set
+    # unless it was set explicitly (a spec-only project loads/reports as rspec).
+    # Auto-pairs sources and tests when --test is absent.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param explicit [Set<Symbol>] explicit CLI fields.
+    # @return [void]
+    def self.autopair!(config, explicit)
+      return unless config.tests.empty?
+
+      paired = config.sources.filter_map do |s|
+        t = Pairing.infer_test(s, project_root: config.project_root, prefer: config.framework)
+        [s, t] if t
+      end
+      (config.sources - paired.map(&:first)).each do |s|
+        warn "[mutineer] no test found by convention for #{s}; skipping"
+      end
+      config.sources = paired.map(&:first)
+      config.tests   = paired.map(&:last).uniq
+      config.framework = Config.detect_framework(config.tests) unless explicit.include?(:framework)
+
+      return unless config.sources.empty?
+      return if config.boot # let the --boot/--rails-requires-test check report it
+
+      warn "mutineer: no test files found by convention; pass --test or add tests"
+      exit 2
+    end
+
+    # #13: a missing/unreadable/unparseable baseline is a usage error (exit 2),
+    # mirroring --output/--since preflight, so CI sees "bad invocation," not a
+    # backtrace mid-run. Validating up front = attempting the load (it raises
+    # ConfigError/SystemCallError; the actual diff reloads in execute).
+    # Preflights a baseline file.
+    #
+    # @api private
+    # @param path [String] baseline file path.
+    # @return [void]
+    def self.preflight_baseline!(path)
+      Baseline.load(path)
+    rescue Mutineer::ConfigError, SystemCallError => e
+      warn "mutineer: #{e.message}"
+      exit 2
+    end
+
+    # Preflights an output path.
+    #
+    # @api private
+    # @param path [String] output file path.
+    # @return [void]
     def self.preflight_output!(path)
       dir = File.dirname(File.expand_path(path))
       return if File.directory?(dir) && File.writable?(dir)
@@ -247,6 +354,10 @@ module Mutineer
       exit 2
     end
 
+    # Executes the run command.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.execute(config)
       if config.tests.empty?
         warn "mutineer: run requires at least one --test file (or use --dry-run)"
@@ -255,8 +366,14 @@ module Mutineer
 
       aggregate, source_map = Runner.execute(config)
       reporter = Reporter.new(aggregate, source_map)
+
+      # #13: diff the current run against the baseline (preflighted above) by the
+      # stable survivor id. The delta is rendered inline (human section / additive
+      # json block) and gates exit independently of --threshold.
+      delta = (Baseline.load(config.baseline).diff(aggregate, epsilon: config.baseline_epsilon) if config.baseline)
+
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
-                      format: config.format, output: config.output)
+                      format: config.format, output: config.output, baseline: delta)
 
       # #14: nudge toward the opt-in tier-2 operators (human report only — never
       # pollute JSON output).
@@ -264,11 +381,18 @@ module Mutineer
         puts hint
       end
 
-      exit reporter.exit_code(threshold: config.threshold)
+      # #13/KTD-4: --baseline and --threshold are independent gates OR'd together.
+      # `max` of two 0/1 codes is the OR; usage (2) is handled earlier and wins.
+      baseline_exit = delta&.regressed ? 1 : 0
+      exit [reporter.exit_code(threshold: config.threshold), baseline_exit].max
     end
 
     # The tier-2 operators not in the active set, as a one-line hint (or nil when
     # they're all already enabled). `active` nil means the default (Tier-1) set.
+    # Builds a Tier-2 operator hint.
+    #
+    # @param active [Array<String>, nil] active operator names.
+    # @return [String, nil] hint text or nil.
     def self.tier2_hint(active)
       active ||= MutatorRegistry::DEFAULT_NAMES
       unused = MutatorRegistry::TIER2_NAMES - active
@@ -278,6 +402,10 @@ module Mutineer
         "enable with --operators <list>."
     end
 
+    # Runs dry-run mode.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
     def self.dry_run(config)
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
       sources = {}