evilution 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 607074e45fead28ec35facc8fadadbb44e0dc6429ee00ef37edf92145bc4b7fc
-  data.tar.gz: 3bc840215dff4272ea6da9aad5ebed982827507f765c6cadc444bd1f3fb63ddc
+  metadata.gz: 34bc612e6537f856f98a6b1911989ddb89d5211bca426ebd1a08f8dddfe4eade
+  data.tar.gz: c6875ae71bb4092184df2c7a05f3efccca97a9db57c91c85e09f6bbf20c3c8d9
 SHA512:
-  metadata.gz: 5febff050f2670b2ab5f1cbeac9bfc41b0f30edc3e5ee39591036da0ef9ccf5d1273c0abe0cc828d289a959c2e135adb348980882a931d263df65e4b8a4e2299
-  data.tar.gz: 1f0d38cab915255ce1742350255cce291fd9c6e3bbdc649af778750089ca9b219c7f2553d1de40c6b2ac72b128310c56d7fff3ecc99ee2c14db42680dd0f3b2b
+  metadata.gz: 46d8c283c0fef3758c0369533a00a8db31337b263119d182133ad5d86d2dab7c2d60d2baa3ffcc53f87d7e605a84c880be2f9f9692a1bdef63642b670a50cb57
+  data.tar.gz: 7f492bfbff46d333d68e271b63b1ac10f1b9adf97a9d38a20f1255b77f3ada298ae92bad102a8835797432450130b179009129ce826a622a33b5346f9bfac58b

data/.beads/interactions.jsonl

@@ -310,3 +310,57 @@
 {"id":"int-2973ca4f","kind":"field_change","created_at":"2026-05-06T07:20:10.503854404Z","actor":"Denis Kiselev","issue_id":"EV-t2o9","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Obsolete: methods refactored on master (commit c6177ee). Rubocop ABC clean for these files."}}
 {"id":"int-523d3c8c","kind":"field_change","created_at":"2026-05-06T07:20:11.036667234Z","actor":"Denis Kiselev","issue_id":"EV-qtvs","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Obsolete: methods refactored on master (commit c6177ee). Rubocop ABC clean for these files."}}
 {"id":"int-be905e1b","kind":"field_change","created_at":"2026-05-06T07:20:11.472283074Z","actor":"Denis Kiselev","issue_id":"EV-psit","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Obsolete: methods refactored on master (commit c6177ee). Rubocop ABC clean for these files."}}
+{"id":"int-b2204b5b","kind":"field_change","created_at":"2026-05-06T07:59:55.142970285Z","actor":"Denis Kiselev","issue_id":"EV-inyq","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Already addressed upstream in v0.29.0 (rubocop ABC clean; tuple-return migrations landed in PRs #1094-#1102)."}}
+{"id":"int-20a87f61","kind":"field_change","created_at":"2026-05-06T07:59:55.620019557Z","actor":"Denis Kiselev","issue_id":"EV-bvwe","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Already addressed upstream in v0.29.0 (rubocop ABC clean; tuple-return migrations landed in PRs #1094-#1102)."}}
+{"id":"int-3b31029e","kind":"field_change","created_at":"2026-05-06T07:59:56.145819366Z","actor":"Denis Kiselev","issue_id":"EV-crru","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Already addressed upstream in v0.29.0 (rubocop ABC clean; tuple-return migrations landed in PRs #1094-#1102)."}}
+{"id":"int-af4d932d","kind":"field_change","created_at":"2026-05-06T07:59:55.93110283Z","actor":"Denis Kiselev","issue_id":"EV-0nep","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Already addressed upstream in v0.29.0 (rubocop ABC clean; tuple-return migrations landed in PRs #1094-#1102)."}}
+{"id":"int-a16fb04a","kind":"field_change","created_at":"2026-05-07T08:38:44.320058211Z","actor":"Denis Kiselev","issue_id":"EV-i5yp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"merged via PR #1163"}}
+{"id":"int-3571ab77","kind":"field_change","created_at":"2026-05-07T09:00:32.015564768Z","actor":"Denis Kiselev","issue_id":"EV-vtoe","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"merged"}}
+{"id":"int-59058caf","kind":"field_change","created_at":"2026-05-07T10:50:55.015519734Z","actor":"Denis Kiselev","issue_id":"EV-jmq4","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"merged"}}
+{"id":"int-3fb9d199","kind":"field_change","created_at":"2026-05-07T13:05:45.604108546Z","actor":"Denis Kiselev","issue_id":"EV-1l8z","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"merged"}}
+{"id":"int-3d3c2194","kind":"field_change","created_at":"2026-05-08T15:20:43.738723453Z","actor":"Denis Kiselev","issue_id":"EV-yyd8","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1175. Harness shipped: bin/evilution-self, script/build_runtime_snapshot, script/run_self_baseline, script/run_self_validation. All 10 originally-crashing dirs measurable. Follow-ups EV-9qh1/EV-u8n5/EV-2jex tracked separately."}}
+{"id":"int-9093e7db","kind":"field_change","created_at":"2026-05-08T18:03:23.097429903Z","actor":"Denis Kiselev","issue_id":"EV-9qh1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1180. Length-prefix marshal + polling waitpid loop in subject Isolation::Fork. Snapshot patch_runtime_protocol step removed (no longer needed). Spec coverage added for nested-fork pipe-EOF regression. Unblocks EV-u8n5."}}
+{"id":"int-9510ef73","kind":"field_change","created_at":"2026-05-08T18:24:44.05157246Z","actor":"Denis Kiselev","issue_id":"EV-u8n5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Resolved by EV-9qh1. Both acceptance bullets verified post-merge (parallel jobs=4 completes; self-mutation of fork.rb/worker.rb/baseline.rb succeeds). No new code needed beyond dropping the script/run_self_baseline skip list."}}
+{"id":"int-93b88ded","kind":"field_change","created_at":"2026-05-10T01:58:49.010521846Z","actor":"Denis Kiselev","issue_id":"EV-2jex","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged. Full self-mutation re-baseline recorded: 30657 muts, 22525 killed, 7672 survived, 0 timeouts, score 74.59% across all 20 lib/ subdirs. Numbers posted to EV-j2kz description + GH#1178."}}
+{"id":"int-e5511e59","kind":"field_change","created_at":"2026-05-10T03:05:25.311104857Z","actor":"Denis Kiselev","issue_id":"EV-pn5y","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1183. index_to_at now skips symbol/string keyed access (Hash-shape heuristic). Verified post-fix: in_process.rb self-mut produced 0 Hash.at NoMethodError, 250 measurable muts (was 260 with ~10 invalid Hash.at attempts)."}}
+{"id":"int-42aeec67","kind":"field_change","created_at":"2026-05-10T04:26:08.578561775Z","actor":"Denis Kiselev","issue_id":"EV-s5br","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1184. 6 delegating accessors on MutationResult swapped from nil? checks to is_a?(ExpectedClass) guards. Verified: self-mut of subject mutation_result.rb produced 0 'undefined method ... for false' crashes (235 muts, 177 killed, exit 0)."}}
+{"id":"int-c6021b93","kind":"field_change","created_at":"2026-05-10T19:05:56.88581869Z","actor":"Denis Kiselev","issue_id":"EV-t7kh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1185. Minimal verbosity now surfaces a trimmed errors sample (first 3 entries × 5-line backtrace head + key fields) when errors>0; absent when errors=0. Tool description + README updated. Unblocks paired EV-187j (default-verbosity token caps) and agent-driven debugging on partly-broken runs."}}
+{"id":"int-96158302","kind":"field_change","created_at":"2026-05-11T03:15:27.20532545Z","actor":"Denis Kiselev","issue_id":"EV-187j","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1186. Summary verbosity now strips diff + error_backtrace from timed_out/errors/unresolved entries; error_message preserved. 100-error synthetic payload measured <50KB. Tool description + README updated. Pairs with EV-t7kh — together unblock agent-driven debugging at scale."}}
+{"id":"int-f7afa606","kind":"field_change","created_at":"2026-05-11T05:14:25.551359428Z","actor":"Denis Kiselev","issue_id":"EV-nrgw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1187. Reframed scope: bead's stale-cache hypothesis didn't reproduce — Evilution::Cache is content-addressed via SHA(file_source), so source changes invalidate correctly. Real silent-failure mode: score = killed / (total - errors - neutral - equivalent - unresolved - unparseable), so high error rates produce 'PASS 100%' that masks 16/19 errored. Fix: ErrorRateWarning line formatter prints '! High error rate: N/T (X%)' under the Score line when errors / total > 25%. Verified with Dry::Struct repro (10/11 errored → warning surfaces under misleading 100% score)."}}
+{"id":"int-1f633a18","kind":"field_change","created_at":"2026-05-11T05:44:28.177265737Z","actor":"Denis Kiselev","issue_id":"EV-a43i","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented explicit preload fallthrough: missing config.preload under :fork+rails warns to stderr and falls through to auto-detect chain; combined error lists both missing explicit + chain candidates when chain also empty. PR #1188 merged."}}
+{"id":"int-13cc794a","kind":"field_change","created_at":"2026-05-11T06:16:58.805696639Z","actor":"Denis Kiselev","issue_id":"EV-corn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented option (a): added 'mutate' as run alias in CommandExtractor (RUN_ALIASES). Updated CLI --help banner, README CLI table, and MCP tool description (with [files...] placeholder). PR #1189 merged. GH #1172."}}
+{"id":"int-980f1e21","kind":"field_change","created_at":"2026-05-11T18:16:52.733542472Z","actor":"Denis Kiselev","issue_id":"EV-kjkd","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"probe only"}}
+{"id":"int-90d90758","kind":"field_change","created_at":"2026-05-12T01:35:59.390842791Z","actor":"Denis Kiselev","issue_id":"EV-hmd5","extra":{"field":"status","new_value":"open","old_value":"in_progress"}}
+{"id":"int-9426e0f2","kind":"field_change","created_at":"2026-05-12T09:22:16.445201172Z","actor":"Denis Kiselev","issue_id":"EV-99r2","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"dry-monads canary complete: 3 surfaced bugs (EV-174x #1197, EV-wwx3 #1198, EV-wzmq #1199) all merged; post-merge canary 385/246/0/0 score 1.0"}}
+{"id":"int-89a6abbb","kind":"field_change","created_at":"2026-05-12T09:38:41.132122586Z","actor":"Denis Kiselev","issue_id":"EV-hmd5","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"dry-types canary complete: 3 mutator output bugs filed (EV-2cv1 #1200, EV-nmhi #1201, EV-jjpt #1202); zero evilution crashes; score 0.79"}}
+{"id":"int-7daa2e34","kind":"field_change","created_at":"2026-05-12T09:49:30.104392229Z","actor":"Denis Kiselev","issue_id":"EV-3xxc","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"pundit canary clean: 800 mutations / 789 killed / 0 errors / score 1.0; 2 new mutator bugs filed (EV-bjot, EV-xsg2)"}}
+{"id":"int-dfdf0230","kind":"field_change","created_at":"2026-05-12T09:56:50.344492509Z","actor":"Denis Kiselev","issue_id":"EV-mw2h","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"dotenv canary complete: 984/624 killed score 0.66; 3 evilution bugs filed (EV-b0ee preload, EV-kws8 + EV-xsg2 sighting mutator); 31 NameErrors are gem-side missing require, not evilution"}}
+{"id":"int-3bf7bd77","kind":"field_change","created_at":"2026-05-12T10:12:38.509609431Z","actor":"Denis Kiselev","issue_id":"EV-o5p5","extra":{"field":"status","new_value":"blocked","old_value":"in_progress"}}
+{"id":"int-2fcc28b2","kind":"field_change","created_at":"2026-05-12T13:55:33.618634552Z","actor":"Denis Kiselev","issue_id":"EV-ui96","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"thor canary clean: 517/359 killed score 0.70; zero evilution bugs; survivors are thor test gaps"}}
+{"id":"int-a2ec0eeb","kind":"field_change","created_at":"2026-05-12T14:05:07.302733558Z","actor":"Denis Kiselev","issue_id":"EV-lnjm","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Recursion stress canary passed (score 0.8768, 0 evilution bugs)"}}
+{"id":"int-f2e146f0","kind":"field_change","created_at":"2026-05-12T14:17:32.642381092Z","actor":"Denis Kiselev","issue_id":"EV-4i26","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"IO/HTTP canary passed (score 0.6361, 0 new bugs, 5 known EV-xsg2 sightings appended)"}}
+{"id":"int-66c73ae9","kind":"field_change","created_at":"2026-05-12T14:27:33.553239753Z","actor":"Denis Kiselev","issue_id":"EV-jm43","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"AST canary done: pass_with_blocking_bug. 1 new evilution bug (EV-l19q heredoc neutralizer), 2 existing bugs (EV-bjot, EV-wzmq) appended/reopened"}}
+{"id":"int-2e92815c","kind":"field_change","created_at":"2026-05-12T15:01:03.20238706Z","actor":"Denis Kiselev","issue_id":"EV-l19q","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via GH#1209 (PR for GH#1208). BodyCallNeutralizer now extends replacement range past heredoc terminators."}}
+{"id":"int-908402ad","kind":"field_change","created_at":"2026-05-12T16:03:48.265773859Z","actor":"Denis Kiselev","issue_id":"EV-xpfi","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Rails canary pass (yaml+config smoke clean, 0 evilution bugs)"}}
+{"id":"int-ff8e85b2","kind":"field_change","created_at":"2026-05-12T17:03:40.966592538Z","actor":"Denis Kiselev","issue_id":"EV-l6gx","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1210 (GH#1207). Minitest 6.x + 5.x compatibility restored. Unblocks 9 canaries."}}
+{"id":"int-5b7b8149","kind":"field_change","created_at":"2026-05-12T17:57:03.394930914Z","actor":"Denis Kiselev","issue_id":"EV-o5p5","extra":{"field":"status","new_value":"closed","old_value":"blocked","reason":"EV-l6gx fix verified; new follow-up EV-blnq filed for fork-isolation hang. Direct integration probe confirms Minitest works."}}
+{"id":"int-0dfac9d1","kind":"field_change","created_at":"2026-05-13T01:38:31.908382613Z","actor":"Denis Kiselev","issue_id":"EV-70hd","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-7616b8d5","kind":"field_change","created_at":"2026-05-13T01:40:01.770243671Z","actor":"Denis Kiselev","issue_id":"EV-aati","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"roda canary complete: score 1.0 (0 survivors), 1 new HIGH bug filed (EV-70hd #1212 BodyCallNeutralizer lazy-load), 4 mutator bug sightings appended (nmhi/xsg2/bjot/kws8). 32724 mutations / 30273 killed / 0 survived."}}
+{"id":"int-05b998b4","kind":"field_change","created_at":"2026-05-13T01:58:27.852827156Z","actor":"Denis Kiselev","issue_id":"EV-720r","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-a323a995","kind":"field_change","created_at":"2026-05-13T02:49:22.801975686Z","actor":"Denis Kiselev","issue_id":"EV-lqpn","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-49c2877f","kind":"field_change","created_at":"2026-05-13T02:49:23.250796095Z","actor":"Denis Kiselev","issue_id":"EV-05tp","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-1db1cd93","kind":"field_change","created_at":"2026-05-13T02:50:33.4238377Z","actor":"Denis Kiselev","issue_id":"EV-ien5","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"sinatra canary complete: 1 new HIGH bug filed (EV-lqpn #1214 TypeError superclass mismatch on Struct.new superclass — 6782 errors blocking 92% of base.rb mutations, score 0.0); 1 new LOW bug (EV-05tp #1215 explicit_super dangling comma); 3 mutator bug sightings appended (xsg2/kws8/bjot)"}}
+{"id":"int-6b08fe75","kind":"field_change","created_at":"2026-05-13T02:54:40.126050522Z","actor":"Denis Kiselev","issue_id":"EV-n3au","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-78d79b10","kind":"field_change","created_at":"2026-05-13T02:54:40.58615495Z","actor":"Denis Kiselev","issue_id":"EV-74e3","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-5f3c2a62","kind":"field_change","created_at":"2026-05-13T02:54:41.035195233Z","actor":"Denis Kiselev","issue_id":"EV-m47s","extra":{"field":"assignee","new_value":"Denis Kiselev","old_value":""}}
+{"id":"int-a891f124","kind":"field_change","created_at":"2026-05-13T16:10:07.942340376Z","actor":"Denis Kiselev","issue_id":"EV-wzmq","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"PR #1221 merged: widened adjacent_string_concat? to detect mixed plain+interp adjacent (line-continued + same-line). Predicate tightened per Copilot review to require StringNode/InterpolatedStringNode type AND own opening_loc, rejecting pure-interpolation EmbeddedStatementsNode parts. 3649 specs pass."}}
+{"id":"int-5243c70e","kind":"field_change","created_at":"2026-05-13T16:46:03.689538886Z","actor":"Denis Kiselev","issue_id":"EV-2cv1","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR #1222 merged: skip block_param_removal when anonymous & param + body forwards via &. Per Copilot review, walker stops at nested DefNode boundary."}}
+{"id":"int-77c3d7b0","kind":"field_change","created_at":"2026-05-13T17:00:36.3309915Z","actor":"Denis Kiselev","issue_id":"EV-nmhi","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR merged: string_literal skips StringNode chunks of InterpolatedSymbolNode / InterpolatedRegularExpressionNode / InterpolatedXStringNode. Chunks are not standalone literals."}}
+{"id":"int-205e0413","kind":"field_change","created_at":"2026-05-14T04:35:40.188276228Z","actor":"Denis Kiselev","issue_id":"EV-n3au","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR #1224 merged: MCP preload param + setup_warning heuristic. Copilot review addressed (schema oneOf, mutations vs workers wording)."}}
+{"id":"int-0f60034f","kind":"field_change","created_at":"2026-05-14T05:36:59.692727916Z","actor":"Denis Kiselev","issue_id":"EV-xsg2","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR #1225 merged: receiver_replacement skips reserved-keyword method names. Per Copilot review, writer suffix (=) stripped before keyword lookup to cover self.class= form."}}
+{"id":"int-f7e471ae","kind":"field_change","created_at":"2026-05-14T06:18:02.455563481Z","actor":"Denis Kiselev","issue_id":"EV-bjot","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR #1226 merged: centralized HeredocSpan extension in Mutator::Base.add_mutation. Per Copilot review, skip-heuristic tightened to regex matching heredoc-anchor identifier pattern (not bare <<). Covers 8 operators via single infrastructure fix."}}
+{"id":"int-3871825c","kind":"field_change","created_at":"2026-05-14T06:57:02.232644676Z","actor":"Denis Kiselev","issue_id":"EV-kws8","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR #1228 merged: rescue_removal walks BeginNode + uses structural clause boundaries. Covers orphan-else and orphan-rescue-class variants. Copilot review evaluated and rejected (end_keyword_loc is populated for implicit-begin shapes, no NoMethodError path)."}}
+{"id":"int-f2bc98ca","kind":"field_change","created_at":"2026-05-14T07:13:14.206329238Z","actor":"Denis Kiselev","issue_id":"EV-jjpt","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR merged: splat_operator skips kwarg-preceded **splat to avoid positional-after-keyword."}}
+{"id":"int-78870411","kind":"field_change","created_at":"2026-05-14T07:28:17.94685909Z","actor":"Denis Kiselev","issue_id":"EV-05tp","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR merged: explicit_super_mutation extends byte range structurally (block start / rparen / args end). Short-circuit spec switched to synthetic in-test operator."}}
+{"id":"int-36e5c972","kind":"field_change","created_at":"2026-05-14T08:23:06.045690955Z","actor":"Denis Kiselev","issue_id":"EV-b0ee","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"PR merged: GemDetector multi-gemspec disambiguation via exact-entry, lib-subdir, then shortest-name fallback."}}
+{"id":"int-00368bf4","kind":"field_change","created_at":"2026-05-14T09:07:21.14041556Z","actor":"Denis Kiselev","issue_id":"EV-blnq","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Not a hang — slow run with no progress feedback. Investigated 2026-05-14: 269 mutations / 202 killed / 42 survived / 25 timed_out / 0 errors / score 0.75 in 4min with -j 4 -t 10 on Shopify/liquid v5.12.0. Per-mutation Minitest test_helper re-bootstrap + 25 worker timeouts caused the perceived 10-min hang. Combined with --no-progress + non-TTY stderr (no parent output) the run looks silent until the JSON dump. Worker logs (--quiet-children --quiet-children-dir DIR) show steady progress. README updated with a 'Long Minitest fork runs — not a hang' section under §7 explaining the timing math + recommended -j/-t flags. No code change needed."}}

data/.rubocop_todo.yml

@@ -4,3 +4,10 @@
 Metrics/AbcSize:
   Exclude:
     - "lib/evilution/runner.rb"
+    - "lib/evilution/isolation/fork.rb"
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/evilution/isolation/fork.rb"
+    - "lib/evilution/integration/minitest.rb"
+    - "lib/evilution/mcp/mutate_tool.rb"

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+Versioning policy: see [docs/versioning.md](docs/versioning.md).
+
+## [0.30.0] - 2026-05-15
+
+### Added
+
+- **Two new mutation operators bring the default registry to 74** — `LastExpressionRemoval` strips a trailing literal (`true`/`false`/`nil`/integer/symbol) from a method body, targeting the idiomatic `def predicate?; side_effect; true; end` pattern where the explicit literal return value is the high-signal behavior under test (EV-74e3, PR #1236). `ArgumentMethodCallReplacement` drops a method call appearing in argument position (`fn(x.attr)` → `fn(x)`, also inside hash values, array elements, and keyword arguments), surfacing the common log-payload / structured-data substitution pattern under its own operator name instead of buried under `method_call_removal` (EV-m47s, PR #1237)
+- **`MutationPlanner` now deduplicates byte-identical mutations across operators** — key is `(file_path, mutated_source)`; first-registered operator wins. Eliminates wasted compute and inflated denominators when multiple operators produce the same edit (e.g. `statement_deletion` + `last_expression_removal` both deleting a trailing literal). `DeadCode` equivalence heuristic widened to recognize `last_expression_removal` so unreachable trailing literals retain equivalent-classification regardless of which operator name survives dedup (PR #1236 and follow-up review)
+- **`BodyCallNeutralizer`: strip non-idempotent class/module body calls before re-eval in fork workers** — DSL registries (`register_mixin`, plugin registration, etc.) raise on second invocation because they assume single-eval semantics. The parent's preload already executed them; re-running them in the child fork is wasted work that aborts the eval before the mutated method takes effect. The neutralizer walks the Prism tree, replaces non-allowlisted top-level call statements with `nil` byte-for-byte, and extends the replacement range to cover heredoc bodies and terminators. Lazy-load-aware: a `$LOADED_FEATURES` snapshot taken at parent preload-end gates neutralization on whether the target file was actually preloaded — first-load-in-child files (e.g. roda's `lib/roda/plugins/typecast_params.rb`) are left intact so subsequent statements depending on those DSL-defined methods do not cascade `NameError` (#1195, EV-70hd PR #1232)
+- **Setup-warning subsystem surfaces silent mutation failures** — when ≥80% of mutations error with ≥80% of those errors sharing a single error class, the warning formatter emits a class-specific hint (`NameError` → preload pointer; `LoadError` → require path; etc.) telling the user the run's numbers are unreliable and where to look. Wired into the CLI text reporter; visible in MCP `evilution-mutate` output too (#1216, #1168)
+- **`mutate` CLI alias for `run`** — `evilution mutate path/foo.rb` is now equivalent to `evilution run path/foo.rb`; matches the `gem` name users reach for first (#1172)
+- **`--preload PATH` flag with explicit fallback + error surface** — supersedes implicit autoloading. Resolves the path with explicit error messages when the file is missing or unreadable; falls back to the inferred convention only when explicitly opted in. MCP option parser accepts boolean `false` to disable preload entirely (#1171)
+- **Method splicing for live method redefinition (`Evilution::Mutator::Splice`)** — supports method-level swaps in workers that previously required full source re-eval. Plumbed alongside the existing source-evaluator strategy (#1194)
+- **Fork-protocol length-prefixed payloads** — replaces the ad-hoc line-terminated protocol that could hang when payload contents contained newlines. Worker self-baseline script can now use multiple jobs safely; the previous skip list for fork-using files was removed (#1176, #1177, #1178)
+- **MCP / session / config schema versioning** — MCP tool envelopes carry `Evilution::MCP::CONTRACT_VERSION` (currently `1`); session JSON files declare a `schema_version`; configuration files (`.evilution.yml`) validated against a versioned schema. Forward compatibility now follows a documented policy (#856, #857, #858)
+- **`docs/versioning.md`** — explicit policy on what counts as the public contract, what triggers a major bump, and how deprecations work. Linked from the top of `CHANGELOG.md` and the `## Versioning` section of `README.md` (#864)
+- **Dual-runtime harness scripts for self-mutation testing** — run evilution's own suite against mutated evilution code in a separate Ruby process, isolating bootstrap effects (#1175)
+
+### Fixed
+
+- **Mutation scoring no longer silently inflates kills when RSpec returns nonzero with zero examples loaded** — `Baseline` now accepts `test_files:` and honors `--spec` at the baseline phase (previously the `--spec` flag was only consulted at mutation time, so the misleading "No matching test found... Use --spec to specify the test file" warning fired even when the user *did* pass `--spec`). `Integration::RSpec#execute_run` captures `RSpec.world.example_count` after the run; if the status is nonzero and zero examples loaded, `ResultBuilder#from_run` returns an explicit error hash so `classify_status` reports `:error` instead of falling through to `:killed`. Without this, environments with `fail_if_no_examples = true`, autoload mismatches, or spec-file load failures would mark every mutation as killed regardless of whether any example ran (EV-720r, PR #1234)
+- **`class X < Struct.new(...)` (or `Data.define`, dynamic `Class.new`) no longer crashes the eval with `TypeError: superclass mismatch`** — `RedefinitionRecovery` now handles `TypeError` for messages containing "superclass mismatch": strips the constants the source declares (same path as the existing `ArgumentError 'already defined'` recovery) and retries once. If the retry still raises, the mutation reports `:error` rather than being silently miscounted as survived. Unblocks sinatra's `lib/sinatra/base.rb` and similar Rack-middleware-style anonymous-parent class patterns (EV-lqpn, PR #1235)
+- **Gem detector now disambiguates multiple gemspecs in a single root** — when a repository ships e.g. `dotenv.gemspec` alongside `dotenv-rails.gemspec`, the previous `Dir.glob.first` was filesystem-order-dependent and often picked the wrong companion gem, triggering `uninitialized constant Rails` at preload. New three-tier resolution: exact-entry match against the target's `lib/foo.rb` path, then first-lib-subdirectory match, then the shortest gemspec basename as the conventional "parent" gem (EV-b0ee, PR #1224)
+- **Heredoc-body orphaning across mutation operators centralized in `Evilution::AST::HeredocSpan`** — operators whose byte edit straddles a `<<~MARKER` anchor (argument_removal, argument_nil_substitution, method_call_removal, statement_deletion, method_body_replacement, block_removal, conditional_branch, string_interpolation, etc.) previously emitted unparseable mutations whenever the kept range included the heredoc opener without its body/terminator. `Mutator::Base#add_mutation` now extends the byte range via a single shared visitor; when the replacement itself re-references a heredoc anchor, the mutation is skipped rather than emitted as broken bytes (EV-bjot, PR #1223)
+- **`receiver_replacement` skips reserved-keyword method names** — replacing `obj.if` (where `if` is the method name spelled as a Ruby keyword) with bare `if` produced unparseable Ruby. The operator now strips writer-form `=` suffixes and bails out when the candidate is a Ruby reserved keyword (EV-xsg2, PR #1222)
+- **`rescue_removal` removes the orphan `else` clause when stripping the sole `rescue`** — `begin; ...; rescue Foo; ...; else; ...; end` with the rescue clause removed previously left a dangling `else` without a matching `rescue`, which is invalid Ruby. The operator now visits `BeginNode` directly and computes structural clause boundaries, dropping orphan else atoms (EV-kws8, PR #1221)
+- **`explicit_super` "remove all args" trims the dangling comma** — `super(a, b)` → `super()` was correctly handled; `super(a, b,)` → `super(,)` was not. The trailing-args boundary now walks block-start / rparen / args-end so the resulting `super` is always parseable (EV-05tp, PR #1230)
+- **`positional-after-keyword` syntax error in argument removal** — eliminated cases where positional arg removal left a kwarg followed by a positional in the result, which Ruby rejects (#1202)
+- **Interpolated-node string parts no longer crash mutators on non-string segments** — `visit_interpolated_symbol_node` / `visit_interpolated_regular_expression_node` / `visit_interpolated_x_string_node` now skip embedded StringNode parts instead of treating them as standalone string literals (EV-nmhi, #1201)
+- **`block_param_removal` anonymous-forward safety check** — body uses of `&` / `*` / `**` previously crashed when the corresponding block-param was removed. The operator now scans the body for anonymous forwards before deciding to remove (EV-2cv1, #1200)
+- **`string_literal` adjacent-string concatenation handled** — Ruby implicitly concatenates adjacent string literals at parse time; mutating one half could leave a syntactically wrong fragment. The operator now detects adjacent quoted literals via Prism's part-type predicates and `opening_loc`, and skips when the result would be unparseable (#1220)
+- **`string_literal` backslash-continuation handling** — multi-line literals joined by trailing `\` survived mutation as half-statements; now correctly span the continuation range (#1196)
+- **`BodyCallNeutralizer` heredoc handling preserves parseable output** — when a neutralized call carried a heredoc argument, the replacement-range collector now walks every variant of interpolated-string / x-string / interpolated-symbol / regex with a `heredoc?` predicate and extends the end offset to the heredoc terminator's line (#1208)
+- **Minitest version compatibility (Minitest 6 removed `__run`)** — `Integration::Minitest` now dispatches to the correct runner method based on the installed Minitest version; integration spec updated to assert the dispatch contract without `NoMethodError` regressions (#1207)
+- **Nil-replacement crash in parallel cleanup accessors** — pool teardown could call accessors on partially-initialized worker state; nil-guards added in the affected paths (#1174)
+- **`indexable?` skips symbol/string keys** — the index-conversion operators no longer attempt receiver mutation on call sites whose argument is itself a symbol/string literal (the receiver is necessarily indexable in those cases; the mutation produced no new signal) (#1173)
+- **Error rate warning formatter wired into text reporter** — high error rates now produce a visible single-line warning before the mutations breakdown (#1168)
+
+### Changed
+
+- **MCP `evilution-mutate` default verbosity tightened to fit agent token caps** — minimal verbosity reports only the high-signal slice (summary + survived); full verbosity audited for unresolved-diffs leaks. Error sampling at minimal verbosity (cap per error class) prevents deadlock when thousands of mutations fail with the same exception (#1169, #1170, EV-r1tt)
+
 ## [0.29.0] - 2026-05-06
 
 ### Changed

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.