evilution 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41c28afbfc162902708394c367eb87150663ac64ab7b2228ee72ab7bb3b0549b
-  data.tar.gz: 269ec61ea7f4d9f083247b022ba7e331bfce85ebc62d75151cf0b14d6769a8f9
+  metadata.gz: 12d485d3cce9569229a95a1e8f29403fbb11f8f067e0c438256919521f6d82dc
+  data.tar.gz: 11a1adeca7c61fa905757137d6a737c6e389eae584b37fca91a8c9eed57926d0
 SHA512:
-  metadata.gz: 11f61c28eca30a943b6632066b8992860e2bf67fb1a617e8cf0ac6ccfcbbce33d48baec4452a57127aacaeacf2f834f6d01350be091a5d2bbd279df226e5cbc0
-  data.tar.gz: 6d3c6f07b8ddda520966ef2bc9616752fa693499fff18e0542e3059a1f1ff16ae9a56f9b68fe96eea6b90cb41981e5f87bc540238a2fd2e29f166f629cf1259f
+  metadata.gz: ce9208fa3f3ed3160d2844cdd5e1479cf7b2fa90985371cb95d6978177f371d38ec4bdccf473f79af318cd6c617fda2b1962efe4f389eab1912ab348cc48b475
+  data.tar.gz: 57ff4d971829430d5d47525ac0bc5e488b326e6916657aaf9acb3faf0e8795e909523ec8238b6b9fbaace13bdd60c0f437f30d94efbfa82861b42da802a54aac

data/.beads/interactions.jsonl

@@ -230,3 +230,18 @@
 {"id":"int-94972aae","kind":"field_change","created_at":"2026-04-20T16:13:12.727090894Z","actor":"Denis Kiselev","issue_id":"EV-0fgx","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #813 (commit 262b9ae). Integration spec spec/evilution/compare/integration_spec.rb + e2e fixtures landed. 15/15 examples pass."}}
 {"id":"int-4d639e4e","kind":"field_change","created_at":"2026-04-20T16:57:42.95949164Z","actor":"Denis Kiselev","issue_id":"EV-ynlo","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #816. SourceAstCache content-keyed LRU + ExampleFilter integration + BaselineRunner wiring."}}
 {"id":"int-c15ed3e8","kind":"field_change","created_at":"2026-04-20T17:49:38.782150309Z","actor":"Denis Kiselev","issue_id":"EV-toid","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-842a1d3a","kind":"field_change","created_at":"2026-04-21T05:01:55.401885343Z","actor":"Denis Kiselev","issue_id":"EV-h8pw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-c92539a9","kind":"field_change","created_at":"2026-04-21T05:04:50.605824487Z","actor":"Denis Kiselev","issue_id":"EV-vkq9","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"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/.claude/prompts/architect.md

@@ -66,17 +66,30 @@ Evilution
   ::AST::SourceSurgeon     # Text-level mutation at byte offsets
   ::Mutator::Base          # Abstract operator base (Prism::Visitor)
   ::Mutator::Registry      # Node type → operator mapping
-  ::Mutator::Operator::*   # 18 concrete mutation operators
+  ::Mutator::Operator::*   # 72 concrete mutation operators
   ::Isolation::Fork        # Fork + pipe per mutation
+  ::Integration::Base      # Template-method orchestrator; delegates mutation apply to Loading::MutationApplier
   ::Integration::RSpec     # RSpec programmatic test runner
+  ::Integration::Minitest  # Minitest programmatic test runner
+  ::Integration::Loading::MutationApplier      # Composes the mutation-apply pipeline
+  ::Integration::Loading::SyntaxValidator      # Prism parse check
+  ::Integration::Loading::SourceEvaluator      # eval w/ TOPLEVEL_BINDING + absolute path
+  ::Integration::Loading::ConstantPinner       # const_get top-level constants to defeat Zeitwerk re-autoload
+  ::Integration::Loading::RedefinitionRecovery # Strip constants + retry on "already defined"
+  ::Integration::Loading::ConcernStateCleaner  # Clear AS::Concern @_included_block / @_prepended_block
+  ::AST::ConstantNames     # Prism walk → fully-qualified class/module names
+  ::LoadPath::SubpathResolver # Shortest $LOAD_PATH-relative path for a file
   ::Coverage::Collector    # Ruby Coverage module wrapper
   ::Coverage::TestMap      # Source line → test file mapping
+  ::Compare::Categorizer   # Fixed / new / persistent / flaky / reintroduced bucketing
+  ::Compare::Normalizer    # Canonicalize mutation records for cross-run compare
   ::Diff::Parser           # Git diff output parser
   ::Diff::FileFilter       # Filter subjects to changed code
   ::Result::MutationResult # Single mutation outcome
   ::Result::Summary        # Aggregated results
   ::Reporter::JSON         # Structured output for AI agents
   ::Reporter::CLI          # Human-readable terminal output
+  ::Reporter::HTML         # Section-based HTML report
   ::Reporter::Suggestion   # Actionable fix hint generator
 ```
 

data/.claude/skills/create-issue/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: create-issue
+description: Create a beads issue and a matching GitHub issue, cross-linked via external-ref and description
+argument-hint: "--title <title> --description <desc> --type <type> --priority <0-4>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Create Cross-Linked Issue (Beads + GitHub)
+
+Create a beads issue and a matching GitHub issue in Port-Royal/vanilla-mafia, with each linking to the other.
+
+## Arguments
+
+All arguments are passed as `$ARGUMENTS`. Parse them as bd-style flags:
+
+- `--title` (required): Issue title
+- `--description` (required): Why this issue exists and what needs to be done
+- `--type` (required): `bug`, `feature`, or `task`
+- `--priority` (required): 0-4 (0=critical, 4=backlog)
+- `--parent` (optional): Parent beads issue ID for sub-tasks
+
+Example:
+```
+/create-issue --title "Fix login redirect" --description "After login, users are redirected to /dashboard instead of the page they came from" --type bug --priority 1
+```
+
+## Steps
+
+1. **Create the GitHub issue first** (to get the GH number):
+   ```
+   gh issue create --repo Port-Royal/vanilla-mafia --title "<title>" --body "<description>"
+   ```
+   Extract the issue number from the output.
+
+2. **Create the beads issue** with `--external-ref gh-<number>`:
+   ```
+   bd create --title "<title>" --description "<description>\n\nGH: #<gh-number>" --type <type> --priority <priority> --external-ref gh-<number>
+   ```
+   Extract the beads issue ID from the output.
+
+3. **Update the GitHub issue body** to include the beads ID:
+   ```
+   gh api repos/Port-Royal/vanilla-mafia/issues/<number> --method PATCH -f body="<description>
+
+   Beads: <beads-id>"
+   ```
+   Use `gh api` (not `gh issue edit`) to avoid the Projects Classic GraphQL error.
+
+4. **If `--parent` was provided**, set the parent on the beads issue:
+   ```
+   bd update <beads-id> --parent <parent-id>
+   ```
+
+5. **Display the result**: show both IDs in format `<beads-id> (GH #<number>)`.

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,43 @@
 # 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
+
+- **Deprecated MCP session tools removed** — `evilution-session-list`, `evilution-session-show`, `evilution-session-diff` shims (deprecated since #637 after consolidation into `evilution-session`) deleted (#686, PR #851)
+
+### Fixed
+
+- **`preload` silently ignored under `:in_process` isolation** — `Runner::IsolationResolver#perform_preload` gated the preload on `resolve_isolation == :fork`, so non-Rails projects (auto-resolving to `:in_process`) silently skipped `preload:` from `.evilution.yml` or `--preload`. Preload now runs for `:in_process` too (#868, PR #871)
+- **`--target ClassName` silently narrowed to git-changed files** — when only a class/method target was given with no file scope, `Runner::SubjectPipeline#target_files` fell back to `Git::ChangedFiles`, producing a misleading `no method found matching 'X'` error when the class file was not in the working-tree diff. Target files now resolve from the configured source when a method/class target is given without explicit file scope (#869, PR #872)
+
+### Changed
+
+- **Internal `Evilution::Compare` refactor** — `lib/evilution/compare.rb` split into one class per file under `lib/evilution/compare/` (`Categorizer`, `Detector`, `Fingerprint`, `InvalidInput`, `Normalizer`, `Record`); `rubocop:disable Style/OneClassPerFile` removed (#825, PR #852)
+- **Internal `Evilution::Integration::Base` refactor** — decomposed into focused collaborators under `Evilution::Integration::Loading::*` (`SyntaxValidator`, `SourceEvaluator`, `ConstantPinner`, `RedefinitionRecovery`, `ConcernStateCleaner`, `MutationApplier`) plus shared helpers `Evilution::AST::ConstantNames` and `Evilution::LoadPath::SubpathResolver`. `Integration::Base` now delegates mutation application to an injectable `MutationApplier`; no user-visible behavior change (#845, PR #873)
+
 ## [0.25.0] - 2026-04-21
 
 ### Added

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/ast/constant_names.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../ast"
+
+# Walks a Prism AST and returns every class/module constant declared, nested
+# names rendered fully-qualified (e.g. "Foo::Bar"). Order is source order:
+# outer declarations precede their nested children.
+class Evilution::AST::ConstantNames
+  def call(source)
+    result = Prism.parse(source)
+    return [] if result.failure?
+
+    collect(result.value)
+  end
+
+  private
+
+  def collect(node, nesting = [])
+    names = []
+    case node
+    when Prism::ModuleNode, Prism::ClassNode
+      const = node.constant_path.full_name
+      qualified = nesting.any? && !const.include?("::") ? "#{nesting.join("::")}::#{const}" : const
+      names << qualified
+      names.concat(collect(node.body, nesting + [const])) if node.body
+    when Prism::ProgramNode
+      names.concat(collect(node.statements, nesting)) if node.statements
+    when Prism::StatementsNode
+      node.body.each { |child| names.concat(collect(child, nesting)) }
+    end
+    names
+  end
+end

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/compare/invalid_input.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../compare"
+
+class Evilution::Compare::InvalidInput < StandardError
+  attr_reader :index
+
+  def initialize(message, index: nil)
+    super(message)
+    @index = index
+  end
+end

data/lib/evilution/compare.rb

@@ -1,15 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Style/OneClassPerFile
 module Evilution::Compare
 end
 
-class Evilution::Compare::InvalidInput < StandardError
-  attr_reader :index
-
-  def initialize(message, index: nil)
-    super(message)
-    @index = index
-  end
-end
-# rubocop:enable Style/OneClassPerFile
+require_relative "compare/invalid_input"

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