evilution 0.28.0 → 0.30.0

data/README.md

@@ -67,11 +67,13 @@ evilution [command] [options] [files...]
 
 The shorter alias `evil` ships alongside `evilution` and accepts identical arguments (handy with `alias be='bundle exec'` → `be evil run ...`).
 
+Every command, subcommand, and flag listed in this section is part of evilution's public CLI contract; see [docs/versioning.md](docs/versioning.md) for stability and deprecation rules.
+
 ### Commands
 
 | Command              | Description                                        | Default |
 |----------------------|----------------------------------------------------|---------|
-| `run`                | Execute mutation testing against files              | Yes     |
+| `run` (alias `mutate`) | Execute mutation testing against files            | Yes     |
 | `init`               | Generate `.evilution.yml` config file               |         |
 | `version`            | Print version string                                |         |
 | `subjects [files]`   | List mutation subjects with locations and counts    |         |
@@ -116,16 +118,33 @@ The shorter alias `evil` ships alongside `evilution` and accepts identical argum
 | `--skip-heredoc-literals`    | Boolean | false        | Skip all string literal mutations inside heredocs.  |
 | `--show-disabled`            | Boolean | false        | Report mutations skipped by `# evilution:disable` comments. |
 | `--fallback-full-suite`      | Boolean | false        | When no matching spec/test resolves for a mutation, run the whole test suite instead of marking it `:unresolved` and skipping. |
+| `--related-specs-heuristic`  | Boolean | false        | When a mutation removes an `includes(...)` call, also run matching specs from `spec/{requests,integration,features,system}` (Rails-style domain match on the source file's basename). Trades extra spec runs for higher kill rate on ORM mutations. |
 | `--baseline-session PATH`    | String  | _(none)_     | Saved session file for HTML report comparison.     |
 | `-e CODE`, `--eval CODE`     | String  | _(none)_     | Inline Ruby code for `util mutation` command.      |
 | `--profile NAME`             | String  | `default`    | Operator profile: `default` or `strict`. `strict` adds aggressive truthiness mutators (e.g. replaces `x.predicate?` with `nil`) intended for pre-merge audits. |
 | `--strict`                   | Boolean | false        | Shortcut for `--profile=strict`.                    |
 
+### Options (for `session` subcommands)
+
+| Flag                | Type    | Default              | Description                                                                                  |
+|---------------------|---------|----------------------|----------------------------------------------------------------------------------------------|
+| `--results-dir DIR` | String  | `.evilution/results` | Directory containing session result JSON files. Honored by `session list` and `session gc`.  |
+| `--limit N`         | Integer | _(none)_             | (`session list`) Show only the N most recent sessions.                                       |
+| `--since DATE`      | String  | _(none)_             | (`session list`) Show only sessions created on or after `DATE` (`YYYY-MM-DD`).               |
+| `--older-than D`    | String  | _(required)_         | (`session gc`) Delete sessions older than `D` (e.g. `30d`, `24h`, `1w`).                     |
+
+### Options (for `compare` command)
+
+| Flag             | Type   | Default   | Description                                                                                          |
+|------------------|--------|-----------|------------------------------------------------------------------------------------------------------|
+| `--against PATH` | String | _(none)_  | Prior (older) session JSON to diff against. Positional first argument is accepted as a fallback.     |
+| `--current PATH` | String | _(none)_  | Current (newer) session JSON. Positional second argument is accepted as a fallback.                  |
+
 ### Operator Profiles
 
 Two profiles ship out of the box:
 
-- **`default`** — the 72 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
+- **`default`** — the 74 stable operators registered in `Mutator::Registry.default`. Suitable for everyday CI runs; balances coverage signal against survivor noise.
 - **`strict`** — adds extra truthiness mutators on top of `default`. Currently `PredicateToNil` (replaces every `x.predicate?` call with `nil` to surface tests that only assert truthiness rather than exact return values). Use for pre-merge audits where you want maximum sensitivity at the cost of more survivors.
 
 Set via `--profile=strict`, the `--strict` shortcut, or `profile: strict` in `.evilution.yml`.
@@ -145,6 +164,7 @@ Generate default config: `bundle exec evilution init`
 Creates `.evilution.yml`:
 
 ```yaml
+schema_version: 1            # opts into strict validation (rejects unknown keys, refuses future versions)
 # timeout: 30              # seconds per mutation
 # format: text             # text | json | html
 # min_score: 0.0           # 0.0–1.0
@@ -165,6 +185,62 @@ Creates `.evilution.yml`:
 
 **Precedence**: CLI flags override `.evilution.yml` values.
 
+### Schema versioning
+
+`.evilution.yml` may declare an integer `schema_version` (currently `1`). Behavior:
+
+- **When declared** — strict mode. Unknown top-level keys raise `Evilution::ConfigError`. A `schema_version` greater than the installed gem supports is rejected so an old gem cannot silently misread a newer config.
+- **When omitted** — legacy lenient mode. Unknown keys are ignored.
+
+Compatibility policy for the `1.x` gem line:
+
+- New configuration keys are added in MINOR releases (additive only). Each new key takes a default that preserves prior behavior.
+- Existing keys are not removed, renamed, or have their semantics changed in any `1.x` release. Deprecated keys keep working through the entire `1.x` line; see [docs/versioning.md](docs/versioning.md).
+- `schema_version` is bumped only on incompatible changes — i.e. only at the next MAJOR release. `schema_version: 2` will ship with `evilution 2.0`.
+
+A JSON Schema covering every supported key lives at [`schema/evilution.config.schema.json`](schema/evilution.config.schema.json). Point editor / IDE YAML extensions at it for autocomplete and inline validation (e.g. VS Code `yaml.schemas`, JetBrains "Custom JSON Schema").
+
+### Configuration reference
+
+All keys recognised under `schema_version: 1`:
+
+| Key                          | Type                          | Default                                | Description                                                                                                                              |
+|------------------------------|-------------------------------|----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `schema_version`             | Integer                       | `1`                                    | Config schema version. Declaring it enables strict validation; omit for lenient mode.                                                    |
+| `timeout`                    | Integer                       | `30`                                   | Per-mutation timeout in seconds.                                                                                                         |
+| `format`                     | String                        | `text`                                 | Output format: `text`, `json`, `html`.                                                                                                   |
+| `target`                     | String / null                 | `null`                                 | Filter expression: method (`Foo#bar`), class (`Foo`), namespace (`Foo*`), descendants (`descendants:Foo`), source glob (`source:**/*.rb`). |
+| `min_score`                  | Float                         | `0.0`                                  | Minimum mutation score (0.0–1.0) for exit code 0.                                                                                        |
+| `integration`                | String                        | `rspec`                                | Test framework: `rspec` or `minitest`.                                                                                                   |
+| `verbose`                    | Boolean                       | `false`                                | Verbose output (RSS/GC stats per phase, error details for errored mutations).                                                            |
+| `quiet`                      | Boolean                       | `false`                                | Suppress output.                                                                                                                         |
+| `jobs`                       | Integer                       | `1`                                    | Number of parallel workers.                                                                                                              |
+| `fail_fast`                  | Integer / null                | `null`                                 | Stop after N surviving mutants. `null` = disabled.                                                                                       |
+| `baseline`                   | Boolean                       | `true`                                 | Run baseline test suite to detect pre-existing failures (marked `:neutral`).                                                             |
+| `isolation`                  | String                        | `auto`                                 | Isolation strategy: `auto`, `fork`, `in_process`. `auto` selects `fork` for Rails projects.                                              |
+| `incremental`                | Boolean                       | `false`                                | Cache killed/timeout results across runs.                                                                                                |
+| `suggest_tests`              | Boolean                       | `false`                                | Generate concrete test code in survivor suggestions (matches `integration`).                                                             |
+| `progress`                   | Boolean                       | `true`                                 | TTY progress bar.                                                                                                                        |
+| `save_session`               | Boolean                       | `false`                                | Save session JSON under `.evilution/results/`.                                                                                           |
+| `line_ranges`                | Hash                          | `{}`                                   | Per-file line-range constraints. Typically set via CLI; rare in YAML.                                                                    |
+| `spec_files`                 | Array<String>           | `[]`                                   | Explicit spec files to run. Bypasses auto-detection when non-empty.                                                                      |
+| `ignore_patterns`            | Array<String>           | `[]`                                   | AST patterns to skip during mutation generation. See [docs/ast_pattern_syntax.md](docs/ast_pattern_syntax.md).                           |
+| `show_disabled`              | Boolean                       | `false`                                | Report mutations skipped by `# evilution:disable` comments.                                                                              |
+| `baseline_session`           | String / null                 | `null`                                 | Saved session file path for HTML report comparison.                                                                                      |
+| `skip_heredoc_literals`      | Boolean                       | `false`                                | Skip string literal mutations inside heredocs.                                                                                           |
+| `related_specs_heuristic`    | Boolean                       | `false`                                | Append related request/integration/feature/system specs for `includes(...)` mutations.                                                   |
+| `fallback_to_full_suite`     | Boolean                       | `false`                                | When no matching spec resolves, run the entire suite instead of marking the mutation `:unresolved`.                                      |
+| `preload`                    | String / Boolean / null       | `null`                                 | File to preload in parent before forking. `false` to disable. `null` to auto-detect for Rails.                                           |
+| `spec_mappings`              | Hash<String, String/Array> | `{}`                                | Custom mapping from source path to spec path(s).                                                                                         |
+| `spec_pattern`               | String / null                 | `null`                                 | Glob restricting resolved spec candidates.                                                                                               |
+| `example_targeting`          | Boolean                       | `true`                                 | Per-mutation example-level targeting.                                                                                                    |
+| `example_targeting_fallback` | String                        | `full_file`                            | When targeting finds no example: `full_file` or `unresolved`.                                                                            |
+| `example_targeting_cache`    | Hash                          | `{ max_files: 50, max_blocks: 10000 }` | LRU cache bounds for the example-targeting AST parser.                                                                                   |
+| `quiet_children`             | Boolean                       | `false`                                | Redirect each worker's stdout/stderr to per-pid files under `quiet_children_dir`.                                                        |
+| `quiet_children_dir`         | String                        | `tmp/evilution_children`               | Directory for `--quiet-children` per-pid log files.                                                                                      |
+| `profile`                    | String                        | `default`                              | Operator profile: `default` or `strict`.                                                                                                 |
+| `hooks`                      | Hash<String, String>    | `{}`                                   | Lifecycle hooks: event name → path to a Ruby file returning a `Proc`.                                                                    |
+
 ## Disable Comments
 
 Suppress mutations on specific code with inline comments:
@@ -190,10 +266,13 @@ Use `--show-disabled` to see which mutations were skipped.
 
 ## JSON Output Schema
 
-Use `--format json` for machine-readable output. Schema:
+Use `--format json` for machine-readable output. The same shape is used for both stdout reports (`--format json`) and saved session files (`--save-session` → `.evilution/results/*.json`); session files add a small set of extra top-level fields described under [Session JSON files](#session-json-files) below.
+
+Schema:
 
 ```json
 {
+  "schema_version": "integer — schema version of this JSON document (current: 1)",
   "version": "string   — gem version",
   "timestamp": "string — ISO 8601 timestamp of the report",
   "summary": {
@@ -251,6 +330,36 @@ Use `--format json` for machine-readable output. Schema:
 
 **Key metric**: `summary.score` — the mutation score. Higher is better. 1.0 means all mutations were caught.
 
+### Session JSON files
+
+Sessions saved by `--save-session` (under `.evilution/results/*.json`) and consumed by `evilution session show`, `evilution session diff`, `evilution compare`, and the HTML reporter share the schema above with these additions:
+
+| Field                | Type    | Description                                                                                       |
+|----------------------|---------|---------------------------------------------------------------------------------------------------|
+| `git`                | Object  | `{ "sha": "<full SHA or null>", "branch": "<branch name or null>" }` captured at run time.        |
+| `killed_count`       | Integer | Top-level convenience counter; mirrors `summary.killed`.                                          |
+| `timed_out_count`    | Integer | Mirrors `summary.timed_out`.                                                                      |
+| `error_count`        | Integer | Mirrors `summary.errors`.                                                                         |
+| `neutral_count`      | Integer | Mirrors `summary.neutral`.                                                                        |
+| `equivalent_count`   | Integer | Mirrors `summary.equivalent`.                                                                     |
+| `skipped_count`      | Integer | Mutations skipped by `# evilution:disable` (omitted from `summary` unless positive).              |
+
+Saved sessions also omit the per-status arrays (`killed`, `neutral`, `equivalent`, `unresolved`, `unparseable`, `timed_out`, `errors`) — only `survived` and `coverage_gaps` are persisted. The score, totals, and timestamps are stable for diff/compare consumers.
+
+#### Schema versioning
+
+Every session and stdout JSON document carries a top-level `schema_version` integer (currently `1`). On read:
+
+- **`schema_version` matches what this gem supports** — proceed normally.
+- **`schema_version` is omitted** — treated as version `1` (the JSON shape that defined version 1). Sessions written before this field existed continue to load.
+- **`schema_version` is greater than what this gem supports** — `Evilution::Session::Store#load`, `evilution compare`, `evilution session show`, `evilution session diff`, and the HTML reporter raise `Evilution::Error` with the offending file path and a "Upgrade the evilution gem" message. We refuse to silently misread a newer document.
+
+Compatibility policy for the `1.x` gem line:
+
+- New top-level fields are added in MINOR releases (additive only). Consumers that ignore unknown fields keep working without changes.
+- Existing fields are not removed, renamed, or have their semantics changed in any `1.x` release.
+- `schema_version` is bumped only on incompatible changes — i.e. only at the next MAJOR release. `schema_version: 2` will ship with `evilution 2.0`. See [docs/versioning.md](docs/versioning.md) for the umbrella SemVer policy.
+
 ### Mutation Statuses
 
 | Status       | Meaning                                                               | Counted in score? |
@@ -266,7 +375,7 @@ Use `--format json` for machine-readable output. Schema:
 
 Unresolved mutations indicate a missing test mapping — the file has no corresponding test file that the resolver could find (for example, an RSpec `_spec.rb` file or a Minitest `_test.rb` file, depending on configuration). They are reported separately so you can act on them (add a test, adjust test naming, or opt in to the full-suite fallback) without inflating the error count.
 
-## Mutation Operators (72 total)
+## Mutation Operators (74 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
 
@@ -344,6 +453,8 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `lambda_body` | Replace lambda body with nil | `-> { expr }` -> `-> { nil }` |
 | `begin_unwrap` | Remove begin/end wrapper | `begin; expr; end` -> `expr` |
 | `block_param_removal` | Remove explicit block parameter | `def foo(&block)` -> `def foo` |
+| `last_expression_removal` | Strip trailing literal return from method body | `def foo?; warn; true; end` -> `def foo?; warn; end` |
+| `argument_method_call_replacement` | Replace a method-call argument with its receiver | `fn(x.attr)` -> `fn(x)` |
 
 ## MCP Server (AI Agent Integration)
 
@@ -382,11 +493,11 @@ The `evilution-mutate` tool accepts a `verbosity` parameter to control response
 
 | Level       | Default | What's included                                              |
 |-------------|---------|--------------------------------------------------------------|
-| `summary`   | Yes     | `summary` + `survived` + `timed_out` + `errors`             |
+| `summary`   | Yes     | `summary` + `survived` + `timed_out` + `errors` + `unresolved` (non-survived entries shed `diff` and `error_backtrace` to bound payload size) |
 | `full`      |         | All entries (killed/neutral/equivalent diffs stripped)        |
-| `minimal`   |         | `summary` + `survived` only                                  |
+| `minimal`   |         | `summary` + `survived` (plus a trimmed sample of up to 3 errored entries when `errors > 0`) |
 
-Use `minimal` when context window budget is tight and you only need to see what survived. Use `full` when you need to inspect killed/neutral/equivalent entries for debugging.
+Use `minimal` when context window budget is tight and you only need to see what survived. The trimmed `errors` sample (each entry: `error_message`, `error_class`, location, plus the first 5 backtrace lines) is added so a partly-broken run is still self-diagnosable without escalating verbosity. Use `full` when you need to inspect killed/neutral/equivalent entries for debugging.
 
 ### Enriched Survived Entries
 
@@ -440,6 +551,62 @@ When evilution causes friction (errors, usage problems, missing capabilities you
 
 Discussion URL: <https://github.com/marinazzio/evilution/discussions>
 
+### Contract stability
+
+The three MCP tools (`evilution-mutate`, `evilution-session`, `evilution-info`) form evilution's public contract for AI agents. From `1.0.0` onwards the following are governed by the gem's [SemVer policy](docs/versioning.md):
+
+- **Tool names**: `evilution-mutate`, `evilution-session`, `evilution-info`.
+- **Input schemas**: every parameter listed in each tool's `input_schema` (name, type, enum values, `required`).
+- **Action enumerations**: the action enum on `evilution-session` (`list`, `show`, `diff`) and `evilution-info` (`subjects`, `tests`, `environment`, `statuses`, `feedback`).
+- **Output payload top-level shape**: the keys and value types documented per action below.
+- **Error envelope**: an error response is a single text content with the response's `error` flag set to true. The body is a JSON object with at minimum an `error` key shaped `{ "type": <string>, "message": <string> }`; tools may add additional top-level keys (e.g. `evilution-mutate` includes `feedback_url` and `feedback_hint` to point agents at the public Discussions channel). Consumers must read the `error.type` discriminator and ignore unknown extras. The error type strings — currently `config_error`, `parse_error`, `not_found`, and `runtime_error` — are part of the contract; new types may be added in MINOR releases (additive).
+
+#### Output `schema_version`
+
+Successful MCP responses carry a top-level `schema_version` integer. Two distinct version spaces are in play; both happen to be `1` today and either may be bumped independently at the next MAJOR release:
+
+- **MCP contract `schema_version`** — `Evilution::MCP::CONTRACT_VERSION` (currently `1`). Stamped on envelopes that exist solely to wrap MCP tool output: `evilution-info` action responses, `evilution-session list`, `evilution-session diff`. Bumped only when the MCP envelope shape itself changes incompatibly.
+- **Session JSON `schema_version`** — `Evilution::Session::Schema::CURRENT_VERSION` (currently `1`). Embedded inside payloads whose shape is also written to disk and consumed elsewhere: `evilution-mutate` (returns a mutation report) and `evilution-session show` (returns a session JSON document). Bumped only when the report/session shape itself changes incompatibly.
+
+Per-tool placement:
+
+| Tool / action                  | `schema_version` source                  | Location in payload                                                                                  |
+|--------------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------|
+| `evilution-mutate`             | `Session::Schema::CURRENT_VERSION`       | Top-level of the mutation report JSON (same shape as `--save-session` output).                      |
+| `evilution-session` `list`     | `MCP::CONTRACT_VERSION`                  | Top-level of envelope: `{ "schema_version": 1, "sessions": [...] }`.                                 |
+| `evilution-session` `show`     | `Session::Schema::CURRENT_VERSION`       | Inside the returned session JSON document.                                                           |
+| `evilution-session` `diff`     | `MCP::CONTRACT_VERSION`                  | Top-level alongside `summary` / `fixed` / `new_survivors` / `persistent`.                            |
+| `evilution-info` (all actions) | `MCP::CONTRACT_VERSION`                  | Top-level of every successful response, injected by the action response formatter.                   |
+
+#### Per-tool output shapes
+
+- **`evilution-mutate`** — full schema in the [JSON Output Schema](#json-output-schema) section. MCP-specific additions to each `survived` entry are documented in [Enriched Survived Entries](#enriched-survived-entries).
+- **`evilution-session` `list`** — `{ "schema_version": Integer, "sessions": Array<{ file, timestamp, total, killed, survived, score, duration }> }`. Sessions are reverse-chronological; the array is filtered by `limit` when provided.
+- **`evilution-session` `show`** — the parsed session JSON document, exactly as written under `.evilution/results/*.json`. Field reference: see [Session JSON files](#session-json-files).
+- **`evilution-session` `diff`** — `{ "schema_version": Integer, "summary": { base_score, head_score, score_delta, base_survived, head_survived, base_total, head_total, base_killed, head_killed }, "fixed": Array, "new_survivors": Array, "persistent": Array }`. The mutation arrays carry the same per-mutation fields the session `survived` list uses (`operator`, `file`, `line`, `subject`, `diff`).
+- **`evilution-info` `subjects`** — `{ "schema_version": Integer, "subjects": Array<{ name, file, line, mutations }>, "total_subjects": Integer, "total_mutations": Integer }`.
+- **`evilution-info` `tests`** — `{ "schema_version": Integer, "specs": Array<{ source, spec }>, "unresolved": Array<String>, "total_sources": Integer, "total_specs": Integer }`.
+- **`evilution-info` `environment`** — `{ "schema_version": Integer, "version": String, "ruby": String, "config_file": String|null, ... }` mirroring the effective `Evilution::Config`.
+- **`evilution-info` `statuses`** — `{ "schema_version": Integer, "statuses": Array<{ name, meaning, in_score }> }`.
+- **`evilution-info` `feedback`** — `{ "schema_version": Integer, "discussion_url": String, "consent": String, "privacy": String }`.
+
+#### Deprecation cycle
+
+When a parameter, action, or output field on the public MCP contract is deprecated:
+
+1. The deprecation is announced in the CHANGELOG and the tool's `description` text gains a deprecation note.
+2. The deprecated form remains functional for the entire `1.x` line — a deprecation introduced in `1.X` continues to work in every subsequent `1.X+N` release.
+3. The earliest release that may remove the deprecated form is `2.0`. Removals are listed in the major-release migration guide.
+4. Adding new parameters, new actions, or new top-level output fields is additive and ships in MINOR releases (existing consumers continue to work).
+
+#### Not covered by the contract
+
+- The exact wording of error `message` strings (the `type` is contract; the message is a hint that may be reworded).
+- The exact ordering of arrays whose contract calls only for membership (e.g. `unresolved` source files).
+- Progress-stream notification payloads sent through `server_context.notifications` — these are best-effort UI signals, not a stable API.
+- Performance characteristics (request latency, memory, parallelism) — improvements ship in any release; regressions are bugs but not contract violations.
+- Default values that are part of the gem's user-facing semantics (timeout, integration default, etc.) — these follow the umbrella SemVer policy and may be tuned.
+
 ## Recommended Workflows for AI Agents
 
 ### 1. Full project scan
@@ -516,6 +683,21 @@ For each entry in `survived[]`:
 
 Entries in the JSON `errors[]` array represent mutations that raised an exception (syntax error, load failure, or runtime crash) rather than producing a test outcome. Each entry includes `error_class`, `error_message`, and the first 5 `error_backtrace` lines. Use these fields to decide whether the error is a bug in the mutation operator (file an issue), a load-time problem in the mutated source (often `NoMethodError: super called outside of method` or constant-redefinition issues), or a genuine crash that the original tests should have caught. Run with `--verbose` to stream the same error details to stderr during the run.
 
+### Long Minitest fork runs — not a hang
+
+Minitest projects under `--isolation=fork` re-bootstrap the test environment (`test_helper.rb`, plugins, runnable state) once per mutation. On constant-heavy files (e.g. Shopify/liquid's `lib/liquid/lexer.rb`, ~270 mutations) the wall-clock cost is dominated by that per-fork bootstrap and any mutations that hit a `--timeout` rather than killing the test fast. A single-worker run (`-j 1`) on a few hundred mutations can take 4+ minutes; combined with `--no-progress` and a non-TTY stderr (CI, redirected logs) the run looks silent the entire time.
+
+Recommended invocation for Minitest fork canaries:
+
+```bash
+RUBYOPT="-Itest" bundle exec evilution mutate lib/<file>.rb \
+  -j 4 -t 10 \
+  --integration=minitest --isolation=fork \
+  --spec test/<dir>/<file>_test.rb
+```
+
+`-j 4` parallelises across workers, `-t 10` caps any mutation that pathologically loops at 10 s. Expect the run to print progress only when stderr is a TTY (use `bundle exec evilution mutate ... 2>&1 | tee log` to get progress while still saving output). The historical "Minitest fork hangs on liquid" report (EV-blnq / GH #1211) turned out to be a slow run + silent UX, not an actual deadlock — the worker logs show steady forward progress when captured via `--quiet-children --quiet-children-dir DIR`.
+
 ### 8. CI gate
 
 ```bash
@@ -588,12 +770,16 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 1. **Parse** — Prism parses Ruby files into ASTs with exact byte offsets
 2. **Extract** — Methods are identified as mutation subjects
 3. **Filter** — Disable comments, Sorbet `sig` blocks, and AST ignore patterns exclude mutations before execution
-4. **Mutate** — 72 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default
+4. **Mutate** — 74 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default. Identical byte-mutations from different operators are deduplicated by `(file_path, mutated_source)` so the count is not inflated by overlap
 5. **Isolate** — Mutations are applied to temporary file copies (never modifying originals); load-path redirection ensures `require` resolves the mutated copy. Default isolation is in-process for plain Ruby projects and fork for Rails projects (auto-detected); `--isolation fork` forces forked child processes. Both sequential and parallel (`--jobs N`) modes respect the configured isolation strategy
 6. **Test** — The configured test framework (RSpec or Minitest) executes against the mutated source
 7. **Collect** — Source strings and AST nodes are released after use to minimize memory retention
 8. **Report** — Results aggregated into text, JSON, or HTML, including efficiency metrics and peak memory usage
 
+## Versioning
+
+`evilution` follows [Semantic Versioning](https://semver.org). The full policy — what counts as the public contract, what triggers a major bump, how deprecations work — is documented in [docs/versioning.md](docs/versioning.md).
+
 ## Repository
 
 https://github.com/marinazzio/evilution

data/docs/versioning.md

@@ -0,0 +1,53 @@
+# Versioning & Upgrade Policy
+
+This document defines what `evilution` promises across releases.
+
+## SemVer interpretation (1.x)
+
+| Bump          | Triggered by                                                                 |
+|---------------|-------------------------------------------------------------------------------|
+| MAJOR (`2.0`) | Removing or renaming anything in the public contract; changing semantics; tightening input validation. |
+| MINOR (`1.X`) | Adding a new CLI flag, config key, mutation operator, public Ruby method, or session/MCP field; relaxing validation; adding an operator to the `default` profile (whether brand-new or promoted from `strict`). |
+| PATCH (`1.X.Y`) | Bug fix, performance improvement, documentation, internal refactor with no observable contract effect. |
+
+## Public contract surface
+
+The following surfaces are covered by the SemVer guarantees above:
+
+- **Public Ruby API** — classes and methods explicitly documented as public. Everything else is internal and may change in any release.
+- **CLI flags and commands** — the README "Command Reference" tables are the authoritative list.
+- **`.evilution.yml` configuration keys** — see the README "Configuration" section.
+- **Session JSON files** (`.evilution/results/*.json`) — see the README "JSON Output Schema" section.
+- **MCP tool input/output schemas** (`evilution-mutate`, `evilution-session`, `evilution-info`) — see the README "MCP Server" section.
+- **Process exit codes** — `0` pass, `1` fail, `2` error. Documented in the README "Exit Codes" section.
+
+Anything not on this list is internal. It can change in any release without a deprecation cycle.
+
+## Deprecation cycle
+
+When a feature on the public contract surface is deprecated:
+
+1. It is marked with the YARD `@deprecated` tag (Ruby API), or with a deprecation note in the relevant doc table (CLI flags, config keys, MCP fields).
+2. Where the call site is reachable at runtime, a one-line warning is emitted to stderr.
+3. The deprecated form remains functional for the entire `1.x` line. A feature deprecated in any `1.X` release continues to work in every subsequent `1.X+N` release.
+4. The earliest release that may remove the feature is the next major (`2.0`), per the SemVer table above.
+5. Each removal is recorded in the CHANGELOG under the major-release entry.
+
+## Explicitly NOT contract
+
+The following are not part of the versioned contract and may change in any release, including patches:
+
+- **Mutation score values.** The score depends on the registered operator set, the operator profile, and your test suite. Adding a new operator to the `default` profile is a MINOR change (additive feature) but will shift scores. Pin both the gem version and the operator profile (`profile: default` or `profile: strict`) if you need a stable score across runs.
+- **Mutation operator output text.** Operator *names* (the `operator` field in JSON output, e.g. `arithmetic_replacement`) are part of the contract. The exact mutated source string an operator emits is diagnostic and may change to fix bugs or improve clarity.
+- **Internal classes** (any class not explicitly documented as part of the public Ruby API).
+- **Log lines, progress output, and human-readable report wording.**
+- **Performance characteristics** (timing, memory, parallel scheduling). Improvements ship in any release; regressions are bugs but not contract violations.
+
+## Upgrading
+
+- **Patch (`1.X.Y` → `1.X.Y+1`)** and **minor (`1.X` → `1.X+1`)**: drop in. Read the CHANGELOG for new flags or config keys you may want to opt into.
+- **Major (`1.X` → `2.0`)**: a migration guide ships with the release, listing every removed contract surface and the replacement path.
+
+## References
+
+- [CHANGELOG](../CHANGELOG.md) — chronological list of changes per release.

data/lib/evilution/ast/constant_names.rb

@@ -17,18 +17,35 @@ class Evilution::AST::ConstantNames
   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)) }
+    when Prism::ModuleNode, Prism::ClassNode then collect_class(node, nesting)
+    when Prism::ProgramNode then collect_program(node, nesting)
+    when Prism::StatementsNode then collect_statements(node, nesting)
+    else []
     end
-    names
+  end
+
+  def collect_class(node, nesting)
+    const = node.constant_path.full_name
+    qualified = qualify(const, nesting)
+    return [qualified] if node.body.nil?
+
+    [qualified] + collect(node.body, nesting + [const])
+  end
+
+  def collect_program(node, nesting)
+    return [] if node.statements.nil?
+
+    collect(node.statements, nesting)
+  end
+
+  def collect_statements(node, nesting)
+    node.body.flat_map { |child| collect(child, nesting) }
+  end
+
+  def qualify(const, nesting)
+    return const if nesting.empty? || const.include?("::")
+
+    "#{nesting.join("::")}::#{const}"
   end
 end

data/lib/evilution/ast/heredoc_span.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../ast"
+
+# Computes the byte-length needed for a mutation whose target range contains
+# heredoc anchors (`<<~MARKER` / `<<-MARKER` / `<<MARKER`).
+#
+# Prism reports a heredoc anchor's `location` as the inline range of just
+# `<<~MARKER` — the body lines and the closing terminator live in `closing_loc`
+# which is on a later line. An operator that builds a byte edit from the
+# anchor's inline range (e.g. `argument_removal` using
+# `node.arguments.location`) covers the anchor but leaves the body+terminator
+# in place, producing an orphaned heredoc fragment that the parser rejects.
+#
+# `extend_length` walks the supplied AST node for heredoc descendants whose
+# anchor falls inside `[offset, offset + length)` and returns a length wide
+# enough to also cover those descendants' `closing_loc.end_offset` — so the
+# mutation's `replacement` replaces the heredoc body and terminator along with
+# the anchor.
+module Evilution::AST::HeredocSpan
+  module_function
+
+  def extend_length(node:, offset:, length:)
+    return length if node.nil?
+
+    end_offset = offset + length
+    max_end = end_offset
+    Walker.new(offset, end_offset) do |closing_end|
+      max_end = closing_end if closing_end > max_end
+    end.visit(node)
+    max_end - offset
+  end
+
+  class Walker < Prism::Visitor
+    def initialize(start_offset, end_offset, &block)
+      super()
+      @start_offset = start_offset
+      @end_offset = end_offset
+      @block = block
+    end
+
+    def visit_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    def visit_interpolated_x_string_node(node)
+      record_if_heredoc(node)
+      super
+    end
+
+    private
+
+    def record_if_heredoc(node)
+      return unless heredoc?(node)
+
+      closing = node.closing_loc
+      return unless anchor_in_range?(node) && closing
+
+      @block.call(closing_end_excluding_trailing_newline(closing))
+    end
+
+    def heredoc?(node)
+      node.respond_to?(:heredoc?) && node.heredoc?
+    end
+
+    # Anchor must be inside the mutation's target range; only then does its
+    # heredoc body sit outside the range and need pulling in.
+    def anchor_in_range?(node)
+      opening = node.opening_loc
+      return false if opening.nil?
+
+      opening.start_offset >= @start_offset && opening.start_offset < @end_offset
+    end
+
+    # Prism's closing_loc covers the terminator including the trailing
+    # newline. Excluding that newline preserves line structure after the
+    # replacement (any code that follows lands on its own line).
+    def closing_end_excluding_trailing_newline(closing)
+      end_off = closing.end_offset
+      slice = closing.slice
+      end_off -= 1 if slice && slice.end_with?("\n")
+      end_off
+    end
+  end
+  private_constant :Walker
+end

data/lib/evilution/ast/pattern/parser.rb

@@ -75,24 +75,36 @@ class Evilution::AST::Pattern::Parser
 
   def parse_value
     skip_whitespace
+    parse_negation || parse_deep_wildcard || parse_single_wildcard || parse_any_node || parse_value_or_nested
+  end
 
-    if current_char == "!"
-      advance(1)
-      skip_whitespace
-      inner = parse_value
-      Evilution::AST::Pattern::NegationMatcher.new(inner)
-    elsif current_char == "*" && !peek_string("**")
-      advance(1)
-      Evilution::AST::Pattern::WildcardValueMatcher.new
-    elsif peek_string("**")
-      advance(2)
-      Evilution::AST::Pattern::DeepWildcardMatcher.new
-    elsif current_char == "_" && !identifier_continues?(1)
-      advance(1)
-      Evilution::AST::Pattern::AnyNodeMatcher.new
-    else
-      parse_value_or_nested
-    end
+  def parse_negation
+    return nil unless current_char == "!"
+
+    advance(1)
+    skip_whitespace
+    Evilution::AST::Pattern::NegationMatcher.new(parse_value)
+  end
+
+  def parse_deep_wildcard
+    return nil unless peek_string("**")
+
+    advance(2)
+    Evilution::AST::Pattern::DeepWildcardMatcher.new
+  end
+
+  def parse_single_wildcard
+    return nil unless current_char == "*"
+
+    advance(1)
+    Evilution::AST::Pattern::WildcardValueMatcher.new
+  end
+
+  def parse_any_node
+    return nil unless current_char == "_" && !identifier_continues?(1)
+
+    advance(1)
+    Evilution::AST::Pattern::AnyNodeMatcher.new
   end
 
   def parse_value_or_nested

data/lib/evilution/baseline.rb

@@ -15,16 +15,18 @@ class Evilution::Baseline
     end
   end
 
-  def initialize(spec_resolver: Evilution::SpecResolver.new, timeout: 30, runner: nil, fallback_dir: "spec")
+  def initialize(spec_resolver: Evilution::SpecResolver.new, timeout: 30, runner: nil,
+                 fallback_dir: "spec", test_files: nil)
     @spec_resolver = spec_resolver
     @timeout = timeout
     @runner = runner
     @fallback_dir = fallback_dir
+    @test_files = test_files
   end
 
   def call(subjects)
     start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    spec_files = resolve_unique_spec_files(subjects)
+    spec_files = baseline_spec_files(subjects)
     failed = Set.new
 
     spec_files.each do |spec_file|
@@ -96,6 +98,17 @@ class Evilution::Baseline
 
   private
 
+  # When --spec was provided, run those files only. Auto-discovery is skipped
+  # entirely — the user has declared what covers their subjects and any
+  # mismatch between auto-discovery and their declaration is what produced
+  # the misleading "No matching test found" warning users have reported even
+  # while passing --spec.
+  def baseline_spec_files(subjects)
+    return Array(@test_files).uniq if @test_files && !@test_files.empty?
+
+    resolve_unique_spec_files(subjects)
+  end
+
   def resolve_unique_spec_files(subjects)
     warned = Set.new
     subjects.map do |s|