mutineer 0.11.2 → 0.11.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 457a9cdee5d5291635fb56dd01caf17293bc500443ca2e43e298a81c0c1f73bf
-  data.tar.gz: ffe7d126be066573d5c9c42969f994e7a9be71ecb8d301643a6deab3de5d7af3
+  metadata.gz: 85591c1b61bcdc3c8a1d39b5b657f667bf7de9039d61e05ab3e5691692f555f0
+  data.tar.gz: 76acdc054e82d9ea10dee4a63bcbb5f0f86db37dd585323f734991f413f21e61
 SHA512:
-  metadata.gz: 63e9df1191cdc62802dcd9dd674eb2954c416b8016017aa3bb9e689f777859f547450416e4a62f23b34f9c9171b063ff12a6639e3cda1ceb9180c48bbea673df
-  data.tar.gz: 0ace3fd9df09a67b535d55ee25f0e30d60f1dd3f03ca1027600cc216d11d9dd468f320e9b11190d595e204d6310bfe05f61ec80e6eeb33f36c123e0981ed1810
+  metadata.gz: b5855d2e0a9d4e226fe0ad2034cc4d08f4b5ac5e2d34df9e92f97b9d344ea5a50c4df01bbdcb0973dc66e8ccde717baab8842935fa07a4cad1238f77b9bebf42
+  data.tar.gz: 3a5c57795de651128a3d3597b2f1776fd32ff76aeaea4edf14037a1ec32e13e72e54c38a56ef8c209f3ee1d6afc0ffbb5fd47153967803c841e64d989d80a047

data/CHANGELOG.md

@@ -6,6 +6,71 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-07-29
+
+### Fixed
+- **`--threshold` now gates on the run being complete, not just its score** — a
+  score is `killed / (killed + survived)`, so mutants that error, time out or come
+  back uncapturable are excluded from the denominator: a broken harness *raised*
+  the score instead of lowering it. Ninety errored mutants and ten that ran (nine
+  killed) reported 90% and exited 0, so CI could not tell a complete run from a
+  mostly-broken one. Past 10% of attempted mutants producing no verdict, a positive
+  `--threshold` now exits 1 whatever the score, and the report says which states
+  broke, on every `--format`. A single bad mutant never trips it, however small the
+  run, so a `--since` PR with a handful of mutants keeps its flake tolerance (#78).
+
+### Added
+- **`no_verdict[]` in the JSON report** (`schema_version` 1.2) — every attempted
+  mutant that produced no verdict, with its `status` and, where there is one, the
+  `details` explaining the cause. `Result#details` was built and rendered in no
+  format at all, so a daemon crash reached the user as nothing but a larger errored
+  count. `summary` gains `attempted` and `no_verdict`, the two figures the
+  completeness gate is computed from (#78).
+
+## [0.11.3] - 2026-07-29
+
+### Fixed
+- **Nothing to mutate now costs nothing** — `--since` matching no changed line (a
+  docs-only PR, which README documents `--since origin/<base>` for) still did the
+  expensive part before discovering there was no work: `--daemon` booted the app
+  once for the coverage map and again for every `--jobs` worker, and
+  `--test-command` ran the whole suite for a smoke check that calibrates a timeout
+  no mutant would use. Both backends now return as soon as the job list is empty.
+  The in-process path is unchanged: it boots before collecting jobs, so it cannot
+  know the list is empty yet. One consequence worth stating: a zero-job `--daemon`
+  run no longer boots the app, so an app that fails to boot now exits 0 (nothing
+  to do) instead of exit 1 (#76).
+- **A dead daemon ends the run instead of scoring the rest against it** — a
+  daemon that dies while running one mutant was already handled: `DaemonClient`
+  respawns and answers `error` for that mutant. But a daemon that could not come
+  back was not. `restart!` closes the pipes before respawning, so if the respawn
+  failed at the OS level (`EMFILE` or `ENOMEM` under `--jobs N`, `ENOENT` when
+  `bundle` does not resolve) the client was left permanently dead while raising
+  errors that read as ordinary per-mutant failures. Every remaining mutant scored
+  `error` against nothing, and Mutineer printed a mutation score built on the
+  fraction of mutants that ran before the daemon died. `DaemonClient` now raises
+  `DaemonBootError` whenever it is gone for good — a refused spawn, a failed boot
+  handshake on respawn, closed pipes, or `MAX_RESTARTS` crashes — and the CLI
+  reports it as a message and exit 1 rather than a backtrace. Under `--jobs N`
+  the remaining queue is dropped so sibling workers stop too. Errored mutants
+  still cannot fail the `--threshold` gate once any mutant is scored (#78).
+
+### Changed
+- **Daemon orchestration split out of `Runner`** — the persistent-daemon backend
+  (job fan-out, worker DBs, coverage-map build, boot config, verdict mapping) now
+  lives in `Mutineer::DaemonBackend`. `Runner` keeps job collection, coverage
+  selection and the single in-process mutant run, and drops from 662 to 439 lines.
+  The external backend's orchestration stays on `Runner` for now, so the two
+  backends are not yet symmetrical. No CLI or behaviour change (#58).
+  Internal-only removals: `Runner.execute_daemon`, `Runner.daemon_coverage_map`
+  and `Runner::DAEMON_TIMEOUT` no longer exist. They were never documented —
+  the supported programmatic contract is the JSON report, the stable mutant ids
+  and the exit codes — so only code calling `Runner` internals directly is
+  affected.
+- **Comment diet on orchestration files** — present-tense YARD contracts; drop
+  ticket/phase/KTD history tags from runner, CLI, daemon pair, coverage map,
+  reporter, result, and related modules. Safety and score invariants kept (#57).
+
 ## [0.11.2] - 2026-07-24
 
 ### Fixed
@@ -253,6 +318,8 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[0.11.4]: https://github.com/davidteren/mutineer/releases/tag/v0.11.4
+[0.11.3]: https://github.com/davidteren/mutineer/releases/tag/v0.11.3
 [0.11.2]: https://github.com/davidteren/mutineer/releases/tag/v0.11.2
 [0.11.1]: https://github.com/davidteren/mutineer/releases/tag/v0.11.1
 [0.11.0]: https://github.com/davidteren/mutineer/releases/tag/v0.11.0

data/README.md

@@ -47,7 +47,7 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 |------|---------|
 | `--test FILE` | Test file covering the sources (repeatable) |
 | `--operators LIST` | Comma-separated operator names (default: the Tier-1 set) |
-| `--threshold FLOAT` | Exit 1 when the score is below FLOAT (default: 0 = off) |
+| `--threshold FLOAT` | Exit 1 when the score is below FLOAT, or when nothing could be scored and something broke, or more than one mutant produced no verdict and they exceed 10% of those attempted (default: 0 = off) |
 | `--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 |
@@ -70,7 +70,7 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 | Code | Meaning |
 |------|---------|
 | `0` | Score ≥ threshold (or no threshold set) |
-| `1` | Survivors below threshold, or a runtime error |
+| `1` | Score below threshold, nothing could be scored and something broke, or more than one mutant produced no verdict and they exceed 10% of those attempted, a `--baseline` regression, or a runtime error |
 | `2` | Usage / invalid-flag error |
 
 ### Operators

data/lib/mutineer/baseline.rb

@@ -4,29 +4,27 @@ 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.
+  # CI baseline/delta gating. A baseline is a prior
+  # `mutineer run --format json` document (no bespoke format to version).
+  # Diff the current run against it by the stable survivor id: 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 is 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
+    #   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
+    #   fixed_survivors - baseline survivor hashes absent from the current run
     #                     (informational, never gates).
-    #   score_drop      — current score < baseline score - epsilon. nil on
+    #   score_drop      - current score < baseline score - epsilon. nil on
     #                     either side skips the check (see #diff).
-    #   regressed       — any new survivors OR a score drop.
+    #   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
+    # Load a prior --format json run. Raises ConfigError (NOT exit: a data class
+    # must never kill the host) on a missing/unreadable file, unparseable JSON,
+    # or a doc that is not 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.
@@ -72,7 +70,7 @@ module Mutineer
 
       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-
+      # either side cannot be compared. Skip the drop check, keep the new-
       # survivor check.
       score_drop = !@score.nil? && !current_score.nil? &&
                    current_score < @score - epsilon

data/lib/mutineer/cli.rb

@@ -18,7 +18,7 @@ module Mutineer
   # Command-line entry point. `start` is the single public method called by
   # bin/mutineer; it parses argv, acts, and exits with a pinned code.
   #
-  # Exit codes (taxonomy consistent across M1–M5):
+  # Exit codes:
   #   0  success / requested output (--version, --help, score >= threshold)
   #   1  survivors below threshold, or a runtime error
   #   2  usage / flag error (unknown subcommand, invalid flag, unknown operator,
@@ -78,7 +78,7 @@ module Mutineer
     # @return [void]
     def self.start(argv)
       opts = {}            # symbol => value, the CLI-provided Config fields
-      explicit = Set.new   # precedence keys the user typed (KTD3)
+      explicit = Set.new   # precedence keys the user typed
       show_operators = false
 
       parser = OptionParser.new do |o|
@@ -116,15 +116,15 @@ module Mutineer
         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.
+        # --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 }
-        # #27: run the target suite as a subprocess in the app's OWN runtime so
+        # Run the target suite as a subprocess in the app's OWN runtime so
         # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
         o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
-        # #26/#27 Phase 2: boot the app ONCE in a persistent daemon and fork per
-        # mutant, with per-worker DB isolation so --jobs N is safe under Rails.
+        # Boot the app ONCE in a persistent daemon and fork per mutant, with
+        # per-worker DB isolation so --jobs N is safe under Rails.
         o.on("--daemon") { opts[:daemon] = true; explicit << :daemon }
       end
 
@@ -150,7 +150,7 @@ module Mutineer
         file_hash = file_path ? Config.from_file(file_path) : {}
         config = Config.resolve(opts, file_hash, explicit)
       rescue Mutineer::ConfigError => e
-        # R8: the lib layer raises instead of killing the host; the CLI maps a
+        # The lib layer raises instead of killing the host; the CLI maps a
         # config (usage) error to exit 2.
         warn "mutineer: #{e.message}"
         exit 2
@@ -158,7 +158,7 @@ module Mutineer
 
       case argv.first
       when "run"
-        # #11: a directory source expands to its **/*.rb files; literal files pass
+        # 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)
@@ -197,7 +197,7 @@ module Mutineer
       warn "mutineer: #{e.message}"
       exit 2
     rescue SystemCallError => e
-      # R5: a missing/unreadable path reaches here as Errno::ENOENT etc. — a plain
+      # A missing/unreadable path reaches here as Errno::ENOENT etc. A plain
       # message and usage exit, never a raw backtrace.
       warn "mutineer: #{e.message}"
       exit 2
@@ -210,15 +210,19 @@ module Mutineer
       warn "mutineer: error reading: #{e.message}"
       exit 1
     rescue Mutineer::SmokeCheckError => e
-      # #27: the unmutated suite isn't green under --test-command — a broken
+      # The unmutated suite is not green under --test-command: a broken
       # environment, not weak tests. Runtime error (exit 1), not usage (exit 2).
       warn "mutineer: #{e.message}"
       exit 1
+    rescue Mutineer::DaemonBootError => e
+      # The daemon is gone for good, so the run ended rather than scoring the rest
+      # against it. A deliberate stop deserves a message, not a raw backtrace.
+      warn "mutineer: #{e.message}"
+      exit 1
     end
 
-    # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
-    # taxonomy above — CI can tell "mistyped flag" from "tests too weak."
-    # Validates the run configuration.
+    # Flag validation: every flag/usage failure exits 2, consistent with the
+    # taxonomy above. CI can tell "mistyped flag" from "tests too weak."
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
@@ -279,13 +283,12 @@ module Mutineer
       validate_paths!(config)
     end
 
-    # #27: --test-command runs the target suite in the app's own runtime. Validate
-    # its shape up front (usage errors → exit 2) and force serial execution: each
+    # --test-command runs the target suite in the app's own runtime. Validate its
+    # shape up front (usage errors → exit 2) and force serial execution: each
     # subprocess boots the app and opens its own fixture transaction against the
-    # same DB, so --jobs > 1 would corrupt results (the #12 fixture-contention
-    # hazard). Unlike --rails, this path has NO per-worker DB isolation to opt into,
-    # so an explicit --jobs N is forced to 1 rather than honored (KTD-5).
-    # Validates the --test-command configuration.
+    # same DB, so --jobs > 1 would corrupt results (fixture-contention hazard).
+    # Unlike --rails, this path has NO per-worker DB isolation to opt into, so an
+    # explicit --jobs N is forced to 1 rather than honored.
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
@@ -347,7 +350,6 @@ module Mutineer
 
     # --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.
@@ -370,10 +372,9 @@ module Mutineer
       exit 2
     end
 
-    # 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.
+    # 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.
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
@@ -387,14 +388,13 @@ 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
+    # Auto-pair sources to tests by path convention when no --test was given
+    # (explicit --test wins). Each source with an inferred test on disk joins the
+    # run; a source with none is dropped with a one-line stderr warning 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.
@@ -421,11 +421,10 @@ module Mutineer
       exit 2
     end
 
-    # #13: a missing/unreadable/unparseable baseline is a usage error (exit 2),
+    # 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.
@@ -464,7 +463,7 @@ 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
+      # 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)
@@ -476,28 +475,27 @@ module Mutineer
       # is not comparable to an in-process run: no coverage narrowing (uncovered
       # mutants count as survivors), and an infra failure is scored as a kill
       # (upper bound). Daemon coverage fallback warnings are emitted from the runner
-      # only when the map is unavailable — not on every --daemon run.
+      # only when the map is unavailable, not on every --daemon run.
       if config.test_command
         warn "[mutineer] --test-command score is an upper bound, not comparable to an " \
              "in-process run: no coverage narrowing (uncovered mutants count as survivors) " \
              "and an infra failure is scored as a kill."
       end
 
-      # Nudge toward the opt-in tier-2 operators (human report only — never
+      # Nudge toward the opt-in tier-2 operators (human report only: never
       # pollute JSON output).
       if !%w[json html].include?(config.format) && (hint = tier2_hint(config.operators))
         puts hint
       end
 
-      # #13/KTD-4: --baseline and --threshold are independent gates OR'd together.
+      # --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.
+    # they are all already enabled). `active` nil means the default (Tier-1) set.
     #
     # @param active [Array<String>, nil] active operator names.
     # @return [String, nil] hint text or nil.

data/lib/mutineer/config.rb

@@ -4,20 +4,20 @@ require "etc"
 require "yaml"
 
 module Mutineer
-  # Raised by the config layer instead of calling exit/abort — a data class must
-  # never kill the host process (R8). The CLI rescues this and maps it to exit 2.
+  # Raised by the config layer instead of calling exit/abort. A data class must
+  # never kill the host process. The CLI rescues this and maps it to exit 2.
   class ConfigError < StandardError; end
 
   # Plain run configuration, populated by the CLI (or directly by the
   # integration test). `operators` nil means "all default operators";
   # `threshold` 0.0 means the CI gate is off (spec §10).
   #
-  # M5 adds: jobs (parallel workers), format (human|json), output (report file),
-  # strategy (reload|redefine), require_paths (extra files to load). Config loading and
-  # the CLI > file > default precedence merge live here (KTD3/KTD4).
+  # Also holds: jobs (parallel workers), format (human|json), output (report
+  # file), strategy (reload|redefine), require_paths (extra files to load).
+  # Config loading and the CLI > file > default precedence merge live here.
   #
-  # Boot mode adds: boot (a file to require ONCE in the parent so the app env —
-  # e.g. Rails — is booted before forking; sources are then NOT manually required)
+  # Boot mode adds: boot (a file to require ONCE in the parent so the app env,
+  # e.g. Rails, is booted before forking; sources are then NOT manually required)
   # and rails (sugar: defaults boot to config/environment and strategy to redefine,
   # and reconnects ActiveRecord per fork).
   Config = Struct.new(
@@ -25,7 +25,7 @@ module Mutineer
     :cache_dir, :project_root, :load_paths,
     :jobs, :format, :output, :strategy, :require_paths,
     :boot, :rails, :since, :framework, :verbose, :ignore,
-    # :daemon is user-facing as of U8 (--daemon flag + KNOWN_KEYS + boolean coerce).
+    # :daemon is user-facing (--daemon flag + KNOWN_KEYS + boolean coerce).
     # :daemon_timeout stays programmatic (set by tests/Runner; no flag yet).
     :baseline, :baseline_epsilon, :fail_fast, :test_command,
     :daemon, :daemon_timeout,
@@ -33,7 +33,7 @@ module Mutineer
   ) do
     # Config file name.
     CONFIG_FILE = ".mutineer.yml"
-    # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
+    # Keys accepted in .mutineer.yml. `require` maps to the :require_paths field.
     KNOWN_KEYS = %w[operators jobs threshold only require boot rails since framework verbose ignore baseline fail_fast test_command daemon].freeze
 
     def initialize(**kwargs)
@@ -59,8 +59,8 @@ module Mutineer
 
     # Walk from `start` toward `home`, returning the first .mutineer.yml path found
     # or nil. Checks `home` itself, then stops; if `start` is above `home`
-    # (e.g. /tmp), the walk continues to the filesystem root (KTD4). Pure
-    # discovery — reads no file content.
+    # (e.g. /tmp), the walk continues to the filesystem root. Pure discovery;
+    # reads no file content.
     def self.find_file(start = Dir.pwd, home = File.expand_path("~"))
       dir = File.expand_path(start)
       loop do
@@ -77,9 +77,9 @@ module Mutineer
     end
 
     # Parse a .mutineer.yml into a symbol-keyed hash of recognized keys. Unknown
-    # keys / unknown operator names emit a one-line stderr warning and are ignored
-    # (R7). A YAML syntax error raises ConfigError (R7a/R8) — never a silent
-    # fallback to defaults, and never an exit from the lib layer.
+    # keys / unknown operator names emit a one-line stderr warning and are ignored.
+    # A YAML syntax error raises ConfigError: never a silent fallback to defaults,
+    # and never an exit from the lib layer.
     def self.from_file(path)
       raw = YAML.safe_load(File.read(path)) || {}
       name = File.basename(path)
@@ -103,7 +103,7 @@ module Mutineer
       raise ConfigError, "#{File.basename(path)} parse error: #{e.message}"
     end
 
-    # Apply precedence (KTD3): start from the CLI-provided values, then fill in a
+    # Apply precedence: start from the CLI-provided values, then fill in a
     # config-file value only for keys the user did NOT type on the command line.
     # `explicit` is a Set of field symbols the CLI saw with a value; a Set (not
     # nil-sentinels) is used because some valid values are zero/false.
@@ -114,7 +114,7 @@ module Mutineer
 
       # --rails sugar: boot config/environment. Prefer redefine only for the
       # in-process path (daemon is whole-file reload only). In-process --rails
-      # shares one test database — force serial unless --daemon.
+      # shares one test database, so force serial unless --daemon.
       if config.rails
         config.boot ||= "config/environment"
         unless config.daemon || explicit.include?(:strategy)
@@ -138,7 +138,6 @@ module Mutineer
 
     # Pick rspec when a MAJORITY of the given test files end with _spec.rb;
     # otherwise minitest. Empty/ambiguous -> minitest (the safe default).
-    # Detects the test framework from the file list.
     #
     # @param tests [Array<String>] test file paths.
     # @return [String] `"rspec"` or `"minitest"`.
@@ -187,10 +186,9 @@ module Mutineer
       end
     end
 
-    # Drop (with a warning) operator names the registry doesn't know (R7).
+    # Drop (with a warning) operator names the registry does not know.
     # Referenced lazily so config.rb carries no load-order dependency on the
     # registry; by the time a config is parsed at runtime, it is loaded.
-    # Filters out unknown operator names.
     #
     # @api private
     # @param names [Array<String>] operator names.