evilution 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8f4aa7633e70e4a54aded76fcdfeb152cb4e4ad76d587b5aa0c93bda96246e3
-  data.tar.gz: b8e65e5d0837b6873c31e6cae9621160a2a6fe75b3949d08a39f91b3df7db60b
+  metadata.gz: cc78bc7bc68c4d25a6b260b62a83a304d617905187e0b06ca6d0bc050be86403
+  data.tar.gz: 0a98e06dfc6ee9c4f0830b5a85346a95bf8de07d6aa9f3c49326077f7e2a8d44
 SHA512:
-  metadata.gz: 923d8fa302a830d1b070e27b2494c5ec3227f6c6188b26f1701a0344e54ac230626a75bd4f0ec70d6e4f10af04e5e62d04b05d93c067ee160ce3c653e86faaf6
-  data.tar.gz: f63389c729c4d121cb24a38a2bd9bd4d386707f81c16dbfd106868e952d72200278cd84fc0936ad60e666e53b5c51efce7d40a615c093d5fc327e1e910a39fd4
+  metadata.gz: a8d67fc09591e0bee7395498d41c347aa907bd061831ef2ff83765bb0f143f577b8070b217193ffcfe23bff2a221b85f23b644cb15f3732f9aaf0069c6e369b1
+  data.tar.gz: c13839cac96e37075a5f2fa4cd82d2d2ca8116ef058d3ad8cbca6b4716bb0239d4e60553100d7c1d36fb05205deb0415b5f91a855319cd55a979fcad49736ec4

data/.beads/.gitignore

@@ -42,8 +42,12 @@ export-state/
 
 # Dolt database (managed by Dolt remotes, not git)
 dolt/
+embeddeddolt/
 dolt-access.lock
 
+# Local backup data
+backup/
+
 # NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
 # They would override fork protection in .git/info/exclude, allowing
 # contributors to accidentally commit upstream issue databases.

data/.beads/interactions.jsonl

@@ -0,0 +1,12 @@
+{"id":"int-4aac1fda","kind":"field_change","created_at":"2026-04-09T05:02:19.518389279Z","actor":"Denis Kiselev","issue_id":"EV-230","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
+{"id":"int-ff9e26c4","kind":"field_change","created_at":"2026-04-09T05:38:57.721818299Z","actor":"Denis Kiselev","issue_id":"EV-230","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged PR #622. RegexSimplification operator with quantifier removal, anchor removal, and character class range removal."}}
+{"id":"int-c318b162","kind":"field_change","created_at":"2026-04-09T06:16:18.67347839Z","actor":"Denis Kiselev","issue_id":"EV-78","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-e2f93b8b","kind":"field_change","created_at":"2026-04-09T06:33:11.389955517Z","actor":"Denis Kiselev","issue_id":"EV-82","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-275fe056","kind":"field_change","created_at":"2026-04-09T06:49:54.009377447Z","actor":"Denis Kiselev","issue_id":"EV-80","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-f1854a23","kind":"field_change","created_at":"2026-04-09T07:52:38.321185191Z","actor":"Denis Kiselev","issue_id":"EV-79","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-d2e4b659","kind":"field_change","created_at":"2026-04-09T08:28:47.700848334Z","actor":"Denis Kiselev","issue_id":"EV-81","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-f2a8e3fa","kind":"field_change","created_at":"2026-04-09T11:39:20.111111433Z","actor":"Denis Kiselev","issue_id":"EV-83","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-41c232c2","kind":"field_change","created_at":"2026-04-09T12:51:12.16692591Z","actor":"Denis Kiselev","issue_id":"EV-84","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-0f073191","kind":"field_change","created_at":"2026-04-09T13:03:11.468115004Z","actor":"Denis Kiselev","issue_id":"EV-85","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-91a9616c","kind":"field_change","created_at":"2026-04-09T13:04:05.459458165Z","actor":"Denis Kiselev","issue_id":"EV-69","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-b4fe2b7b","kind":"field_change","created_at":"2026-04-09T13:42:59.996305852Z","actor":"Denis Kiselev","issue_id":"EV-277","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}

data/.beads/issues.jsonl

@@ -170,7 +170,7 @@
 {"id":"EV-228","title":"Equivalent detection: .count → .length as always-equivalent","description":".count → .length mutations are universally unkillable (both return identical integer results). Evilution should detect this pattern and classify as equivalent automatically. Reported in feedback for HomeController stats block.","notes":"GH #509","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:43.587875972+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T08:52:50.669215278+07:00","closed_at":"2026-04-08T08:52:50.669215278+07:00","close_reason":"Closed"}
 {"id":"EV-229","title":"Equivalent detection: .each → .map in void context","description":"When .each is called in void context (return value not assigned or passed), replacing with .map or .reverse_each produces equivalent behavior. Evilution should detect void-context method calls and mark these swaps as likely-equivalent. Reported for Avo reset_password action.","notes":"GH #511","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:46.8330208+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T09:31:47.874981801+07:00","closed_at":"2026-04-08T09:31:47.874981801+07:00","close_reason":"Closed"}
 {"id":"EV-23","title":"Per-mutation spec targeting","description":"Instead of running the full spec suite for every mutation, map each mutated source file to its relevant spec file(s) using convention-based resolution (e.g. lib/foo/bar.rb -> spec/foo/bar_spec.rb) and only run those. This dramatically reduces per-mutation test time. Depends on convention-based spec file resolution being implemented first.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:28.98620973+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T14:49:13.616876819+07:00","closed_at":"2026-03-16T14:49:13.616876819+07:00","close_reason":"Fixed and merged","dependencies":[{"issue_id":"EV-23","depends_on_id":"EV-34","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-230","title":"Regex simplification operators","description":"Add mutation operators for regex patterns: /\\s+/ → /\\s/ (remove quantifier), remove anchors (^, $, \\A, \\z), simplify character classes. Mutant's regex mutations caught real test gaps (case sensitivity, whitespace handling) that evilution missed. Reported in 2 sessions on Telegram::NewsScorer.","notes":"GH #514","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:48.930372762+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:22:57.239710634+07:00","dependencies":[{"issue_id":"EV-230","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-230","title":"Regex simplification operators","description":"Add mutation operators for regex patterns: /\\s+/ → /\\s/ (remove quantifier), remove anchors (^, $, \\A, \\z), simplify character classes. Mutant's regex mutations caught real test gaps (case sensitivity, whitespace handling) that evilution missed. Reported in 2 sessions on Telegram::NewsScorer.","notes":"GH #514","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:48.930372762+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:22:57.239710634+07:00"}
 {"id":"EV-231","title":".downcase removal operator","description":"Add mutation that removes .downcase calls. This caught real case-sensitivity test gaps in mutant that evilution missed. Useful for testing that code handles mixed-case input. Reported in 2 sessions on NewsScorer.","notes":"GH #516","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:50.682791593+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T09:42:19.793202916+07:00","closed_at":"2026-04-08T09:42:19.793202916+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-231","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-232","title":"Method chain permutation operators (strip → lstrip/rstrip)","description":"Add mutations that replace string cleaning methods with partial variants: strip → lstrip/rstrip, chomp → chop, etc. Mutant's chain permutations caught a real test gap in NewsScorer keyword processing. Reported in 1 session.","notes":"GH #518","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:52.982750285+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T11:15:28.398677068+07:00","closed_at":"2026-04-08T11:15:28.398677068+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-232","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-233","title":"Related specs heuristic (run association specs when .includes() mutated)","description":"When mutations remove .includes() eager loading calls, the matching unit spec may not catch N+1 regressions. Consider a heuristic that also runs specs for the included associations or integration specs. Would complement the spec auto-detection feature. Reported in 1 session for NewsController.","notes":"GH #519","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:21:56.302076763+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T12:16:09.453069408+07:00","closed_at":"2026-04-08T12:16:09.453069408+07:00","close_reason":"Closed"}
@@ -178,22 +178,22 @@
 {"id":"EV-235","title":"Bug: Non-deterministic mutation count on same file","description":"Running evilution twice on the same file (HelpController, 9 LOC) produced different mutation counts (18 vs 15). Unclear cause — possibly non-deterministic operator selection or file state difference. Low priority but should be investigated. Reported once in v0.12.0.","notes":"GitHub: #512","status":"closed","priority":4,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:01.930671333+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T13:20:37.135440498+07:00","closed_at":"2026-04-04T13:20:37.135440498+07:00","close_reason":"Not a bug. The 18 vs 15 difference was exactly the 3 timed-out mutations — counted in run 1 total but excluded in run 2 summary. Mutation generation is fully deterministic (no rand/shuffle/sample in codepath). Reported once in v0.12.0, never reproduced. Reporting has been significantly improved since then."}
 {"id":"EV-236","title":"--spec-dir flag for directory-level spec inclusion","description":"Add a --spec-dir flag that auto-includes all specs in a directory, reducing the chance of missing coverage from adjacent spec files. Useful when a controller has tests split across spec/requests/, spec/controllers/, and spec/features/. Reported once.","notes":"GitHub: #513","status":"closed","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:04.618160285+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-07T09:55:50.99913701+07:00","closed_at":"2026-04-07T09:55:50.99913701+07:00","close_reason":"--spec-dir CLI flag implemented, composes with --spec, validates directory existence. 3 unit tests passing. Merged via GH #513.","dependencies":[{"issue_id":"EV-236","depends_on_id":"EV-227","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-237","title":"Temp-file based mutation (don't modify original source)","description":"Evilution mutates source files in-place on the filesystem, which triggers file watchers, linters, and IDE notifications during runs. Even with the ensure-based restore (fixed earlier), race conditions exist if the process is killed. Write mutated source to a tempfile and point the test runner at it via load path manipulation. Never modify the original source file. Reported in 2 sessions (v0.16.1).","notes":"GH issue: #520 (https://github.com/marinazzio/evilution/issues/520)","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:06.770551806+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:52:59.896531797+07:00","closed_at":"2026-04-08T15:52:59.896531797+07:00","close_reason":"Closed","external_ref":"gh-520","labels":["reliability"]}
-{"id":"EV-238","title":"Epic: Research mutation density gap with mutant","description":"Evilution consistently generates 1.8-2.6x fewer mutations than mutant across 25 feedback sessions. While some of mutant's extras are equivalent ([]→fetch, to_i→Integer()), many catch real edge cases. This epic covers: (1) Audit mutant's operator list systematically against evilution's 54 operators, (2) Identify which missing operators catch real bugs vs produce noise, (3) Prioritize operator additions by signal-to-noise ratio, (4) Target closing the gap to <1.5x. Related: existing gap analysis created 15 new operator issues (EV-214 through EV-224, #491-#505).","notes":"GitHub: #515","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:11.095318733+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:22:55.790159971+07:00"}
+{"id":"EV-238","title":"Epic: Research mutation density gap with mutant","description":"Evilution consistently generates 1.8-2.6x fewer mutations than mutant across 25 feedback sessions. While some of mutant's extras are equivalent ([]→fetch, to_i→Integer()), many catch real edge cases. This epic covers: (1) Audit mutant's operator list systematically against evilution's 54 operators, (2) Identify which missing operators catch real bugs vs produce noise, (3) Prioritize operator additions by signal-to-noise ratio, (4) Target closing the gap to <1.5x. Related: existing gap analysis created 15 new operator issues (EV-214 through EV-224, #491-#505).","notes":"GitHub: #515","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:11.095318733+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T10:41:04.310878722+07:00","closed_at":"2026-04-09T10:41:04.310878722+07:00","close_reason":"Closed"}
 {"id":"EV-239","title":"Epic: Research and fix high memory baseline","description":"Evilution's memory baseline is 718+ MB even for tiny files in v0.18.0 sessions, and grows across consecutive runs in the same session (718→763→795→800 MB). Previous fixes addressed AST node retention and StringIO leaks but baseline remains high. Mutant peaks at ~200 MB for comparable workloads. This epic covers: (1) Profile memory allocation during boot/setup phase, (2) Identify what's consuming the 718 MB baseline, (3) Investigate cross-run memory growth (session-level leak?), (4) Target bringing baseline under 300 MB. Related: existing rake memory:check infrastructure exists.","notes":"GitHub: #517","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:16.602817355+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T00:16:38.665740136+07:00","closed_at":"2026-04-06T00:16:38.665740136+07:00","close_reason":"Premise invalid: 718 MB baseline was the MCP host process, not evilution. Standalone evilution baseline is ~30 MB (confirmed via EV-242/245/246 profiling). No memory fix needed. Sub-issues resolved: EV-242 (30 MB boot baseline), EV-243 (single mutation profiled), EV-245 (no cross-run growth), EV-246 (fork has zero parent-side cost), EV-247 (RSS tracking added)."}
 {"id":"EV-24","title":"Epic: JSON Output Improvements","description":"Make JSON output fully machine-parseable in all scenarios, including errors. Add diagnostic fields that help agents debug failures.","status":"closed","priority":1,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:37.450686472+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T11:15:24.900944562+07:00","closed_at":"2026-03-16T11:15:24.900944562+07:00","close_reason":"All children complete: structured errors, test_command in JSON, noise suppression","dependencies":[{"issue_id":"EV-24","depends_on_id":"EV-25","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-24","depends_on_id":"EV-26","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-24","depends_on_id":"EV-40","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-240","title":"Neutral mutation category (test errors vs test failures)","description":"Add a 'neutral' classification for mutations where tests error (crash/exception) rather than fail (assertion). This helps users distinguish test infrastructure problems from real coverage gaps. Mutant has this distinction and it's valuable — e.g., killfork 403 errors in vanilla-mafia are infrastructure noise, not coverage gaps. Currently evilution has neutral detection implemented but feedback suggests it doesn't always classify correctly. Reported in 3 sessions.","notes":"GH issue: #521 (https://github.com/marinazzio/evilution/issues/521)","status":"in_progress","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:18.548454128+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T12:21:16.372929584+07:00","external_ref":"gh-521","labels":["reliability"]}
 {"id":"EV-241","title":"Heredoc-aware string literal mutations","description":"Evilution's string_literal operator generates many false survived mutants on heredoc templates by mutating whitespace and literal text around interpolations. MigrationGenerator scored 63.1% due to template whitespace mutations that don't affect generated code behavior. Should either skip literal text in heredocs, only mutate interpolated expressions, or add a --skip-heredoc-literals flag. Reported in 1 session but caused significant score distortion.","notes":"GH issue: #522 (https://github.com/marinazzio/evilution/issues/522)","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:22:20.534650035+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:23:19.83846784+07:00","external_ref":"gh-522","labels":["reliability","false-positives"]}
 {"id":"EV-242","title":"Profile memory allocation during boot/setup phase","description":"Use memory_profiler gem or ObjectSpace to identify what objects are allocated during Evilution boot before any mutations run. Identify the top 10 memory consumers. This will help understand where the 718 MB baseline comes from.","notes":"GitHub: #527","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:39.583808805+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T23:36:18.3122267+07:00","closed_at":"2026-04-05T23:36:18.3122267+07:00","close_reason":"Boot footprint is ~30 MB. The 718 MB baseline was MCP host process, not evilution.","dependencies":[{"issue_id":"EV-242","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-243","title":"Profile memory allocation during single mutation cycle","description":"Measure memory before and after a single mutation+test cycle. Identify what is allocated and not released within one cycle. Compare with mutant's behavior for the same file.","notes":"GitHub: #528","status":"in_progress","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:46.085727121+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T23:37:08.936438689+07:00","dependencies":[{"issue_id":"EV-243","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-244","title":"Run head-to-head comparison on 10 diverse files, catalog every mutation mutant generates that evilution doesn't","description":"Pick 10 files of varying complexity (controller, model, service, validator, lib, migration, Avo resource, helper, concern, formatter). Run both mutant and evilution on each file. Catalog every mutation mutant produces that evilution misses. Classify each as: real signal, likely equivalent, or noise.","notes":"GitHub: #523","status":"open","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:52.935963449+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T15:36:16.088018831+07:00","dependencies":[{"issue_id":"EV-244","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-244","title":"Run head-to-head comparison on 10 diverse files, catalog every mutation mutant generates that evilution doesn't","description":"Pick 10 files of varying complexity (controller, model, service, validator, lib, migration, Avo resource, helper, concern, formatter). Run both mutant and evilution on each file. Catalog every mutation mutant produces that evilution misses. Classify each as: real signal, likely equivalent, or noise.","notes":"GitHub: #523","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:52.935963449+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T00:06:40.444637431+07:00","closed_at":"2026-04-09T00:06:40.444637431+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-244","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-245","title":"Investigate cross-run session memory growth","description":"Run multiple evilution invocations via MCP in the same session. Measure RSS between invocations. Determine if the growth (718->763->795->800 MB) is in the MCP server process, worker pool, or accumulated state.","notes":"GitHub: #529","status":"in_progress","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:54.234490102+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T23:40:31.266000331+07:00","dependencies":[{"issue_id":"EV-245","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-246","title":"Investigate parent vs child process memory split","description":"Measure RSS of the parent (coordinator) process separately from forked child (worker) processes. Determine where the 718 MB baseline lives — is it the parent before forking, or do children inherit and grow independently?","notes":"GitHub: #531","status":"in_progress","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:28:59.300347033+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T23:45:11.030185257+07:00","dependencies":[{"issue_id":"EV-246","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-247","title":"Add RSS tracking per mutation to JSON output","description":"Include parent_rss_kb and child_rss_kb fields in each mutation result. child_rss_kb partially exists (seen in feedback log) — verify it is accurate and add parent_rss_kb tracking. This provides ongoing observability for memory usage.","notes":"GitHub: #532","status":"in_progress","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:08.569266807+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T23:49:30.25391422+07:00","dependencies":[{"issue_id":"EV-247","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-248","title":"Implement memory budget CI gate","description":"Add a CI check that runs rake memory:check and fails if peak RSS exceeds a threshold (e.g., 400 MB for a reference fixture). This prevents memory regressions from being merged.","notes":"GitHub: #533","status":"open","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:16.177682161+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T11:45:18.765568988+07:00","close_reason":"Growth-based leak detection in CI (EV-274/PR #571) is sufficient. Absolute peak RSS budget not needed — standalone baseline is ~30 MB (EV-239 premise was invalid). Per-mutation growth check catches regressions effectively.","dependencies":[{"issue_id":"EV-248","depends_on_id":"EV-239","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-249","title":"Audit current SourceSurgeon mutation-and-restore flow","description":"Document the current code path: where the file is read, mutated, written, and restored. Identify all callers and the ensure-based restore mechanism. Map the failure modes (SIGKILL, OOM, etc.).","notes":"## Audit Findings\n\n### Read Points\n1. **AST::Parser#call** (parser.rb:11) — File.read to parse with Prism\n2. **Mutator::Base#call** (base.rb:18) — File.read to store as original_source in Mutation\n3. **Integration::RSpec#apply_mutation** (rspec.rb:68) — reads before overwrite (direct-overwrite fallback only)\n4. **Isolation::Fork#restore_original_source** (fork.rb:48) — reads to verify if restore needed (defense-in-depth)\n\n### Mutation (In-Memory)\nSourceSurgeon.apply (source_surgeon.rb:6-10) is pure in-memory byte surgery. Never touches filesystem. Called from Mutator::Base#add_mutation.\n\n### Two Write Paths in Integration::RSpec#apply_mutation\n- **Path A (LOAD_PATH shadow, preferred):** Target under $LOAD_PATH → Dir.mktmpdir, write mutated source to mirrored subpath, prepend to $LOAD_PATH. Original file never touched.\n- **Path B (Direct overwrite, fallback):** Not under $LOAD_PATH → acquires exclusive flock, overwrites original file.\n\n### Restore — Two Layers\n- **Layer 1:** Integration::RSpec#restore_original via ensure in #call (rspec.rb:33-35). Path A: removes temp dir from $LOAD_PATH, purges $LOADED_FEATURES, deletes temp dir. Path B: writes @original_content back, releases flock.\n- **Layer 2:** Isolation::Fork#restore_original_source (fork.rb:47-53) — parent-process defense-in-depth. Only in sequential (Fork isolation) path. NOT in parallel path.\n\n### Execution Paths\n- **Sequential (jobs=1):** Runner → Isolation::Fork → fork child → Integration::RSpec#call → ensure restore (child) + ensure restore (parent)\n- **Parallel (jobs>1):** Runner → Parallel::Pool → WorkQueue forks workers → Isolation::InProcess → Integration::RSpec#call → ensure restore only. No parent-side defense-in-depth.\n\n### Failure Modes\n- Normal flow / exception: Safe on both paths\n- SIGKILL child (sequential): Safe (parent restores on direct-overwrite; file untouched on temp-dir)\n- **SIGKILL worker (parallel) + direct-overwrite: FILE CORRUPTED — no recovery**\n- **OOM parallel worker + direct-overwrite: FILE CORRUPTED**\n- **SIGINT/SIGTERM to parent + direct-overwrite: File may be corrupted (zero signal handlers in lib/)**\n- Disk full during restore: File stays corrupted\n\n### Key Findings\n- Zero trap/at_exit/Signal.trap calls in entire lib/ directory\n- Biggest risk: direct-overwrite fallback in parallel mode (no parent-side restore)\n- Epic EV-237 should eliminate direct-overwrite path entirely, making LOAD_PATH shadow the only path","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:17.689070042+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.183398494+07:00","closed_at":"2026-04-08T15:53:00.183398494+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-249","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-25","title":"Structured error responses in JSON mode","description":"When --format json is used and exit code is 2 (error), output a JSON object with error details instead of unstructured stderr text. Schema: { \"error\": { \"type\": \"config_error|parse_error|runtime_error\", \"message\": \"...\", \"file\": \"...\" } }. Agents currently have to regex-parse stderr which is fragile.","status":"closed","priority":1,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:38.283715502+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-15T22:41:54.370789377+07:00","closed_at":"2026-03-15T22:41:54.370789377+07:00","close_reason":"Merged PR #74 — structured JSON error output in CLI"}
-{"id":"EV-250","title":"Classify mutant's extra mutations by operator category","description":"From the head-to-head data (EV-244), group mutant's extra mutations by category (e.g., receiver mutations, argument permutations, method name substitutions, literal boundary values). Count how many are signal vs noise per category. Produce a table of categories with signal/noise breakdown.","notes":"GitHub: #526","status":"open","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:21.320269648+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:29:32.613448913+07:00","dependencies":[{"issue_id":"EV-250","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-251","title":"Prioritize operator additions by signal-to-noise ratio","description":"Rank the missing operator categories by: (a) frequency of real signal catches, (b) implementation complexity, (c) expected equivalent mutant rate. Produce a prioritized implementation order for new operators.","notes":"GitHub: #534","status":"open","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:38.370181376+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:29:53.283203728+07:00","dependencies":[{"issue_id":"EV-251","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-250","title":"Classify mutant's extra mutations by operator category","description":"From the head-to-head data (EV-244), group mutant's extra mutations by category (e.g., receiver mutations, argument permutations, method name substitutions, literal boundary values). Count how many are signal vs noise per category. Produce a table of categories with signal/noise breakdown.","notes":"GitHub: #526","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:21.320269648+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T09:11:20.047999158+07:00","closed_at":"2026-04-09T09:11:20.047999158+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-250","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-251","title":"Prioritize operator additions by signal-to-noise ratio","description":"Rank the missing operator categories by: (a) frequency of real signal catches, (b) implementation complexity, (c) expected equivalent mutant rate. Produce a prioritized implementation order for new operators.","notes":"GitHub: #534","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:38.370181376+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T10:41:04.207816996+07:00","closed_at":"2026-04-09T10:41:04.207816996+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-251","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-252","title":"Reproduce and measure per-mutation RSS growth on reference fixture","description":"Create a reproducible benchmark: run evilution on a known fixture file, record RSS after each mutation. Confirm the ~3-8 MB/mutation growth rate. Baseline for measuring fix effectiveness.","notes":"GitHub: #539","status":"in_progress","priority":0,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:39.421709567+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T15:08:27.260195719+07:00","dependencies":[{"issue_id":"EV-252","depends_on_id":"EV-226","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-253","title":"Profile object allocation delta per mutation cycle","description":"Use ObjectSpace.count_objects or memory_profiler to capture what new objects are allocated during one mutation cycle and not released. Identify the top retained object types.","notes":"GitHub: #540 — Profiling complete. Root cause: RSpec ExampleGroup subclass ivars create reference cycles preventing GC (+3380 slots/mutation). Secondary: World#@sources_by_path cache. Fix proven: clearing EG ivars + sources cache after Runner.run = 0 growth.","status":"closed","priority":0,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:41.259785614+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-05T15:50:12.517441649+07:00","closed_at":"2026-04-05T15:50:12.517441649+07:00","close_reason":"Profiling complete. Root cause identified: RSpec ExampleGroup reference cycles + World source cache. Findings documented on GH #540.","dependencies":[{"issue_id":"EV-253","depends_on_id":"EV-226","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-254","title":"Design temp-file mutation architecture","description":"Design how the temp file is created, where it lives (tmpdir vs .evilution/tmp), how the test process is redirected to load it (Ruby $LOAD_PATH manipulation vs file-level bootsnap override vs ENV-based), and how Rails autoloader interacts with it.","notes":"## Architecture Design: Temp-File Mutation\n\n### Problem Statement\nTwo write paths exist in Integration::RSpec#apply_mutation:\n- **Path A (LOAD_PATH shadow):** Works when file is under $LOAD_PATH — writes to temp dir, prepends to $LOAD_PATH. Original file never touched. Already safe.\n- **Path B (Direct overwrite):** Fallback when file is NOT under $LOAD_PATH — overwrites original, restores via ensure. Vulnerable to SIGKILL/OOM (especially in parallel mode where no parent-side defense-in-depth exists).\n\n**Goal:** Eliminate Path B entirely. Never modify the original source file.\n\n---\n\n### Design Decisions\n\n#### 1. Temp file location: Dir.mktmpdir (system tmpdir)\n- Use `Dir.mktmpdir('evilution')` (same as current Path A), NOT .evilution/tmp\n- Rationale: system tmpdir is auto-cleaned on reboot; no risk of polluting the project directory; avoids .gitignore concerns; already proven in current Path A\n\n#### 2. Redirection mechanism: LOAD_PATH shadow + explicit load\n**For files under $LOAD_PATH** (most lib/ files): Keep current approach — mirror subpath in temp dir, prepend to $LOAD_PATH. This handles any `require` calls during the test run.\n\n**For files NOT under $LOAD_PATH** (the current fallback case): \n- Write mutated source to temp dir mirroring the relative path from project root\n- Explicitly `load` the temp file in the forked child to redefine the class/module\n- This replaces the direct-overwrite approach entirely\n- The `load` approach works because it always executes the file (unlike `require` which checks $LOADED_FEATURES)\n\n#### 3. SourceSurgeon: No changes needed\nSourceSurgeon.apply is already pure in-memory byte surgery. It returns a mutated string without touching the filesystem. No changes required for this epic.\n\n#### 4. Where file I/O moves\n**Integration::RSpec#apply_mutation** remains the owner of temp-file writes, but the two-path logic changes:\n- Path A (under $LOAD_PATH): unchanged — temp dir + $LOAD_PATH prepend\n- Path B (not under $LOAD_PATH): temp dir + explicit `load` (replaces direct overwrite)\n- Both paths use temp files. Original is never touched.\n\n#### 5. Restore/cleanup strategy (three layers)\n1. **ensure in Integration::RSpec#call** (existing): Remove temp dir from $LOAD_PATH, purge $LOADED_FEATURES entries, FileUtils.rm_rf temp dir. Works for both paths now.\n2. **ensure in Isolation::Fork#call** (existing): Simplify — no longer needs to check/restore original file content. Instead, just verify temp dir cleanup. Keep as defense-in-depth for temp dir leaks.\n3. **at_exit hook** (new): Register a cleanup for the temp base dir pattern (evilution*) in case of unhandled exit. Safety net for leaked temp dirs.\n4. **Signal traps** (new): Trap SIGTERM/SIGINT in the parent process to ensure temp dir cleanup before exit.\n\n#### 6. Isolation::Fork#restore_original_source\n- Remove the file-content comparison and rewrite logic\n- Replace with temp-dir cleanup verification (check if any evilution temp dirs remain, clean them)\n- This is now truly defense-in-depth rather than a critical restore path\n\n#### 7. Parallel mode (InProcess isolation)\n- No special handling needed — each worker is a forked process with its own $LOAD_PATH\n- Temp dirs are per-mutation, isolated across workers\n- The biggest current risk (corrupted original file on worker SIGKILL) is eliminated because the original file is never modified\n\n#### 8. Zeitwerk (Rails autoloader) compatibility\n- Zeitwerk maps file paths to constant names using autoload_paths (which are $LOAD_PATH entries in Rails)\n- For files under Zeitwerk-managed paths: LOAD_PATH shadow works — Zeitwerk will find the temp version first\n- For files NOT under Zeitwerk paths: the explicit `load` approach bypasses Zeitwerk entirely, which is correct since Zeitwerk wouldn't manage those files anyway\n- Edge case: Zeitwerk caches file-to-constant mappings. In a forked child, the cache is inherited. Since we `load` after fork, the class is redefined in-place — Zeitwerk's cache remains valid (same constant, new definition)\n- Need integration test to verify (EV-268)\n\n---\n\n### Implementation Order\n1. **EV-263** (SourceSurgeon temp-file write): Modify apply_mutation to always use temp files. Add explicit `load` for non-LOAD_PATH files. Remove direct-overwrite fallback.\n2. **EV-265** (Load-path redirection): Refine the LOAD_PATH prepend logic. Handle edge cases (multiple LOAD_PATH matches, nested paths).\n3. **EV-267** (Cleanup): Add at_exit hook and signal traps. Simplify Isolation::Fork defense-in-depth.\n4. **EV-266** (Zeitwerk): Test and handle Zeitwerk edge cases.\n5. **EV-268** (Integration tests): Verify original file never modified, cleanup on normal/exceptional/signal exit, Zeitwerk compat.\n\n### Files to modify\n- `lib/evilution/integration/rspec.rb` — primary changes (apply_mutation, restore_original)\n- `lib/evilution/isolation/fork.rb` — simplify restore_original_source\n- `lib/evilution/isolation/in_process.rb` — no changes expected\n- `lib/evilution/ast/source_surgeon.rb` — no changes\n- `lib/evilution/runner.rb` — possibly add at_exit/signal trap registration","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:42.91131604+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.18355494+07:00","closed_at":"2026-04-08T15:53:00.18355494+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-254","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
@@ -207,7 +207,7 @@
 {"id":"EV-261","title":"Add --skip-heredoc-literals CLI flag","description":"Add a flag to completely skip string literal mutations inside heredocs. For users who prefer zero heredoc mutations.","notes":"GitHub: #548","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:56.515382643+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T19:20:01.937747302+07:00","closed_at":"2026-04-08T19:20:01.937747302+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-261","depends_on_id":"EV-241","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-261","depends_on_id":"EV-260","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-262","title":"Add tests for heredoc mutation behavior","description":"Test: heredoc with no interpolation (skipped or mutated to empty), heredoc with interpolation (only expressions mutated), squiggly heredoc, nested heredoc.","notes":"GitHub: #549","status":"in_progress","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:56.333773283+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T19:20:02.042056553+07:00","dependencies":[{"issue_id":"EV-262","depends_on_id":"EV-241","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-262","depends_on_id":"EV-261","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-263","title":"Implement temp-file write in SourceSurgeon","description":"Modify SourceSurgeon.apply to write mutated source to a temp file instead of overwriting the original. Return the temp file path. Original file is never touched.","notes":"GitHub: #537","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:29:59.265360981+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.183566714+07:00","closed_at":"2026-04-08T15:53:00.183566714+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-263","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-264","title":"Define target metric and measurement methodology for mutation density gap","description":"Define what 'closing the gap' means: target ratio (e.g., <1.5x), measurement protocol (which files, which mutant config), and a benchmark script that can be re-run to track progress over time.","notes":"GitHub: #541","status":"open","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:30:08.545241632+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-04T11:30:26.634822515+07:00","dependencies":[{"issue_id":"EV-264","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-264","title":"Define target metric and measurement methodology for mutation density gap","description":"Define what 'closing the gap' means: target ratio (e.g., <1.5x), measurement protocol (which files, which mutant config), and a benchmark script that can be re-run to track progress over time.","notes":"GitHub: #541","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:30:08.545241632+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T23:19:42.57055849+07:00","closed_at":"2026-04-08T23:19:42.57055849+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-264","depends_on_id":"EV-238","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-265","title":"Implement load-path redirection for forked test process","description":"In the fork isolation, prepend the temp directory to $LOAD_PATH (or use a more targeted mechanism) so that require and load pick up the mutated file instead of the original.","notes":"GitHub: #550","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:30:17.522950262+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.18357647+07:00","closed_at":"2026-04-08T15:53:00.18357647+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-265","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-266","title":"Handle Rails autoloader (Zeitwerk) compatibility","description":"Zeitwerk uses absolute paths. Test that the temp-file approach works with Zeitwerk's file-to-constant mapping. May need to use Zeitwerk's on_load callbacks or file override mechanism.","notes":"GitHub: #551","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:30:40.575881302+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.183584148+07:00","closed_at":"2026-04-08T15:53:00.183584148+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-266","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-267","title":"Add cleanup of temp files after mutation run","description":"Ensure temp files are cleaned up on normal exit, exception, and signal (SIGTERM/SIGINT). Use at_exit hooks and signal traps.","notes":"GitHub: #552","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-04T11:30:57.733824316+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-08T15:53:00.18359655+07:00","closed_at":"2026-04-08T15:53:00.18359655+07:00","close_reason":"Closed","dependencies":[{"issue_id":"EV-267","depends_on_id":"EV-237","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
@@ -221,6 +221,9 @@
 {"id":"EV-274","title":"Add rake memory:check to CI pipeline","description":"Add the memory leak regression check (rake memory:check) as a CI step. This catches regressions in isolation/integration code by detecting per-mutation RSS growth spikes. Requires Linux runner (/proc/self/status). Consider running after the main spec suite to avoid blocking fast feedback.","notes":"GitHub: #566","status":"closed","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-05T22:53:27.447410371+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T11:52:58.110045281+07:00","closed_at":"2026-04-06T11:52:58.110045281+07:00","close_reason":"Implemented in PR #571. Added memory_check job to CI workflow with pinned runner (ubuntu-24.04), SHA-pinned actions, and explicit threshold env vars."}
 {"id":"EV-275","title":"Use project's own complex classes as memory check fixture","description":"Replace the simple_class.rb fixture in script/memory_check with more complex classes from the evilution codebase itself (e.g. Runner, Config, AST::Parser). This provides realistic per-mutation load: more ExampleGroup subclasses, deeper spec nesting, and heavier metadata — closer to what users see in real projects. Affects check #5 (RSpec integration per-mutation) primarily.","notes":"GitHub: #567","status":"in_progress","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-05T22:53:30.214655275+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T12:36:50.959507734+07:00"}
 {"id":"EV-276","title":"InProcess suppress_output closes /dev/null handles causing 'closed stream' on reuse with clear_examples","description":"InProcess#suppress_output uses File.open with blocks that auto-close /dev/null handles after each call. When the RSpec integration uses clear_examples (which reuses Configuration), the formatter retains a reference to $stdout from the first run. On subsequent calls, the formatter writes to the closed handle, causing 'closed stream' errors. Fix: use persistent /dev/null handles or StringIO.","notes":"GitHub: #569","status":"in_progress","priority":2,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-05T23:06:51.502713099+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-06T12:02:05.127419951+07:00"}
+{"id":"EV-277","title":"Multi-byte character offset bug in AST::Parser subject extraction","description":"When parsing files containing multi-byte characters (e.g. Cyrillic), AST::Parser uses @source[loc.start_offset...loc.end_offset] on the string directly instead of on the binary representation. Prism byte offsets are byte-based, but Ruby string slicing is character-based for encoded strings, causing extracted method bodies to be garbled. Fix: use @source.b[offset...end].force_encoding(@source.encoding) as done in the mutant_json_adapter workaround.","notes":"GitHub: #615","status":"open","priority":1,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-09T00:01:43.021380194+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T00:01:58.491188786+07:00"}
+{"id":"EV-278","title":"IndexToAt operator: [] → .at() substitution","description":"Add mutation operator that replaces array/hash [] access with .at() method. .at() returns nil on out-of-bounds instead of raising, exposing missing bounds checks. Identified in EV-251 prioritization as the only uncovered signal category (60 mutations in benchmark corpus). Low implementation complexity — match CallNode with name [] on collection receivers.","notes":"GitHub: #618","status":"in_progress","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-09T09:12:09.052329944+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T11:26:17.496127389+07:00"}
+{"id":"EV-279","title":"BlockPassRemoval operator: remove &:method block pass","description":"Add mutation operator that removes &:symbol block pass arguments from method calls (e.g. map(&:to_s) → map). Low priority — only 5 mutations in benchmark corpus, but trivial to implement. Identified in EV-251 prioritization.","notes":"GitHub: #619","status":"in_progress","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-04-09T09:12:14.145760441+07:00","created_by":"Denis Kiselev","updated_at":"2026-04-09T10:43:28.718393237+07:00"}
 {"id":"EV-28","title":"MCP server for direct tool invocation","description":"Implement a Model Context Protocol (MCP) server that exposes evilution as a tool. Agents could call evilution directly instead of shelling out and parsing output. The server should expose a 'mutate' tool that accepts target files, options, and returns structured results.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:45.29866593+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T22:58:51.734461132+07:00","closed_at":"2026-03-16T22:58:51.734461132+07:00","close_reason":"PR #103 merged — MCP server with evilution-mutate tool via stdio transport"}
 {"id":"EV-29","title":"Add --stdin flag to accept file list from stdin","description":"Add a --stdin flag that reads target file paths (one per line) from stdin. Enables workflows like: git diff --name-only | evilution run --stdin --format json. Each line can include line-range syntax (e.g. lib/foo.rb:15-30).","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:17:46.306306092+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T18:03:28.998559073+07:00","closed_at":"2026-03-16T18:03:28.998559073+07:00","close_reason":"PR #92 merged — --stdin flag for piped file list workflows"}
 {"id":"EV-3","title":"Phase 2: Mutation Operators & CLI","description":"Implement remaining 17 mutation operators, build CLI with OptionParser, exe/evilution executable, human-readable reporter. Milestone: bundle exec evilution run lib/user.rb --format json","status":"closed","priority":2,"issue_type":"epic","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:05:00.492971295+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:21:32.168384165+07:00","closed_at":"2026-03-02T11:21:32.168384165+07:00","close_reason":"Phase 2 complete: all 18 operators, CLI, Reporter::CLI, Registry registration, executable","dependencies":[{"issue_id":"EV-3","depends_on_id":"EV-2","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.22.0] - 2026-04-09
+
+### Added
+
+- **Minitest integration** — full Minitest support as an alternative to RSpec; abstract `Integration::Base` framework with template method pattern; `Integration::Minitest` with programmatic `Minitest.__run` execution, `MinitestCrashDetector` reporter for distinguishing assertion failures from crashes; `--integration minitest` CLI flag and `integration: minitest` config option; `SpecResolver` parameterized for Minitest file discovery (`test/`, `_test.rb`); plugin-based runner dispatch via `INTEGRATIONS` registry; baseline runner abstracted from RSpec with injectable runner callable; Minitest concrete suggestion templates using `def test_`/`assert_equal` style (#223, #224, #225, #226, #227, #228, #229, #230)
+- **New mutation operators (3)** — `index_to_at` replaces `arr[0]` with `arr.at(0)` for array index access (#618); `regex_simplification` simplifies regex character classes and quantifiers (#514); `block_pass_removal` removes block arguments (`&...`) in method calls (#619)
+- **Mutation density benchmarking** — comparison tools and methodology for measuring mutation density against reference tool; baseline results and operator classification documents (#523, #526, #541)
+
+### Fixed
+
+- **Multi-byte character offset bug** — Prism byte offsets were used with character-based `String#[]`, causing garbled source extraction for files with multi-byte characters (UTF-8 Cyrillic, Thai, CJK, etc.); fixed `AST::Parser`, `DisableComment`, and 7 mutation operators to use `byteslice`/`getbyte`; added `byteslice_source` helper to `Mutator::Base` (#615)
+
+### Changed
+
+- **Operator count** — 72 operators (up from 69), with new index-to-at, regex simplification, and block pass removal operators
+- **Test framework support** — RSpec and Minitest both supported; documentation updated throughout CLI help, MCP tool descriptions, and README
+
 ## [0.21.0] - 2026-04-08
 
 ### Added

data/README.md

@@ -7,7 +7,7 @@
 * **License**: MIT (free, no commercial restrictions)
 * **Language**: Ruby >= 3.3
 * **Parser**: Prism (Ruby's official AST parser, ships with Ruby 3.3+)
-* **Test framework**: RSpec (currently the only supported integration)
+* **Test frameworks**: RSpec and Minitest
 
 ## Installation
 
@@ -57,9 +57,10 @@ evilution [command] [options] [files...]
 | `--no-baseline`              | Boolean | _(enabled)_  | Skip baseline test suite check. By default, a baseline run detects pre-existing failures and marks those mutations as `neutral`. |
 | `--fail-fast [N]`            | Integer | _(none)_     | Stop after N surviving mutants (default 1 if no value given). |
 | `-v`, `--verbose`            | Boolean | false        | Verbose output with RSS memory and GC stats per phase and per mutation. |
-| `--suggest-tests`            | Boolean | false        | Generate concrete RSpec test code in suggestions instead of static descriptions. |
+| `--suggest-tests`            | Boolean | false        | Generate concrete test code in suggestions (RSpec or Minitest, based on `--integration`). |
 | `-q`, `--quiet`              | Boolean | false        | Suppress output.                                   |
 | `--stdin`                    | Boolean | false        | Read target file paths from stdin (one per line).  |
+| `--integration NAME`         | String  | `rspec`      | Test framework integration: `rspec` or `minitest`.  |
 | `--incremental`              | Boolean | false        | Cache killed/timeout results; skip unchanged mutations on re-runs. |
 | `--save-session`             | Boolean | false        | Persist results as timestamped JSON under `.evilution/results/`. |
 | `--no-progress`              | Boolean | _(enabled)_  | Disable the TTY progress bar.                      |
@@ -86,8 +87,8 @@ Creates `.evilution.yml`:
 # timeout: 30              # seconds per mutation
 # format: text             # text | json | html
 # min_score: 0.0           # 0.0–1.0
-# integration: rspec       # test framework
-# suggest_tests: false     # concrete RSpec test code in suggestions
+# integration: rspec       # test framework: rspec, minitest
+# suggest_tests: false     # concrete test code in suggestions (matches integration)
 # save_session: false      # persist results under .evilution/results/
 # skip_heredoc_literals: false  # skip all string literal mutations inside heredocs
 # show_disabled: false     # report mutations skipped by disable comments
@@ -168,7 +169,7 @@ 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.
 
-## Mutation Operators (69 total)
+## Mutation Operators (72 total)
 
 Each operator name is stable and appears in JSON output under `survived[].operator`.
 
@@ -201,8 +202,10 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `keyword_argument` | Remove keyword defaults/params | `def foo(bar: 42)` -> `def foo(bar:)` |
 | `multiple_assignment` | Remove targets or swap order | `a, b = 1, 2` -> `b, a = 1, 2` |
 | `block_removal` | Remove blocks from method calls | `items.map { \|x\| x * 2 }` -> `items.map` |
+| `block_pass_removal` | Remove block arguments passed with `&` | `items.map(&:to_s)` -> `items.map` |
 | `range_replacement` | Swap inclusive/exclusive ranges | `1..10` -> `1...10` |
 | `regexp_mutation` | Replace regexp with always/never matching | `/pat/` -> `/a\A/` |
+| `regex_simplification` | Simplify regex quantifiers, anchors, ranges | `/\d+/` -> `/\d/`, `/[a-z]/` -> `/[az]/` |
 | `receiver_replacement` | Drop explicit `self` receiver | `self.foo` -> `foo` |
 | `send_mutation` | Swap semantically related methods | `detect` -> `find`, `map` -> `flat_map` |
 | `compound_assignment` | Swap compound assignment operators | `+=` -> `-=`, `&&=` -> `\|\|=` |
@@ -224,6 +227,7 @@ Each operator name is stable and appears in JSON output under `survived[].operat
 | `bitwise_complement` | Remove or swap `~` | `~x` -> `x`, `~x` -> `-x` |
 | `zsuper_removal` | Replace implicit `super` with `nil` | `super` -> `nil` |
 | `explicit_super_mutation` | Mutate explicit super arguments | `super(a, b)` -> `super` |
+| `index_to_at` | Replace `[]` with `.at()` for arrays | `arr[0]` -> `arr.at(0)` |
 | `index_to_fetch` | Replace `[]` with `.fetch()` | `h[k]` -> `h.fetch(k)` |
 | `index_to_dig` | Replace `[]` chains with `.dig()` | `h[a][b]` -> `h.dig(a, b)` |
 | `index_assignment_removal` | Remove `[]=` assignments | `h[k] = v` -> removed |
@@ -290,9 +294,9 @@ Use `minimal` when context window budget is tight and you only need to see what
 
 ### Concrete Test Suggestions
 
-The MCP tool accepts a `suggest_tests` boolean parameter (default: `false`). When enabled, survived mutation suggestions contain concrete RSpec `it` blocks that an agent can drop into a spec file, instead of static description text.
+The MCP tool accepts a `suggest_tests` boolean parameter (default: `false`). When enabled, survived mutation suggestions contain concrete test code that an agent can drop into a test file, instead of static description text. The MCP tool currently generates RSpec-style suggestions (`it`/`expect` blocks).
 
-Pass `suggest_tests: true` in the MCP tool call, or use `--suggest-tests` on the CLI, to activate this mode.
+Pass `suggest_tests: true` in the MCP tool call to activate this mode. The CLI also supports `--suggest-tests`; when using the CLI, generated suggestions match the `--integration` setting (RSpec `it`/`expect` blocks or Minitest `def test_`/`assert_equal` methods).
 
 > **Note**: `.mcp.json` is gitignored by default since it is a local editor/agent configuration file.
 
@@ -356,7 +360,7 @@ Use when you know which file was modified and want to verify its test coverage.
 For each entry in `survived[]`:
 1. Read `file` at `line` to understand the code context
 2. Read `operator` to understand what was changed
-3. Read `suggestion` for a hint on what test to write (use `--suggest-tests` for concrete RSpec code)
+3. Read `suggestion` for a hint on what test to write (use `--suggest-tests` for concrete test code)
 4. Write a test that would fail if the mutation were applied
 5. Re-run evilution on just that file to verify the mutant is now killed
 
@@ -389,9 +393,9 @@ 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** — 69 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default
+4. **Mutate** — 72 operators produce text replacements at precise byte offsets (source-level surgery, no AST unparsing); heredoc literal text is skipped by default
 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; `--isolation fork` uses forked child processes. Parallel mode (`--jobs N`) always uses in-process isolation inside pool workers to avoid double forking
-6. **Test** — RSpec executes against the mutated source
+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
 

data/comparison_results/baseline_2026-04-09.md

@@ -0,0 +1,35 @@
+# Head-to-Head Mutation Comparison Baseline
+
+Date: 2026-04-09
+Evilution: v0.21.0
+Reference tool: mutant 0.16.0 (via mutant_json_adapter)
+Target project: private Rails app (Ruby 4.0.1)
+
+## Results
+
+| File | Evilution | Reference | Ratio |
+|------|-----------|-----------|-------|
+| app/controllers/admin/news_controller.rb | 363 | 524 | 1.44x |
+| app/models/player_claim.rb | 237 | 281 | 1.19x |
+| app/services/telegram/news_scorer.rb | 353 | 496 | 1.41x |
+| app/validators/password_strength_validator.rb | 157 | 179 | 1.14x |
+| app/policies/application_policy.rb | 79 | 86 | 1.09x |
+| app/services/telegram/entities_formatter.rb | 454 | 647 | 1.43x |
+| app/services/autosave_game_protocol_service.rb | 315 | 418 | 1.33x |
+| lib/scraper/game_scraper.rb | 449 | 625 | 1.39x |
+| app/jobs/process_telegram_webhook_job.rb | 196 | 255 | 1.30x |
+| lib/telegram/export_parser.rb | 300 | 390 | 1.30x |
+| **TOTAL** | **2,903** | **3,901** | **1.34x** |
+
+## Summary
+
+- Density ratio: **1.34x** (target: < 1.5x) — **PASS**
+- Highest gap: entities_formatter.rb (1.44x), news_controller.rb (1.44x)
+- Lowest gap: application_policy.rb (1.09x)
+
+## Notes
+
+- Reference tool cannot parse Ruby 4.0 files natively; used mutant_json_adapter
+  (Prism-based method extraction + mutant util mutation -e per method)
+- This means reference tool mutations lack class-level context (constants,
+  inheritance, instance variables) — actual gap may be slightly different

data/comparison_results/operator_classification.md

@@ -0,0 +1,79 @@
+# Reference Tool Mutation Classification by Operator Category
+
+Date: 2026-04-09
+Corpus: 10 files from a private Rails app (2,903 evilution / 3,901 reference mutations)
+
+## Category Breakdown
+
+Classification of all 3,901 reference tool mutations by semantic category,
+with signal/noise assessment and evilution coverage status.
+
+| Category | Count | % | Signal | Evilution Coverage |
+|----------|------:|--:|--------|-------------------|
+| complex_mutation | 854 | 21.9% | Mixed | Partial — multi-statement changes, compound mutations spanning multiple lines |
+| argument_nil | 585 | 15.0% | Signal | Covered — ArgumentNilSubstitution, ArgumentRemoval |
+| guard_clause_restructure | 570 | 14.6% | Noise | Not applicable — reformats `return if X` to `unless X; return; end` without semantic change |
+| receiver_mutation | 416 | 10.7% | Signal | Covered — ReceiverReplacement, MethodCallRemoval |
+| receiver_self_swap | 281 | 7.2% | Mixed | Partial — ReceiverReplacement covers some; `self.` insertion is often equivalent |
+| string_mutation | 224 | 5.7% | Signal | Covered — StringLiteral, StringInterpolation |
+| arithmetic_mutation | 224 | 5.7% | Signal | Covered — ArithmeticReplacement |
+| symbol_mutation | 129 | 3.3% | Signal | Covered — SymbolLiteral (mutant uses `__mutant__` suffix) |
+| hash_mutation | 119 | 3.1% | Mixed | Partial — HashLiteral covers structure; key reordering is noise |
+| method_body_removal | 94 | 2.4% | Signal | Covered — MethodBodyReplacement (empty body variant) |
+| method_body_raise | 79 | 2.0% | Signal | Covered — MethodBodyReplacement (raise variant) |
+| method_body_super | 79 | 2.0% | Signal | Covered — MethodBodyReplacement (super variant) |
+| method_substitution_at | 60 | 1.5% | Mixed | Not covered — `[]` → `.at()` catches missing bounds checks |
+| method_substitution_fetch | 58 | 1.5% | Signal | Covered — IndexToFetch |
+| condition_nil_false | 43 | 1.1% | Signal | Covered — ConditionalBranch, NilReplacement |
+| method_body_nil | 27 | 0.7% | Signal | Covered — MethodBodyReplacement (nil variant) |
+| regex_mutation | 27 | 0.7% | Signal | Covered — RegexpMutation, RegexCapture |
+| boolean_literal | 16 | 0.4% | Signal | Covered — BooleanLiteralReplacement |
+| equality_mutation | 10 | 0.3% | Signal | Covered — EqualityToIdentity |
+| block_pass_mutation | 5 | 0.1% | Signal | Partial — BlockRemoval covers block removal; `&:method` removal not specific |
+| integer_boundary | 1 | 0.0% | Signal | Covered — IntegerLiteral |
+
+## Signal vs Noise Summary
+
+| Assessment | Count | % |
+|------------|------:|--:|
+| Signal (catches real bugs) | 2,176 | 55.8% |
+| Mixed (some signal, some equivalent) | 1,155 | 29.6% |
+| Noise (equivalent or reformatting) | 570 | 14.6% |
+
+## Key Findings
+
+### 1. Guard clause restructuring is pure noise (14.6%)
+
+The reference tool rewrites `return X if condition` to `unless condition; return X; end`.
+This is a syntactic reformatting, not a semantic mutation. It inflates the mutation count
+without testing anything. Evilution correctly does not produce these.
+
+### 2. Most categories are already covered by evilution
+
+Of 20 categories, evilution has operators covering 14 fully and 4 partially.
+Only 2 categories are not covered:
+- **guard_clause_restructure** — noise, should not be added
+- **method_substitution_at** — `[]` → `.at()`, marginal signal
+
+### 3. The "complex_mutation" bucket needs further analysis
+
+854 mutations (21.9%) are multi-statement compound changes that don't fit a single
+category. Many combine receiver replacement + argument modification + formatting
+changes in one diff. Some contain real signal (e.g., removing a hash key from a
+method call), others are largely equivalent reformattings.
+
+### 4. The 1.34x gap is largely explained by:
+
+- Guard clause restructuring: 570 mutations (noise)
+- Receiver self-swap equivalents: ~140 mutations (noise portion of 281)
+- Complex compound mutations: ~288 mutations (noise portion of 854)
+
+**Removing noise**, the effective gap drops to approximately **1.0-1.1x** —
+near parity for signal-bearing mutations.
+
+## Recommendations for EV-251 (Prioritization)
+
+1. **Do not add** guard clause restructuring — pure noise
+2. **Consider adding** `[]` → `.at()` substitution (60 mutations, real signal for bounds checking)
+3. **Investigate** the complex_mutation bucket further to extract any discrete operator patterns
+4. **Current density target (< 1.5x) is already met** at 1.34x overall

data/comparison_results/operator_prioritization.md

@@ -0,0 +1,68 @@
+# Operator Addition Prioritization
+
+Date: 2026-04-09
+Based on: EV-250 classification of 3,901 reference tool mutations across 10 files
+
+## Current Status
+
+- Density ratio: **1.34x** (target: < 1.5x) — **already passing**
+- Evilution: 68 operators covering 14/20 reference categories fully, 4 partially
+- Effective signal gap after removing noise: ~1.0-1.1x (near parity)
+
+## Prioritized Operator Additions
+
+Ranked by: (a) signal frequency, (b) implementation complexity, (c) equivalent mutant rate.
+
+### Priority 1: High signal, low complexity
+
+| # | Operator | Signal Count | Complexity | Equiv. Rate | Notes |
+|---|----------|-------------|-----------|-------------|-------|
+| 1 | `[]` → `.at()` substitution | 60 | Low | Low (~10%) | Catches unchecked array/hash access. Single AST node transform. New operator needed. |
+
+**Rationale:** Only uncovered category with real signal. `.at()` returns nil
+instead of raising on out-of-bounds, exposing missing bounds checks. Simple to
+implement — match `CallNode` with name `[]` on collection receivers, emit `.at()`
+variant.
+
+### Priority 2: Improve existing coverage (partial gaps)
+
+| # | Operator | Gap Area | Complexity | Equiv. Rate | Notes |
+|---|----------|----------|-----------|-------------|-------|
+| 2 | Regex simplification (EV-230, #514) | 27 | Medium | Low (~15%) | Quantifier removal, anchor removal, character class simplification. Already scoped. |
+| 3 | Block pass removal (`&...`) | 5 | Low | Medium (~30%) | Remove `&` block pass arguments (`&:symbol`, `&method(:name)`, etc). Marginal count but trivial to add. |
+
+**Rationale:** EV-230 is already scoped with a GH issue. Block pass removal is
+minimal effort for minimal gain — include only if doing a batch of small operators.
+
+### Priority 3: Do not implement
+
+| # | Category | Count | Reason |
+|---|----------|------:|--------|
+| — | Guard clause restructuring | 570 | Pure noise — syntactic reformatting, not semantic mutation |
+| — | Receiver self-swap (remaining) | ~140 | Mostly equivalent — `self.method` vs `method` rarely matters |
+| — | Complex compound mutations | ~288 | Noise portion of multi-statement changes; not decomposable into discrete operators |
+
+## Implementation Order
+
+1. **EV-230** (#514) — Regex simplification operators (already scoped, medium complexity, 27 signal mutations)
+2. **New: `IndexToAt`** — `[]` → `.at()` substitution (60 signal mutations, low complexity)
+3. **New: `BlockPassRemoval`** — `&:method` removal (5 signal mutations, trivial)
+
+## Impact Assessment
+
+| Scenario | Estimated Ratio | Delta |
+|----------|----------------|-------|
+| Current | 1.34x | — |
+| After adding all Priority 1+2 | ~1.31x | -0.03x |
+
+The density gap is already within target. These additions improve **signal
+coverage** (catching real bugs that reference tool catches and evilution misses)
+rather than closing the headline ratio, which is already healthy.
+
+## Recommendation
+
+The density gap research (EV-238) can be considered **successful** — the 1.5x
+target is met at 1.34x. Remaining work should focus on signal quality (regex
+mutations, bounds checking) rather than chasing the ratio lower. The reference
+tool's ~15% noise inflation means its raw count is not a meaningful target for
+exact parity.

data/docs/mutation_density_benchmark.md

@@ -0,0 +1,91 @@
+# Mutation Density Benchmark Methodology
+
+## Goal
+
+Track and close the mutation density gap between evilution and a reference
+mutation testing tool.
+Current gap: **1.8-2.6x** (evilution generates fewer mutations).
+Target: **< 1.5x** across the benchmark corpus.
+
+## Metric
+
+**Density ratio** = `reference_mutations / evilution_mutations` per file.
+
+A ratio of 1.0 means parity. Values above 1.0 mean the reference tool generates
+more. The aggregate ratio is computed from total mutations across all benchmark
+files (not an average of per-file ratios, which would over-weight small files).
+
+## Measurement Protocol
+
+### Benchmark corpus
+
+Select **10 files** from a real-world Rails project covering diverse patterns:
+
+| Slot | Category             | Example                          |
+|------|----------------------|----------------------------------|
+| 1    | Controller           | `app/controllers/*_controller.rb`|
+| 2    | Model (ActiveRecord) | `app/models/*.rb`                |
+| 3    | Service object       | `app/services/*.rb`              |
+| 4    | Validator            | `app/validators/*.rb`            |
+| 5    | Concern / mixin      | `app/models/concerns/*.rb`       |
+| 6    | Helper               | `app/helpers/*.rb`               |
+| 7    | Formatter / presenter| `app/presenters/*.rb`            |
+| 8    | Lib utility          | `lib/*.rb`                       |
+| 9    | Job / worker         | `app/jobs/*.rb`                  |
+| 10   | Configuration / DSL  | `config/initializers/*.rb`       |
+
+Files should be **50-300 LOC** (enough mutations to be meaningful, small enough
+to run quickly). The exact file list is stored in the benchmark config file
+(`scripts/benchmark_density.yml`).
+
+### Tool configuration
+
+Both tools must run with equivalent settings:
+
+- **evilution**: default operators, no `--skip-heredoc-literals`, no ignore patterns
+- **reference tool**: default operator set, no timeout (we only count, not run)
+
+The benchmark counts **generated mutations**, not killed/survived. This isolates
+operator coverage from test quality.
+
+### Running the benchmark
+
+```bash
+# Count-only mode (fast, no test execution):
+scripts/benchmark_density scripts/benchmark_density.yml
+
+# Full output with per-file breakdown:
+scripts/benchmark_density scripts/benchmark_density.yml --verbose
+```
+
+### Output
+
+The script produces a table:
+
+```
+File                          Evilution  Reference  Ratio
+app/models/user.rb                  42         78  1.86x
+app/services/payment.rb             31         52  1.68x
+...
+TOTAL                              312        534  1.71x
+```
+
+And a summary: `Density ratio: 1.71x (target: < 1.50x)`.
+
+## When to Run
+
+- **Before each release** that adds new operators
+- **After closing operator issues** from the gap analysis epic (GH #515)
+- **On demand** when evaluating whether a proposed operator is worth adding
+
+## Interpreting Results
+
+- **Ratio < 1.5x**: target met
+- **Ratio 1.5-2.0x**: progress, but more operators needed
+- **Ratio > 2.0x**: significant gap remains
+- **Per-file outliers**: files with ratio > 3.0x likely expose a missing operator category
+
+Not all extra mutations from the reference tool are valuable. Some produce
+equivalent mutants (semantically identical code). The head-to-head comparison
+(GH #523) classifies each extra mutation as signal vs noise. The density ratio
+is a **coarse progress metric**, not a quality score.