evilution 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b561b61697995a22463ea15828357375b1ce9868ad6ee87f3f331336d26b890
-  data.tar.gz: 4a0cb24bfe2e9e9478ab5d752f05ea4ea69582e324e736241f1fe6b1e5e581cd
+  metadata.gz: 12d485d3cce9569229a95a1e8f29403fbb11f8f067e0c438256919521f6d82dc
+  data.tar.gz: 11a1adeca7c61fa905757137d6a737c6e389eae584b37fca91a8c9eed57926d0
 SHA512:
-  metadata.gz: 416aaea92d50fc3a969c350fd36d47e5b8b625ba4b1c64b66f208731cfaf1250714b8bc8e494bbc1586922357886dd96026f31e9f96b7e2cd849e43f402de3e3
-  data.tar.gz: e81fc9c5edfa9e25b4a7077f2776c2256bf5211bc5d88b53cc604ef735d64366ee3b3a294a480f49d3107c7634ff98459f6f46e0a8ede3248cec2b72007f940e
+  metadata.gz: ce9208fa3f3ed3160d2844cdd5e1479cf7b2fa90985371cb95d6978177f371d38ec4bdccf473f79af318cd6c617fda2b1962efe4f389eab1912ab348cc48b475
+  data.tar.gz: 57ff4d971829430d5d47525ac0bc5e488b326e6916657aaf9acb3faf0e8795e909523ec8238b6b9fbaace13bdd60c0f437f30d94efbfa82861b42da802a54aac

data/.beads/interactions.jsonl

@@ -235,3 +235,13 @@
 {"id":"int-2abceed3","kind":"field_change","created_at":"2026-04-24T05:18:13.096916772Z","actor":"Denis Kiselev","issue_id":"EV-kjac","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
 {"id":"int-03bc2f7f","kind":"field_change","created_at":"2026-04-24T05:40:10.83959826Z","actor":"Denis Kiselev","issue_id":"EV-hklf","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
 {"id":"int-2781044c","kind":"field_change","created_at":"2026-04-24T05:40:11.975030418Z","actor":"Denis Kiselev","issue_id":"EV-cpku","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Folded into EV-hklf — error rename 'no method found' → 'no subject matched' shipped in PR #872."}}
+{"id":"int-3fd6fda2","kind":"field_change","created_at":"2026-04-24T17:15:49.060178577Z","actor":"Denis Kiselev","issue_id":"EV-3ew5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"PR #884 merged to master"}}
+{"id":"int-95f8d2f1","kind":"field_change","created_at":"2026-04-25T14:49:14.844074734Z","actor":"Denis Kiselev","issue_id":"EV-owgh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #890"}}
+{"id":"int-d786895b","kind":"field_change","created_at":"2026-04-25T15:46:53.977607499Z","actor":"Denis Kiselev","issue_id":"EV-a6de","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #891"}}
+{"id":"int-a297634a","kind":"field_change","created_at":"2026-04-25T16:56:08.483381206Z","actor":"Denis Kiselev","issue_id":"EV-ilu3","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #892"}}
+{"id":"int-0647d42f","kind":"field_change","created_at":"2026-04-25T17:06:39.083006592Z","actor":"Denis Kiselev","issue_id":"EV-aa4x","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #893"}}
+{"id":"int-86ea8eca","kind":"field_change","created_at":"2026-04-25T17:28:36.516431743Z","actor":"Denis Kiselev","issue_id":"EV-6x6g","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #894"}}
+{"id":"int-811fef5f","kind":"field_change","created_at":"2026-04-25T17:39:31.325092593Z","actor":"Denis Kiselev","issue_id":"EV-6c51","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #895"}}
+{"id":"int-9d182026","kind":"field_change","created_at":"2026-04-25T17:54:26.23542935Z","actor":"Denis Kiselev","issue_id":"EV-67yh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #897"}}
+{"id":"int-7ede49f5","kind":"field_change","created_at":"2026-04-25T18:16:18.358350457Z","actor":"Denis Kiselev","issue_id":"EV-zvhp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #898"}}
+{"id":"int-c28f7ee0","kind":"field_change","created_at":"2026-04-26T02:28:38.321564801Z","actor":"Denis Kiselev","issue_id":"EV-vev8","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #899"}}

data/.rubocop_todo.yml

@@ -0,0 +1,7 @@
+# This file lists per-file metric exclusions that should eventually be paid down
+# (refactor the file rather than expanding the exclude list). Inherited from .rubocop.yml.
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/evilution/config.rb"
+    - "lib/evilution/runner.rb"

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.27.0] - 2026-04-26
+
+### Added
+
+- **`prism` declared as a runtime dependency (`>= 1.5, < 2`)** — Rails 7.1 stacks pin `prism 0.19` (which lacks `IfNode#subsequent`), causing a `NoMethodError` on the first `if` evilution mutated. Bundler now refuses incompatible prism versions at install time instead of crashing at runtime (#876, PR #891)
+- **`--[no-]incremental` CLI flag** — `--no-incremental` overrides `incremental: true` from the config file for one invocation (cold-cache debugging, CI escape hatch). Last flag wins when both forms are given (#878, PR #897)
+- **`--quiet-children` and `--quiet-children-dir DIR` flags** — redirect each forked worker's stdout/stderr to per-pid files under `tmp/evilution_children/<pid>.{out,err}` (configurable). Keeps parent output clean when app initializers (Datadog, Bullet, etc.) emit warnings on every fork. Trade-off: live worker errors only appear in the side files (`tail -f tmp/evilution_children/*.err`) (#880, PR #899)
+- **Preload autodetect chain extended** — `Runner::IsolationResolver` now probes `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb` (was: rails_helper + test_helper only). Rails projects that consolidate everything into `spec/spec_helper.rb` no longer need an explicit `preload:` setting. When the chain finds nothing under a Rails project, raises a `ConfigError` listing every path tried and pointing at `--preload` / `--no-preload` (#879, PR #898)
+- **`evilution version` prints the bundled `mcp` gem version** — second line shows `mcp gem X.Y.Z (server compatibility)`. Run inside the same bundle the MCP server uses to confirm what's loaded after a `bundle update` (#883, PR #894)
+- **Public feedback channel exposed across CLI and MCP surfaces** — when a run hits friction (`errored`, `unparseable`, or `unresolved` buckets > 0; baseline failure; MCP error response), evilution surfaces a single GitHub Discussions URL so agents can suggest filing feedback. CLI text reports gain a one-line footer; the CLI error-exit path emits the same line on stderr (both suppressed by `--quiet`, `--format=json`, `--format=html`). MCP `evilution-mutate` responses embed `feedback_url` + `feedback_hint` on friction (and always on error payloads); the `minimal` verbosity contract is preserved (no extra keys). New MCP `evilution-info action=feedback` returns `{ discussion_url, version, guidance_for_agent }` on demand for any feedback intent including missing-capability requests on clean runs. Tool descriptions and the README MCP "Feedback channel" subsection prominently document the **explicit user-consent gate** (agents must never post on the user's behalf without explicit approval) and **privacy expectations** (never include secrets, env vars, project name, file paths, source code, or class/method names from user code — the channel is public). By construction, no run-derived data is embedded in any feedback field — agent + user compose any actual payload themselves (#900, PR #901)
+
+### Fixed
+
+- **`Cache#store` crashed with `TypeError: no implicit conversion of nil into String` when `incremental: true` and `jobs >= 2`** — `Strategy::Parallel#run_batch` called `batch.each(&:strip_sources!)` before `@cache.store`, leaving `mutation.original_source = nil` for `Digest::SHA256.hexdigest`. Reordered so store runs before strip; added a defensive nil-source guard in `Cache#store` mirroring the existing one in `Cache#fetch` (#875, PR #890)
+- **`block_removal` produced unparseable mutations on block-pass arguments (`map!(&:sym)`, `index_by(&:id)`, `flat_map(&block)`)** — operator stripped the `BlockArgumentNode` from inside the call's parens, leaving a dangling open paren. Operator now skips emission when `node.block.is_a?(Prism::BlockArgumentNode)`; explicit `{}` / `do..end` blocks are unaffected (#881, PR #895)
+- **`method_body_replacement` errored at runtime when generating the `super`-replacement on methods whose enclosing class had no parent implementation** — `super`-replacement now only emitted when the original body already calls `super` (`SuperNode` or `ForwardingSuperNode`), using that as a heuristic that a super target exists in this context. Methods without `super` get only the `nil` and `self` replacements (#877, PR #892)
+
+### Documentation
+
+- **README "Installing on Rails 7.1 + Ruby 3.3" section** — covers the `cgi 0.5.0` (Rails-pinned) vs `cgi 0.5.1` (Ruby 3.3 default-gem) Bundler activation conflict, the sidecar `Gemfile.local` workaround (`eval_gemfile("Gemfile")` + add evilution + prism), the `BUNDLE_GEMFILE=Gemfile.local` invocation, and guidance on whether to commit or `.gitignore` the resulting `Gemfile.local.lock` (#882, PR #893)
+- **README MCP "After upgrading the gem: restart the MCP server" subsection** — explains that the MCP server is a long-lived stdio process the agent host spawns; `bundle update evilution` swaps the gem on disk but the running process keeps the old code in memory until restart. Symptom is opaque "Internal error" responses to flags the old build doesn't recognize (#883, PR #894)
+
 ## [0.26.0] - 2026-04-24
 
 ### Removed

data/README.md

@@ -21,6 +21,44 @@ Then: `bundle install`
 
 Or standalone: `gem install evilution`
 
+Requires `prism >= 1.5, < 2`. Older Rails apps (e.g. Rails 7.1 pins `prism 0.19`) must upgrade prism — the gemspec constraint forces bundler to resolve a compatible 1.x version. If your app pins `prism 2.x`, bundler will reject the install until evilution widens its upper bound.
+
+### Installing on Rails 7.1 + Ruby 3.3
+
+Two Bundler conflicts hit fresh installs on this stack:
+
+1. **`cgi` activation conflict.** Rails 7.1's `Gemfile.lock` pins `cgi 0.5.0`. Ruby 3.3.x ships `cgi 0.5.1` as a default gem. Loading evilution via Bundler aborts with:
+
+   ```
+   Gem::LoadError: can't activate cgi-0.5.1, already activated cgi-0.5.0.
+   Make sure all dependencies are added to Gemfile.
+   ```
+
+2. **`prism` pin.** Same lockfile pins `prism 0.19`, which lacks the `IfNode#subsequent` accessor evilution uses (older Prism releases exposed it as `consequent`). Symptom: `NoMethodError: undefined method 'subsequent' for an instance of Prism::IfNode`.
+
+Both resolve cleanly with a sidecar `Gemfile.local` that re-evaluates the project Gemfile and adds evilution + prism on top — no edits to the main `Gemfile.lock`:
+
+```ruby
+# Gemfile.local
+eval_gemfile("Gemfile")
+
+group :test, :development do
+  gem "evilution"
+  gem "prism", "~> 1.5"
+end
+```
+
+Then invoke evilution against that Gemfile:
+
+```sh
+BUNDLE_GEMFILE=Gemfile.local bundle install
+BUNDLE_GEMFILE=Gemfile.local bundle exec evilution run lib/foo.rb
+```
+
+The first command writes a sibling `Gemfile.local.lock`. Decide whether to commit or `.gitignore` it the same way you would for any developer-only Gemfile — typically gitignored when only one or two engineers run mutation testing locally, committed when CI also runs evilution against the sidecar Gemfile.
+
+The evilution gemspec already declares `prism >= 1.5, < 2`, so adding the `gem "prism"` line above is only necessary on stacks that also pin prism in `Gemfile.lock`.
+
 ## Command Reference
 
 ```
@@ -67,11 +105,13 @@ The shorter alias `evil` ships alongside `evilution` and accepts identical argum
 | `-q`, `--quiet`              | Boolean | false        | Suppress output.                                   |
 | `--stdin`                    | Boolean | false        | Read target file paths from stdin (one per line).  |
 | `--integration NAME`         | String  | `rspec`      | Test framework integration: `rspec` or `minitest`.  |
-| `--incremental`              | Boolean | false        | Cache killed/timeout results; skip unchanged mutations on re-runs. |
+| `--[no-]incremental`         | Boolean | false        | Cache killed/timeout results; skip unchanged mutations on re-runs. Pass `--no-incremental` to override `incremental: true` from the config file for one invocation (e.g. cold-cache debugging). Last flag wins when both are given. |
 | `--save-session`             | Boolean | false        | Persist results as timestamped JSON under `.evilution/results/`. |
 | `--no-progress`              | Boolean | _(enabled)_  | Disable the TTY progress bar.                      |
+| `--quiet-children`           | Boolean | false        | Redirect each forked worker's stdout/stderr to per-pid files under `tmp/evilution_children/<pid>.{out,err}` so noisy app initializers (Datadog, Bullet, etc.) don't merge with parent output. Trade-off: live worker errors only appear in the side files, not the terminal — `tail -f tmp/evilution_children/*.err` to watch them. |
+| `--quiet-children-dir DIR`   | String  | `tmp/evilution_children` | Override the directory used by `--quiet-children`.    |
 | `--isolation MODE`           | String  | `auto`       | Isolation strategy: `auto`, `fork`, or `in_process`. `auto` selects `fork` for Rails projects. See [docs/isolation.md](docs/isolation.md). |
-| `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers (e.g. `spec/rails_helper.rb`). Auto-detected for Rails. |
+| `--preload FILE`             | String  | _(auto)_     | File to require in parent before forking workers. Auto-detect chain for Rails projects: `spec/rails_helper.rb` → `spec/spec_helper.rb` → `test/test_helper.rb`. Errors with the full chain listed if none exist; pass `--no-preload` to opt out. |
 | `--no-preload`               | Boolean | _(enabled)_  | Disable parent-process preload.                     |
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
@@ -323,7 +363,7 @@ The server exposes the following tools:
 |---|---|
 | `evilution-mutate` | Run mutation testing on target files with structured JSON results |
 | `evilution-session` | Inspect mutation testing history — `action: list` browses saved sessions, `action: show` displays one, `action: diff` compares two (fixed/new/persistent survivors, score delta) |
-| `evilution-info` | Discovery before mutation — `action: subjects` lists mutatable methods with mutation counts, `action: tests` resolves which specs cover given sources, `action: environment` dumps the effective config |
+| `evilution-info` | Discovery before mutation — `action: subjects` lists mutatable methods with mutation counts, `action: tests` resolves which specs cover given sources, `action: environment` dumps the effective config, `action: statuses` returns the mutation-result status glossary, `action: feedback` returns the public Discussions URL plus consent + privacy guidance for posting feedback |
 
 ### Verbosity Control
 
@@ -375,6 +415,20 @@ Pass `skip_config: true` to ignore the project config file. This skips loading `
 
 > **Note**: `.mcp.json` is gitignored by default since it is a local editor/agent configuration file.
 
+### After upgrading the gem: restart the MCP server
+
+The MCP server is a long-lived stdio process spawned by the agent host. `bundle update evilution` swaps the gem on disk but the running process keeps the old code in memory — symptom is opaque "Internal error" responses to flags or shapes the old build doesn't recognize. Restart the server (reload the workspace in Claude Code / Copilot / etc.) so the new gem loads.
+
+`evilution version` prints the gem version and the bundled `mcp` gem version on separate lines — run it in the same bundle the MCP server uses to confirm what's loaded.
+
+### Feedback channel
+
+When evilution causes friction (errors, usage problems, missing capabilities you wish were there), the MCP responses include a `feedback_url` plus `feedback_hint`. The `evilution-info` tool also exposes `action=feedback`, which returns the channel URL and posting guidance on demand.
+
+**Agents must never post on the user's behalf without explicit user permission.** Show the user exactly what you would post, get explicit approval, then post. Never include secrets, environment variables, the project name, file paths, source code, or class/method names from user code — the feedback channel is public.
+
+Discussion URL: <https://github.com/marinazzio/evilution/discussions>
+
 ## Recommended Workflows for AI Agents
 
 ### 1. Full project scan

data/lib/evilution/cache.rb

@@ -27,6 +27,8 @@ class Evilution::Cache
   end
 
   def store(mutation, result_data)
+    return if mutation.original_source.nil?
+
     file_key = file_key(mutation)
     entry_key = entry_key(mutation)
     data = read_file(file_key) || {}

data/lib/evilution/child_output.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../evilution"
+
+module Evilution::ChildOutput
+  module_function
+
+  class << self
+    attr_accessor :log_dir
+  end
+
+  # Per-run truncation happens once in the parent (Runner#configure_child_output);
+  # within a run, multiple forks reusing the same PID (pool worker recycle, per-mutation
+  # forks) append so cross-fork output isn't lost.
+  def redirect!
+    return unless log_dir
+
+    pid = Process.pid
+    $stdout.reopen(File.join(log_dir, "#{pid}.out"), "a")
+    $stderr.reopen(File.join(log_dir, "#{pid}.err"), "a")
+    $stdout.sync = true
+    $stderr.sync = true
+  end
+end

data/lib/evilution/cli/commands/run.rb

@@ -10,6 +10,7 @@ require_relative "../../runner"
 require_relative "../../hooks"
 require_relative "../../hooks/registry"
 require_relative "../../hooks/loader"
+require_relative "../../feedback/messages"
 
 class Evilution::CLI::Commands::Run < Evilution::CLI::Command
   def call
@@ -34,10 +35,18 @@ class Evilution::CLI::Commands::Run < Evilution::CLI::Command
       @stdout.puts(JSON.generate(error_payload(error)))
       Evilution::CLI::Result.new(exit_code: 2, error: error, error_rendered: true)
     else
+      @stderr.puts(Evilution::Feedback::Messages.cli_footer) unless quiet?(config, file_options)
       Evilution::CLI::Result.new(exit_code: 2, error: error)
     end
   end
 
+  def quiet?(config, file_options)
+    return config.quiet unless config.nil?
+    return true if @options[:quiet]
+
+    file_options && file_options[:quiet]
+  end
+
   def build_hooks(config)
     return nil if config.hooks.empty?
 

data/lib/evilution/cli/commands/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "mcp"
 require_relative "../commands"
 require_relative "../command"
 require_relative "../dispatcher"
@@ -10,6 +11,7 @@ class Evilution::CLI::Commands::Version < Evilution::CLI::Command
 
   def perform
     @stdout.puts(Evilution::VERSION)
+    @stdout.puts("mcp gem #{::MCP::VERSION} (server compatibility)")
     0
   end
 end

data/lib/evilution/cli/parser/options_builder.rb

@@ -70,15 +70,29 @@ class Evilution::CLI::Parser::OptionsBuilder
     opts.on("--fail-fast", "Stop after N surviving mutants " \
                            "(default: disabled; if provided without N, uses 1; use --fail-fast=N)") { @options[:fail_fast] ||= 1 }
     opts.on("--no-baseline", "Skip baseline test suite check") { @options[:baseline] = false }
-    opts.on("--incremental", "Cache killed/timeout results; skip re-running them on unchanged files") { @options[:incremental] = true }
+    opts.on("--[no-]incremental",
+            "Cache killed/timeout results; skip re-running them on unchanged files. " \
+            "Use --no-incremental to override `incremental: true` from the config file for one run.") do |v|
+      @options[:incremental] = v
+    end
     opts.on("--integration NAME", "Test integration: rspec, minitest (default: rspec)") { |i| @options[:integration] = i }
     opts.on("--isolation STRATEGY", "Isolation: auto, fork, in_process (default: auto)") { |s| @options[:isolation] = s }
     opts.on("--preload FILE", "Preload FILE in the parent process before forking " \
-                              "(default: auto-detect spec/rails_helper.rb for Rails projects)") { |f| @options[:preload] = f }
+                              "(default: auto-detect spec/rails_helper.rb -> spec/spec_helper.rb -> " \
+                              "test/test_helper.rb for Rails projects)") { |f| @options[:preload] = f }
     opts.on("--no-preload", "Disable parent-process preload even for Rails projects") { @options[:preload] = false }
     opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
     opts.on("--suggest-tests", "Generate concrete test code in suggestions (RSpec or Minitest)") { @options[:suggest_tests] = true }
     opts.on("--no-progress", "Disable progress bar") { @options[:progress] = false }
+    opts.on("--quiet-children",
+            "Redirect each child process's stdout/stderr to per-pid files under " \
+            "tmp/evilution_children (or --quiet-children-dir DIR), keeping parent output clean.") do
+      @options[:quiet_children] = true
+    end
+    opts.on("--quiet-children-dir DIR",
+            "Directory for --quiet-children per-pid log files (default: tmp/evilution_children)") do |d|
+      @options[:quiet_children_dir] = d
+    end
   end
 
   def add_extra_flag_options(opts)

data/lib/evilution/config/builders/spec_resolver.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "../builders"
+require_relative "../../spec_resolver"
+
+class Evilution::Config::Builders::SpecResolver
+  def self.call(integration:)
+    case integration
+    when :minitest
+      Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
+    else
+      Evilution::SpecResolver.new
+    end
+  end
+end

data/lib/evilution/config/builders/spec_selector.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../builders"
+require_relative "spec_resolver"
+require_relative "../../spec_selector"
+
+class Evilution::Config::Builders::SpecSelector
+  def self.call(spec_files:, spec_mappings:, spec_pattern:, integration:)
+    Evilution::SpecSelector.new(
+      spec_files: spec_files,
+      spec_mappings: spec_mappings,
+      spec_pattern: spec_pattern,
+      spec_resolver: Evilution::Config::Builders::SpecResolver.call(integration: integration)
+    )
+  end
+end

data/lib/evilution/config/builders.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module Evilution::Config::Builders
+end

data/lib/evilution/config/env_loader.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Evilution::Config::EnvLoader
+  module_function
+
+  def load
+    opts = {}
+    val = ENV.fetch("EV_DISABLE_EXAMPLE_TARGETING", nil)
+    opts[:example_targeting] = false if val && !val.empty? && val != "0"
+    opts
+  end
+end

data/lib/evilution/config/file_loader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Evilution::Config::FileLoader
+  module_function
+
+  def load
+    Evilution::Config::CONFIG_FILES.each do |path|
+      next unless File.exist?(path)
+
+      data = YAML.safe_load_file(path, symbolize_names: true)
+      return data.is_a?(Hash) ? data : {}
+    rescue Psych::SyntaxError, Psych::DisallowedClass => e
+      raise Evilution::ConfigError.new("failed to parse config file #{path}: #{e.message}", file: path)
+    rescue SystemCallError => e
+      raise Evilution::ConfigError.new("cannot read config file #{path}: #{e.message}", file: path)
+    end
+
+    {}
+  end
+end

data/lib/evilution/config/sources.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "file_loader"
+require_relative "env_loader"
+
+module Evilution::Config::Sources
+  module_function
+
+  def merge(explicit:, skip_file:)
+    file = skip_file ? {} : Evilution::Config::FileLoader.load
+    env  = Evilution::Config::EnvLoader.load
+    Evilution::Config::DEFAULTS.merge(file).merge(env).merge(explicit)
+  end
+end

data/lib/evilution/config/validators/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../validators"
+
+class Evilution::Config::Validators::Base
+  def self.call(_value)
+    raise NotImplementedError
+  end
+
+  class << self
+    private
+
+    def coerce_symbol!(value, allowed:, name:)
+      raise Evilution::ConfigError, "#{name} must be #{allowed.join(" or ")}, got nil" if value.nil?
+
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise Evilution::ConfigError, "#{name} must be #{allowed.join(" or ")}, got #{value.inspect}"
+      end
+
+      sym = value.to_sym
+      return sym if allowed.include?(sym)
+
+      raise Evilution::ConfigError, "#{name} must be #{allowed.join(" or ")}, got #{sym.inspect}"
+    end
+
+    def coerce_positive_int!(value, name:)
+      raise Evilution::ConfigError, "#{name} must be a positive integer, got #{value.inspect}" if value.is_a?(Float)
+
+      int = Integer(value)
+      raise Evilution::ConfigError, "#{name} must be a positive integer, got #{int}" unless int >= 1
+
+      int
+    rescue ::ArgumentError, ::TypeError
+      raise Evilution::ConfigError, "#{name} must be a positive integer, got #{value.inspect}"
+    end
+  end
+end

data/lib/evilution/config/validators/example_targeting_cache.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::ExampleTargetingCache < Evilution::Config::Validators::Base
+  def self.call(value)
+    raise Evilution::ConfigError, "example_targeting_cache must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+    normalized = normalize_keys(value)
+    merged = Evilution::Config::DEFAULTS[:example_targeting_cache].merge(normalized)
+    require_positive_int!(merged, :max_files)
+    require_positive_int!(merged, :max_blocks)
+    merged
+  end
+
+  class << self
+    private
+
+    def normalize_keys(value)
+      value.each_with_object({}) do |(k, v), acc|
+        unless k.is_a?(String) || k.is_a?(Symbol)
+          raise Evilution::ConfigError,
+                "example_targeting_cache keys must be Strings or Symbols, got #{k.inspect}"
+        end
+        acc[k.to_sym] = v
+      end
+    end
+
+    def require_positive_int!(cache, key)
+      v = cache[key]
+      return if v.is_a?(Integer) && v >= 1
+
+      raise Evilution::ConfigError,
+            "example_targeting_cache.#{key} must be a positive integer, got #{v.inspect}"
+    end
+  end
+end

data/lib/evilution/config/validators/example_targeting_fallback.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::ExampleTargetingFallback < Evilution::Config::Validators::Base
+  FALLBACKS = %i[full_file unresolved].freeze
+
+  def self.call(value)
+    unless value.is_a?(String) || value.is_a?(Symbol)
+      raise Evilution::ConfigError,
+            "example_targeting_fallback must be full_file or unresolved, got #{value.inspect}"
+    end
+
+    sym = value.to_sym
+    unless FALLBACKS.include?(sym)
+      raise Evilution::ConfigError,
+            "example_targeting_fallback must be full_file or unresolved, got #{sym.inspect}"
+    end
+
+    sym
+  end
+end

data/lib/evilution/config/validators/fail_fast.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::FailFast < Evilution::Config::Validators::Base
+  def self.call(value)
+    return nil if value.nil?
+
+    coerce_positive_int!(value, name: "fail_fast")
+  end
+end

data/lib/evilution/config/validators/hooks.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::Hooks < Evilution::Config::Validators::Base
+  def self.call(value)
+    return {} if value.nil?
+    raise Evilution::ConfigError, "hooks must be a mapping of event names to file paths, got #{value.class}" unless value.is_a?(Hash)
+
+    value
+  end
+end

data/lib/evilution/config/validators/ignore_patterns.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::IgnorePatterns < Evilution::Config::Validators::Base
+  def self.call(value)
+    patterns = Array(value)
+    patterns.each do |pattern|
+      unless pattern.is_a?(String)
+        raise Evilution::ConfigError,
+              "ignore_patterns must be an array of strings, got #{pattern.class} (#{pattern.inspect})"
+      end
+    end
+    patterns
+  end
+end

data/lib/evilution/config/validators/integration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::Integration < Evilution::Config::Validators::Base
+  ALLOWED = %i[rspec minitest].freeze
+
+  def self.call(value)
+    coerce_symbol!(value, allowed: ALLOWED, name: "integration")
+  end
+end

data/lib/evilution/config/validators/isolation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::Isolation < Evilution::Config::Validators::Base
+  ALLOWED = %i[auto fork in_process].freeze
+  MESSAGE = "isolation must be auto, fork, or in_process"
+
+  def self.call(value)
+    raise Evilution::ConfigError, "#{MESSAGE}, got nil" if value.nil?
+
+    raise Evilution::ConfigError, "#{MESSAGE}, got #{value.inspect}" unless value.is_a?(String) || value.is_a?(Symbol)
+
+    sym = value.to_sym
+    return sym if ALLOWED.include?(sym)
+
+    raise Evilution::ConfigError, "#{MESSAGE}, got #{sym.inspect}"
+  end
+end

data/lib/evilution/config/validators/jobs.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::Jobs < Evilution::Config::Validators::Base
+  def self.call(value)
+    coerce_positive_int!(value, name: "jobs")
+  end
+end

data/lib/evilution/config/validators/preload.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::Preload < Evilution::Config::Validators::Base
+  def self.call(value)
+    return nil if value.nil?
+    return false if value == false
+    return value if value.is_a?(String)
+
+    raise Evilution::ConfigError, "preload must be nil, false, or a String path, got #{value.inspect}"
+  end
+end

data/lib/evilution/config/validators/spec_mappings.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::SpecMappings < Evilution::Config::Validators::Base
+  def self.call(value)
+    return {} if value.nil?
+
+    raise Evilution::ConfigError, "spec_mappings must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+    normalized = value.each_with_object({}) do |(source, specs), acc|
+      key = normalize_key(source)
+      acc[key] = normalize_value(key, specs)
+    end
+
+    warn_missing(normalized)
+    normalized
+  end
+
+  class << self
+    private
+
+    def normalize_key(source)
+      key = source.to_s
+      key = key.delete_prefix("#{Dir.pwd}/") if key.start_with?("/")
+      key.delete_prefix("./")
+    end
+
+    def normalize_value(source, specs)
+      case specs
+      when String then [specs]
+      when Array
+        specs.each do |entry|
+          unless entry.is_a?(String)
+            raise Evilution::ConfigError,
+                  "spec_mappings[#{source.inspect}] entries must be string paths, got #{entry.class}"
+          end
+        end
+        specs
+      else
+        raise Evilution::ConfigError,
+              "spec_mappings[#{source.inspect}] must be a string or array of strings, got #{specs.class}"
+      end
+    end
+
+    def warn_missing(mappings)
+      mappings.each do |source, specs|
+        specs.each do |spec_path|
+          next if File.exist?(spec_path)
+
+          warn "[evilution] spec_mappings[#{source.inspect}]: #{spec_path} not found, skipping"
+        end
+      end
+    end
+  end
+end

data/lib/evilution/config/validators/spec_pattern.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class Evilution::Config::Validators::SpecPattern < Evilution::Config::Validators::Base
+  def self.call(value)
+    return nil if value.nil?
+    return value if value.is_a?(String)
+
+    raise Evilution::ConfigError, "spec_pattern must be nil or a String glob, got #{value.class}"
+  end
+end