evilution 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e568b1c786f7e222faef20c3e49f78b3d1f2c40c9ebb7162960446ddbfbda81
-  data.tar.gz: '087c483fdf29859f33c2d92fefd97b9b89d3b94ad728aa89bf564f5183f22d36'
+  metadata.gz: 66bf48cbfe57daab8f06f98ace9a49b733e0143ae9c3e5e4c5fb516f465b30d7
+  data.tar.gz: d021601a2e2256e1c846f55c355845aaacfb8435116873f3c1d74c0e5d7dda33
 SHA512:
-  metadata.gz: 365a112cc494347d628cc0252472bde1f94ac1336730c4c1227e0c06fd0d733b94e93484b87b9ba134cb42f8ca15b36324761b43a889b0c153db6d40024f48fc
-  data.tar.gz: 5d02b004948bc6c0e8e2c4762b730163cdf2c69a7319d836ddc0b2675241eff8d2e1538505462b1392a8dc2002af3c5466247cce221fe178d8ca9f3815d0781d
+  metadata.gz: 731b85019e5571ddfd8d72904a8303f231c8ba6d5dac1c27782e1dbf11943d55be4d8796382e3bb49b20a719755b0690e2305076b9a42dfe7080103ac88252f0
+  data.tar.gz: e5d61aa19eeea415a19f7ab4ea98e09682de65a7694315a82a2989e31d874f176c22e58103a462055c5a73ed29f5f82d5136e26134cc74907cbbc5151dee0541

data/.beads/.migration-hint-ts

@@ -1 +1 @@
-1774024848
+1774149286

data/.beads/issues.jsonl

@@ -61,8 +61,8 @@
 {"id":"EV-3.7","title":"Implement StringLiteral operator","description":"Targets StringNode. Mutations: non-empty -> empty string, empty -> 'mutation'. File: lib/evilution/mutator/operator/string_literal.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:13.633726423+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:10:56.39748015+07:00","closed_at":"2026-03-02T11:10:56.39748015+07:00","close_reason":"All 3 operators implemented with passing specs","dependencies":[{"issue_id":"EV-3.7","depends_on_id":"EV-3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-3.7","depends_on_id":"EV-2.6","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-3.8","title":"Implement ArrayLiteral operator","description":"Targets ArrayNode with elements. Mutation: [a, b, c] -> []. File: lib/evilution/mutator/operator/array_literal.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:13.734617709+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:10:56.397565925+07:00","closed_at":"2026-03-02T11:10:56.397565925+07:00","close_reason":"All 3 operators implemented with passing specs","dependencies":[{"issue_id":"EV-3.8","depends_on_id":"EV-3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-3.8","depends_on_id":"EV-2.6","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-3.9","title":"Implement HashLiteral operator","description":"Targets HashNode with pairs. Mutation: {k: v} -> {}. File: lib/evilution/mutator/operator/hash_literal.rb + spec.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T00:06:13.840779748+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-02T11:10:56.397570989+07:00","closed_at":"2026-03-02T11:10:56.397570989+07:00","close_reason":"All 3 operators implemented with passing specs","dependencies":[{"issue_id":"EV-3.9","depends_on_id":"EV-3","type":"parent-child","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-3.9","depends_on_id":"EV-2.6","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-30","title":"Epic: Smarter Suggestions","description":"Improve the suggestion field in mutation results to provide concrete, actionable test code that agents can use directly.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:03.590579846+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:03.590579846+07:00","dependencies":[{"issue_id":"EV-30","depends_on_id":"EV-31","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-31","title":"Generate concrete RSpec test code in suggestions","description":"Replace prose suggestions like 'add a test that checks the boundary' with actual RSpec code snippets that would kill the mutant. Use the mutation's operator, file context, and method signature to generate a concrete test example. The suggestion should be a valid RSpec 'it' block that an agent can drop into a spec file.","status":"open","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:05.964542284+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-10T06:18:05.964542284+07:00","dependencies":[{"issue_id":"EV-31","depends_on_id":"EV-55","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-56","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-57","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-58","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-59","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-60","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-61","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-30","title":"Epic: Smarter Suggestions","description":"Improve the suggestion field in mutation results to provide concrete, actionable test code that agents can use directly.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:03.590579846+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:18:58.004667853+07:00","closed_at":"2026-03-22T17:18:58.004667853+07:00","close_reason":"Epic complete. Concrete RSpec test suggestions implemented for all 16 operator types, gated behind --suggest-tests flag, with MCP tool support and documentation.","dependencies":[{"issue_id":"EV-30","depends_on_id":"EV-31","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-31","title":"Generate concrete RSpec test code in suggestions","description":"Replace prose suggestions like 'add a test that checks the boundary' with actual RSpec code snippets that would kill the mutant. Use the mutation's operator, file context, and method signature to generate a concrete test example. The suggestion should be a valid RSpec 'it' block that an agent can drop into a spec file.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:05.964542284+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:18:20.274404522+07:00","closed_at":"2026-03-22T17:18:20.274404522+07:00","close_reason":"All concrete suggestion templates implemented for every operator category (EV-55–61), CLI flag added (EV-74), MCP schema updated (EV-75), and docs written (EV-76).","dependencies":[{"issue_id":"EV-31","depends_on_id":"EV-55","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-56","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-57","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-58","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-59","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-60","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-61","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-74","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-75","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-31","depends_on_id":"EV-76","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-32","title":"Epic: Zero-friction Defaults","description":"Make evilution work well with zero configuration. Auto-detect what to mutate and which specs to run based on git state and file conventions.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:06.843446356+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T10:11:01.311639679+07:00","closed_at":"2026-03-16T10:11:01.311639679+07:00","close_reason":"Already merged and released in v0.4.0","dependencies":[{"issue_id":"EV-32","depends_on_id":"EV-33","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-32","depends_on_id":"EV-34","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-33","title":"Auto-detect changed files from git merge base","description":"When evilution is run with no file arguments, default to mutating files changed since the merge base of the current branch (git merge-base HEAD main). This makes 'evilution run --format json' just work in a feature branch without specifying files. Should be skippable if explicit files are provided.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:08.235421922+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T10:11:01.311622041+07:00","closed_at":"2026-03-16T10:11:01.311622041+07:00","close_reason":"Already merged and released in v0.4.0"}
 {"id":"EV-34","title":"Convention-based spec file resolution","description":"Implement a mapping from source files to their spec files using Ruby/RSpec conventions: lib/foo/bar.rb -> spec/foo/bar_spec.rb, app/models/user.rb -> spec/models/user_spec.rb. This is a foundational piece used by both zero-friction defaults (auto-detect specs) and per-mutation spec targeting (run only relevant specs). Should handle common Rails and gem layouts.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-10T06:18:09.380269033+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-16T10:11:01.311627178+07:00","closed_at":"2026-03-16T10:11:01.311627178+07:00","close_reason":"Already merged and released in v0.4.0"}
@@ -110,14 +110,14 @@
 {"id":"EV-54.5","title":"Add always-matching regexp variant","description":"Currently regexp only mutates to never-matching /a\\A/. Add always-matching /.*/ variant to test both match and no-match code paths.","status":"closed","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-19T21:21:21.049402671+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-21T10:05:45.034075069+07:00","closed_at":"2026-03-21T10:05:45.034075069+07:00","close_reason":"Added always-matching /.*/ variant alongside never-matching /a\\A/. Each regexp now produces 2 mutations. 731 specs pass, 100% mutation score.","external_ref":"gh-171","dependencies":[{"issue_id":"EV-54.5","depends_on_id":"EV-54","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-54.6","title":"Expand ArithmeticReplacement with bitwise shift operators","description":"Add <<→>> swap. Niche but catches bitwise shift bugs. Lowest priority in this epic.","status":"closed","priority":4,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-19T21:21:21.152296396+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-21T01:03:32.687774444+07:00","closed_at":"2026-03-21T01:03:32.687774444+07:00","close_reason":"Added << >> bitwise shift swap to ArithmeticReplacement operator. 714 specs passing, 100% mutation score.","external_ref":"gh-172","dependencies":[{"issue_id":"EV-54.6","depends_on_id":"EV-54","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-54.7","title":"Operator: ArgumentNilSubstitution","description":"Replace each method argument with nil, one at a time. E.g. foo(a, b) → foo(nil, b) and foo(a, nil). Works for single-arg calls too (unlike ArgumentRemoval which requires 2+). This catches 'default value' bugs where a method has a sensible fallback for nil — e.g. I18n.with_locale(user.locale) → I18n.with_locale(nil) silently falls back to default locale. Identified from real-world feedback where mutant caught a locale test gap that evilution missed (v0.7.0).","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-19T22:09:42.995246472+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-20T23:43:12.098455761+07:00","closed_at":"2026-03-20T23:43:12.098455761+07:00","close_reason":"Implemented ArgumentNilSubstitution operator. Replaces each argument with nil one at a time, works for single-arg calls too (unlike ArgumentRemoval). Skips splat, keyword, block, and forwarding args. 12 specs passing, 705 total.","external_ref":"gh-175","dependencies":[{"issue_id":"EV-54.7","depends_on_id":"EV-54","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]}
-{"id":"EV-55","title":"Concrete suggestions: Comparison & Arithmetic operators","description":"Generate concrete RSpec it blocks for ComparisonReplacement and ArithmeticReplacement mutations. Test should assert exact return value at boundary conditions.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.26716126+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.26716126+07:00"}
-{"id":"EV-56","title":"Concrete suggestions: Boolean operators","description":"Generate concrete RSpec it blocks for BooleanOperatorReplacement, BooleanLiteralReplacement, and NegationInsertion mutations. Test should assert true/false explicitly.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.370014645+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.370014645+07:00"}
-{"id":"EV-57","title":"Concrete suggestions: Literal operators","description":"Generate concrete RSpec it blocks for IntegerLiteral, FloatLiteral, StringLiteral, and SymbolLiteral mutations. Test should assert exact value returned.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.473990949+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.473990949+07:00"}
-{"id":"EV-58","title":"Concrete suggestions: Collection operators","description":"Generate concrete RSpec it blocks for ArrayLiteral, HashLiteral, and CollectionReplacement mutations. Test should assert contents or size.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.577189348+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.577189348+07:00"}
-{"id":"EV-59","title":"Concrete suggestions: Conditional operators","description":"Generate concrete RSpec it blocks for ConditionalNegation and ConditionalBranch mutations. Test should exercise both branches.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.676644345+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.676644345+07:00"}
+{"id":"EV-55","title":"Concrete suggestions: Comparison & Arithmetic operators","description":"Generate concrete RSpec it blocks for ComparisonReplacement and ArithmeticReplacement mutations. Test should assert exact return value at boundary conditions.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.26716126+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T16:37:54.589252928+07:00","closed_at":"2026-03-22T16:37:54.589252928+07:00","close_reason":"Implemented concrete RSpec suggestions for comparison_replacement and arithmetic_replacement operators using Option A (enriched centralized module with lambdas in CONCRETE_TEMPLATES hash)"}
+{"id":"EV-56","title":"Concrete suggestions: Boolean operators","description":"Generate concrete RSpec it blocks for BooleanOperatorReplacement, BooleanLiteralReplacement, and NegationInsertion mutations. Test should assert true/false explicitly.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.370014645+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T16:45:46.097533929+07:00","closed_at":"2026-03-22T16:45:46.097533929+07:00","close_reason":"Added concrete RSpec suggestion lambdas for boolean_operator_replacement, boolean_literal_replacement, and negation_insertion operators in CONCRETE_TEMPLATES"}
+{"id":"EV-57","title":"Concrete suggestions: Literal operators","description":"Generate concrete RSpec it blocks for IntegerLiteral, FloatLiteral, StringLiteral, and SymbolLiteral mutations. Test should assert exact value returned.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.473990949+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T16:49:40.666070785+07:00","closed_at":"2026-03-22T16:49:40.666070785+07:00","close_reason":"Added concrete RSpec suggestion lambdas for integer_literal, float_literal, string_literal, and symbol_literal operators in CONCRETE_TEMPLATES"}
+{"id":"EV-58","title":"Concrete suggestions: Collection operators","description":"Generate concrete RSpec it blocks for ArrayLiteral, HashLiteral, and CollectionReplacement mutations. Test should assert contents or size.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.577189348+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T16:55:27.552776823+07:00","closed_at":"2026-03-22T16:55:27.552776823+07:00","close_reason":"Added concrete RSpec suggestion lambdas for array_literal, hash_literal, and collection_replacement operators. Also excluded suggestion.rb from ClassLength rubocop check since it's data-heavy."}
+{"id":"EV-59","title":"Concrete suggestions: Conditional operators","description":"Generate concrete RSpec it blocks for ConditionalNegation and ConditionalBranch mutations. Test should exercise both branches.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.676644345+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:01:30.626874811+07:00","closed_at":"2026-03-22T17:01:30.626874811+07:00","close_reason":"Added concrete RSpec suggestion lambdas for conditional_negation and conditional_branch operators in CONCRETE_TEMPLATES"}
 {"id":"EV-6","title":"Fix pool fork tests hanging in CI and WSL2","description":"The spec/evilution/parallel/pool_spec.rb fork-based tests hang on both WSL2 and GitHub Actions. CI currently excludes them via --exclude-pattern. Root cause is likely double-fork (Pool forks workers, each Worker uses Isolation::Fork which forks again) causing pipe/process management issues. Needs investigation and fix so pool tests run reliably in CI.","status":"closed","priority":1,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T16:21:43.62587758+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-05T12:31:51.831163433+07:00","closed_at":"2026-03-05T12:31:51.831163433+07:00","close_reason":"Closed"}
-{"id":"EV-60","title":"Concrete suggestions: Structural operators","description":"Generate concrete RSpec it blocks for StatementDeletion, MethodBodyReplacement, ReturnValueRemoval, and MethodCallRemoval mutations. Test should depend on side effect or return value.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.777078104+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.777078104+07:00"}
-{"id":"EV-61","title":"Concrete suggestions: Nil operator","description":"Generate concrete RSpec it block for NilReplacement mutations. Test should assert non-nil return value.","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.882878252+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T09:58:33.882878252+07:00"}
+{"id":"EV-60","title":"Concrete suggestions: Structural operators","description":"Generate concrete RSpec it blocks for StatementDeletion, MethodBodyReplacement, ReturnValueRemoval, and MethodCallRemoval mutations. Test should depend on side effect or return value.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.777078104+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:06:40.998608577+07:00","closed_at":"2026-03-22T17:06:40.998608577+07:00","close_reason":"Added concrete RSpec suggestion lambdas for statement_deletion, method_body_replacement, return_value_removal, and method_call_removal operators in CONCRETE_TEMPLATES"}
+{"id":"EV-61","title":"Concrete suggestions: Nil operator","description":"Generate concrete RSpec it block for NilReplacement mutations. Test should assert non-nil return value.","design":"Use Option A (enriched centralized module): Convert the static TEMPLATES entry in Reporter::Suggestion to a lambda/proc that receives the Mutation object and returns concrete RSpec code. Use mutation.original_source, mutation.mutated_source, and mutation.subject metadata to interpolate actual values into the generated test. When suggest_tests is off, return existing static text; when on, return concrete RSpec it-block.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T09:58:33.882878252+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:13:11.879236112+07:00","closed_at":"2026-03-22T17:13:11.879236112+07:00","close_reason":"Added concrete RSpec suggestion lambda for nil_replacement operator in CONCRETE_TEMPLATES. This completes all concrete suggestion issues (EV-55 through EV-61)."}
 {"id":"EV-62","title":"Neutral mutation detection","description":"Run the original unmutated code once before mutation testing. Flag any tests that already fail, so surviving mutants caused by pre-broken tests are reported as neutral rather than gaps. Eliminates false positives in mutation score.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:03.670730866+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T23:16:28.920679692+07:00","closed_at":"2026-03-17T23:16:28.920679692+07:00","close_reason":"Merged"}
 {"id":"EV-63","title":"In-process mutation for performance","description":"Replace fork+file-write isolation with in-memory mutation (constant replacement or load-path override) for the common case. Current approach: 3.0 mutations/s vs mutant's 17.6 mutations/s (6x slower). Fork overhead is the main bottleneck. Keep fork as fallback for safety.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:03.765021194+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-18T18:31:15.344270883+07:00","closed_at":"2026-03-18T18:31:15.344270883+07:00","close_reason":"GH issue #114 closed, PR #123 merged"}
 {"id":"EV-64","title":"Class-level --target filtering","description":"Extend --target to accept class names without method (e.g. --target Game) to mutate all methods in the class. Currently only supports fully-qualified method names like Game#method.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:03.858147999+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-19T21:31:38.601679951+07:00","closed_at":"2026-03-19T21:31:38.601679951+07:00","close_reason":"Implemented class-level --target filtering with 3 new specs, 100% mutation score"}
@@ -125,7 +125,7 @@
 {"id":"EV-66","title":"Scope-aware spec resolution","description":"Improve convention-based spec resolution for nested modules. When a method is nested in a module, prefer spec/models/game_spec.rb over a generic match. Handle edge cases in app/ directory structures.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:04.04579177+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-19T22:15:01.15206232+07:00","closed_at":"2026-03-19T22:15:01.15206232+07:00","close_reason":"Implemented parent-path fallback in SpecResolver for nested module spec resolution"}
 {"id":"EV-67","title":"HTML report with visual mutation map","description":"Generate an HTML report showing which lines are well-tested vs vulnerable. Visual mutation map per file with color-coded coverage.","status":"closed","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:04.13552276+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-20T23:58:29.045246978+07:00","closed_at":"2026-03-20T23:58:29.045246978+07:00","close_reason":"Implemented HTML reporter with visual mutation map. Self-contained HTML with inline CSS (dark theme), per-file mutation maps with color-coded lines (green=killed, red=survived, yellow=timeout), expandable survived mutation details with diffs and suggestions. Writes to evilution-report.html. 17 reporter specs, 724 total passing."}
 {"id":"EV-68","title":"Equivalent mutation detection","description":"Add heuristics to skip mutations that produce provably identical behavior (dead code paths, no-op transformations). Reduces noise in mutation results.","status":"closed","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:04.226297798+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-21T00:22:25.796367972+07:00","closed_at":"2026-03-21T00:22:25.796367972+07:00","close_reason":"Implemented equivalent mutation detection with 4 heuristics: NoopSource (identical source), MethodBodyNil (empty/nil method bodies), AliasSwap (detect/find, length/size, collect/map), DeadCode (unreachable code after return/raise). Integrated into runner pipeline, reporters (CLI/JSON/HTML), and MCP tool. Equivalents excluded from score denominator. 100% mutation score (211/211). 753 total specs passing."}
-{"id":"EV-69","title":"Minitest integration","description":"Add Minitest support alongside existing RSpec integration. Broader ecosystem support for non-RSpec projects.","status":"open","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:04.313129974+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-17T10:15:04.313129974+07:00"}
+{"id":"EV-69","title":"Minitest integration","description":"Epic: Add Minitest support alongside existing RSpec integration. RSpec is currently deeply coupled across 12 files (integration, baseline, spec_resolver, runner, config, cli, suggestions, MCP tool). This epic introduces a test framework abstraction layer and implements Minitest as the first alternative integration.","status":"open","priority":4,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-17T10:15:04.313129974+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:27:58.96045095+07:00"}
 {"id":"EV-7","title":"Enable true per-mutation isolation with temp file copies","description":"Currently all mutations for the same file go to one worker (PR #4 fix). This means single-file projects get no parallelism benefit. Implement temp file copy approach: each worker copies the source file to a temp location, mutates the copy, and runs tests against it. This enables safe parallel mutation of the same file across multiple workers.","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T16:21:46.820210376+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-06T11:46:55.740292929+07:00","closed_at":"2026-03-06T11:46:55.740292929+07:00","close_reason":"Already merged in PR #20"}
 {"id":"EV-70","title":"Epic: Fix memory leaks and add memory observability","description":"Evilution processes consume up to 17.2 GB each due to memory leaks. This epic covers: (1) identifying and fixing root causes — double forking, upfront mutation array, source string retention in results, Marshal round-trips; (2) adding runtime memory instrumentation behind --verbose; (3) adding memory budget specs to catch regressions in CI.","status":"closed","priority":1,"issue_type":"epic","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-18T18:51:39.345459861+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-19T14:34:58.765114612+07:00","closed_at":"2026-03-19T14:34:58.765114612+07:00","close_reason":"All 14 sub-issues complete. Memory leaks fixed, observability added, rake memory:check in place for regression detection.","external_ref":"gh-124","labels":["v0.7.0"]}
 {"id":"EV-70.1","title":"Add RSS memory measurement utility","description":"Create a lightweight Memory module that reads RSS from /proc/$$/status (Linux) with no gem dependencies. Provide Memory.rss_mb method returning current process RSS in MB. This is the foundation for all other memory instrumentation.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-18T18:51:45.894741371+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-18T19:02:42.603502332+07:00","closed_at":"2026-03-18T19:02:42.603502332+07:00","close_reason":"Implemented Memory module with rss_kb, rss_mb, rss_kb_for(pid), and delta methods. 8 specs passing.","external_ref":"gh-125","labels":["v0.7.0"],"dependencies":[{"issue_id":"EV-70.1","depends_on_id":"EV-70","type":"parent-child","created_at":"0001-01-01T00:00:00Z"}]}
@@ -145,5 +145,17 @@
 {"id":"EV-71","title":"Trim MCP tool response to reduce context window usage","description":"The evilution MCP tool returns full JSON report with all killed mutation diffs (~10k tokens). Only survived mutations are actionable. Trim killed/neutral/timed_out/errors detail arrays in MutateTool.call, keeping summary counts and survived details only.","status":"closed","priority":1,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-19T23:23:32.672265145+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-19T23:31:18.511115181+07:00","closed_at":"2026-03-19T23:31:18.511115181+07:00","close_reason":"Trim killed/neutral/timed_out/errors detail arrays from MCP tool response, keeping only summary and survived details","external_ref":"marinazzio/evilution#178"}
 {"id":"EV-72","title":"Add verbosity control to MCP tool response","description":"Add a verbosity parameter (full/summary/minimal) to the MCP tool to control response size. Default to summary for best context efficiency. Full keeps all entries without diffs, summary omits killed/neutral arrays, minimal keeps only summary + survived.","status":"closed","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-19T23:41:41.837080367+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-21T01:16:09.980410196+07:00","closed_at":"2026-03-21T01:16:09.980410196+07:00","close_reason":"Added verbosity parameter (full/summary/minimal) to MCP tool. Default is summary which omits killed/neutral/equivalent arrays. 718 specs passing, 100% mutation score. Updated README.","external_ref":"marinazzio/evilution#179"}
 {"id":"EV-73","title":"Clean up deprecated CLI switches and config options","description":"Remove long-deprecated --diff, --no-coverage flags and coverage config option. GH #176.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-21T00:37:09.266487789+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-21T00:49:24.827479374+07:00","closed_at":"2026-03-21T00:49:24.827479374+07:00","close_reason":"Removed deprecated --diff, --no-coverage CLI flags; removed diff_base, coverage, diff? from Config; removed filter_by_diff from Runner; deleted diff/parser, diff/file_filter, coverage/collector, coverage/test_map and their specs; cleaned up requires. 712 specs passing.","external_ref":"gh-176"}
+{"id":"EV-74","title":"Add --suggest-tests CLI flag to enable concrete test suggestions","description":"Add a --suggest-tests CLI flag and Config option (default: false) that gates whether suggestions use static templates or concrete RSpec test code. GH #209","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T10:24:05.280617605+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T10:30:31.273675421+07:00","closed_at":"2026-03-22T10:30:31.273675421+07:00","close_reason":"Added --suggest-tests CLI flag, Config attribute, predicate method, and default template entry. 737 specs pass, no rubocop offenses."}
+{"id":"EV-75","title":"Add suggest_tests parameter to MCP tool schema","description":"Add suggest_tests boolean parameter to evilution-mutate MCP tool input schema so AI agents can opt into concrete test suggestions. GH #210","status":"closed","priority":2,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T10:24:06.101977203+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T10:45:56.197750084+07:00","closed_at":"2026-03-22T10:45:56.197750084+07:00","close_reason":"Added suggest_tests boolean parameter to MCP tool input schema, passed through to Config. 739 specs pass, rubocop clean, 100% mutation score.","dependencies":[{"issue_id":"EV-75","depends_on_id":"EV-74","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-76","title":"Document --suggest-tests flag for AI agent consumers","description":"Update CLI help, MCP tool description, and README to document the suggest_tests capability for both human and AI agent consumers. GH #211","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T10:24:07.258670935+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T10:55:17.076339069+07:00","closed_at":"2026-03-22T10:55:17.076339069+07:00","close_reason":"Documented --suggest-tests flag in README (CLI options table, config example, MCP section, workflow guidance) and enhanced MCP tool description for agent discoverability. 739 specs pass, rubocop clean, 100% mutation score.","dependencies":[{"issue_id":"EV-76","depends_on_id":"EV-74","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-76","depends_on_id":"EV-75","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-77","title":"Refactor: Replace extract_diff_lines tuple return with a struct or named accessors","description":"The Suggestion.extract_diff_lines method returns a two-element array [original_line, mutated_line], which is then destructured at every call site in CONCRETE_TEMPLATES. Replace with a struct or object with named accessors for clarity and to avoid positional coupling.","notes":"GitHub issue: #222","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:13:20.688409572+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:19:56.805536144+07:00"}
+{"id":"EV-78","title":"Abstract test framework interface in Integration::Base","description":"Extract Integration::Base into a proper strategy pattern with run_tests, build_args, reset_state methods. The current Integration::RSpec hard-codes RSpec::Core::Runner.run() and RSpec.reset. Define abstract methods that any test framework integration must implement.","notes":"GitHub issue: #223","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:15.862336424+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:30.068127772+07:00","dependencies":[{"issue_id":"EV-78","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-79","title":"Implement Integration::Minitest class","description":"Create Integration::Minitest implementing the test framework interface. Must handle Minitest::Runnable.run, test execution, and pass/fail detection via exit codes. Should support both minitest and minitest-reporters.","notes":"GitHub issue: #224","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:19.881523481+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:33.447325403+07:00","dependencies":[{"issue_id":"EV-79","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-79","depends_on_id":"EV-78","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-8","title":"Investigate RSpec state accumulation across mutation runs","description":"RSpec.reset is called between mutations but loaded spec files persist in memory. Long mutation runs may accumulate state from previously loaded specs, potentially causing false positives/negatives. Investigate whether RSpec::Core::Runner.run properly isolates between runs or if additional cleanup is needed.","status":"closed","priority":2,"issue_type":"bug","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T16:21:48.618669476+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-05T11:57:56.965910759+07:00","closed_at":"2026-03-05T11:57:56.965910759+07:00","close_reason":"Investigation complete: fork isolation already prevents state accumulation. Added documentation explaining the guarantee and tests verifying independent consecutive runs."}
+{"id":"EV-80","title":"Support Minitest file discovery in SpecResolver","description":"SpecResolver currently assumes _spec.rb suffix and spec/ directory. Add support for Minitest conventions: test/ directory, *_test.rb suffix. Make discovery strategy configurable based on the chosen integration.","notes":"GitHub issue: #225","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:24.214856109+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:39.343862681+07:00","dependencies":[{"issue_id":"EV-80","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-81","title":"Abstract baseline runner from RSpec","description":"baseline.rb hard-codes require 'rspec/core', RSpec.reset, and RSpec::Core::Runner.run. Refactor to use the Integration interface so baseline verification works with any test framework.","notes":"GitHub issue: #226","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:28.362534837+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:41.1884433+07:00","dependencies":[{"issue_id":"EV-81","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-81","depends_on_id":"EV-78","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-82","title":"Add --integration CLI flag and config support for Minitest","description":"Config currently defaults to integration: :rspec with no alternative. Add integration: :minitest option in .evilution.yml and --integration CLI flag. Update config template and validation.","notes":"GitHub issue: #227","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:33.571806703+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:43.084294853+07:00","dependencies":[{"issue_id":"EV-82","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-83","title":"Plugin-based runner dispatch for test integrations","description":"Runner currently uses a case statement with only 'when :rspec'. Refactor to a registry/plugin mechanism that resolves the integration class from config.integration. Also update module loading in evilution.rb to conditionally require integrations.","notes":"GitHub issue: #228","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:40.5256819+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:54.689064249+07:00","dependencies":[{"issue_id":"EV-83","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-83","depends_on_id":"EV-78","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-84","title":"Minitest concrete suggestion templates","description":"All 16 CONCRETE_TEMPLATES in Reporter::Suggestion generate RSpec it/expect blocks. Add parallel Minitest templates using assert_equal style. suggestion_for should select the right template set based on the configured integration.","notes":"GitHub issue: #229","status":"open","priority":3,"issue_type":"feature","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:41.5343649+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:28:59.242395265+07:00","dependencies":[{"issue_id":"EV-84","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-84","depends_on_id":"EV-79","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
+{"id":"EV-85","title":"Update documentation for Minitest support","description":"Update CLI help text, MCP tool descriptions, and README to reflect Minitest as a supported integration. Currently --suggest-tests and MCP tool explicitly say 'RSpec'. Make descriptions framework-aware or generic.","notes":"GitHub issue: #230","status":"open","priority":3,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-22T17:28:51.219728494+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-22T17:29:06.644497418+07:00","dependencies":[{"issue_id":"EV-85","depends_on_id":"EV-69","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-85","depends_on_id":"EV-79","type":"blocks","created_at":"0001-01-01T00:00:00Z"},{"issue_id":"EV-85","depends_on_id":"EV-82","type":"blocks","created_at":"0001-01-01T00:00:00Z"}]}
 {"id":"EV-9","title":"Add multi-Ruby CI test matrix (3.2, 3.3, 4.0)","description":"CI currently only tests Ruby 4.0.1. Add a matrix strategy testing Ruby 3.2, 3.3, and 4.0 to ensure compatibility across supported Ruby versions. Prism ships with Ruby 3.3+ so 3.2 may need the prism gem as a dependency.","status":"closed","priority":2,"issue_type":"task","owner":"denis.kiselyov@gmail.com","created_at":"2026-03-02T16:21:51.239774764+07:00","created_by":"Denis Kiselev","updated_at":"2026-03-05T12:31:51.83181612+07:00","closed_at":"2026-03-05T12:31:51.83181612+07:00","close_reason":"Closed"}

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.12.0] - 2026-03-22
+
+### Added
+
+- **Concrete RSpec test suggestions** (`--suggest-tests`) — surviving mutants now include ready-to-use RSpec `it` blocks instead of generic guidance; covers all operator families: arithmetic, comparison, boolean, literal, collection, conditional, structural, and nil operators (#209, #215, #216, #217, #218, #219, #220, #221)
+- **MCP tool `suggest_tests` parameter** — enables concrete test suggestions in MCP tool responses (#213)
+
+### Changed
+
+- **RuboCop configuration cleanup** — added metrics targets and refactored cop values/exclusions (#204, #207)
+
 ## [0.11.0] - 2026-03-21
 
 ### Added

data/README.md

@@ -48,6 +48,7 @@ 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. |
 | `-q`, `--quiet`         | Boolean | false        | Suppress output.                                   |
 
 ### Exit Codes
@@ -65,10 +66,11 @@ Generate default config: `bundle exec evilution init`
 Creates `.evilution.yml`:
 
 ```yaml
-# timeout: 10        # seconds per mutation
-# format: text       # text | json
-# min_score: 0.0     # 0.0–1.0
-# integration: rspec # test framework
+# timeout: 10           # seconds per mutation
+# format: text          # text | json
+# min_score: 0.0        # 0.0–1.0
+# integration: rspec    # test framework
+# suggest_tests: false  # concrete RSpec test code in suggestions
 ```
 
 **Precedence**: CLI flags override `.evilution.yml` values.
@@ -172,6 +174,12 @@ The MCP tool accepts a `verbosity` parameter to control response size:
 
 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.
 
+### 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.
+
+Pass `suggest_tests: true` in the MCP tool call, or use `--suggest-tests` on the CLI, to activate this mode.
+
 > **Note**: `.mcp.json` is gitignored by default since it is a local editor/agent configuration file.
 
 ## Recommended Workflows for AI Agents
@@ -234,7 +242,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
+3. Read `suggestion` for a hint on what test to write (use `--suggest-tests` for concrete RSpec 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
 

data/lib/evilution/cli.rb

@@ -122,6 +122,7 @@ module Evilution
       opts.on("--incremental", "Cache killed/timeout results; skip re-running them on unchanged files") { @options[:incremental] = true }
       opts.on("--isolation STRATEGY", "Isolation: auto, fork, in_process (default: auto)") { |s| @options[:isolation] = s }
       opts.on("--stdin", "Read target file paths from stdin (one per line)") { @options[:stdin] = true }
+      opts.on("--suggest-tests", "Generate concrete RSpec test code in suggestions") { @options[:suggest_tests] = true }
       opts.on("-v", "--verbose", "Verbose output") { @options[:verbose] = true }
       opts.on("-q", "--quiet", "Suppress output") { @options[:quiet] = true }
     end

data/lib/evilution/config.rb

@@ -19,13 +19,15 @@ module Evilution
       baseline: true,
       isolation: :auto,
       incremental: false,
+      suggest_tests: false,
       line_ranges: {},
       spec_files: []
     }.freeze
 
     attr_reader :target_files, :timeout, :format,
                 :target, :min_score, :integration, :verbose, :quiet,
-                :jobs, :fail_fast, :baseline, :isolation, :incremental, :line_ranges, :spec_files
+                :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
+                :line_ranges, :spec_files
 
     def initialize(**options)
       file_options = options.delete(:skip_config_file) ? {} : load_config_file
@@ -66,6 +68,10 @@ module Evilution
       incremental
     end
 
+    def suggest_tests?
+      suggest_tests
+    end
+
     def self.file_options
       CONFIG_FILES.each do |path|
         next unless File.exist?(path)
@@ -104,6 +110,9 @@ module Evilution
 
         # Stop after N surviving mutants (default: disabled)
         # fail_fast: 1
+
+        # Generate concrete RSpec test code in suggestions (default: false)
+        # suggest_tests: false
       YAML
     end
 
@@ -134,6 +143,7 @@ module Evilution
       @baseline = merged[:baseline]
       @isolation = validate_isolation(merged[:isolation])
       @incremental = merged[:incremental]
+      @suggest_tests = merged[:suggest_tests]
       @line_ranges = merged[:line_ranges] || {}
       @spec_files = Array(merged[:spec_files])
     end

data/lib/evilution/mcp/mutate_tool.rb

@@ -8,9 +8,10 @@ require_relative "../reporter/json"
 
 module Evilution
   module MCP
-    class MutateTool < ::MCP::Tool # rubocop:disable Metrics/ClassLength
+    class MutateTool < ::MCP::Tool
       tool_name "evilution-mutate"
-      description "Run mutation testing on Ruby source files"
+      description "Run mutation testing on Ruby source files. " \
+                  "Use suggest_tests: true to get concrete RSpec test code for surviving mutants."
       input_schema(
         properties: {
           files: {
@@ -39,6 +40,11 @@ module Evilution
             items: { type: "string" },
             description: "Spec files to run (overrides auto-detection)"
           },
+          suggest_tests: {
+            type: "boolean",
+            description: "When true, suggestions for survived mutants include concrete RSpec test code " \
+                         "instead of static description text (default: false)"
+          },
           verbosity: {
             type: "string",
             enum: %w[full summary minimal],
@@ -50,9 +56,12 @@ module Evilution
       )
 
       class << self
-        def call(server_context:, files: [], target: nil, timeout: nil, jobs: nil, fail_fast: nil, spec: nil, verbosity: nil) # rubocop:disable Lint/UnusedMethodArgument
+        # rubocop:disable Lint/UnusedMethodArgument,Metrics/ParameterLists
+        def call(server_context:, files: [], target: nil, timeout: nil, jobs: nil,
+                 fail_fast: nil, spec: nil, suggest_tests: nil, verbosity: nil)
           parsed_files, line_ranges = parse_files(Array(files))
-          config_opts = build_config_opts(parsed_files, line_ranges, target, timeout, jobs, fail_fast, spec)
+          config_opts = build_config_opts(parsed_files, line_ranges, target, timeout, jobs, fail_fast, spec,
+                                          suggest_tests)
           config = Config.new(**config_opts)
           runner = Runner.new(config: config)
           summary = runner.call
@@ -64,6 +73,7 @@ module Evilution
           error_payload = build_error_payload(e)
           ::MCP::Tool::Response.new([{ type: "text", text: ::JSON.generate(error_payload) }], error: true)
         end
+        # rubocop:enable Lint/UnusedMethodArgument,Metrics/ParameterLists
 
         VALID_VERBOSITIES = %w[full summary minimal].freeze
 
@@ -98,13 +108,14 @@ module Evilution
           raise ParseError, "invalid line range: #{str.inspect}"
         end
 
-        def build_config_opts(files, line_ranges, target, timeout, jobs, fail_fast, spec)
+        def build_config_opts(files, line_ranges, target, timeout, jobs, fail_fast, spec, suggest_tests)
           opts = { target_files: files, line_ranges: line_ranges, format: :json, quiet: true, skip_config_file: true }
           opts[:target] = target if target
           opts[:timeout] = timeout if timeout
           opts[:jobs] = jobs if jobs
           opts[:fail_fast] = fail_fast if fail_fast
           opts[:spec_files] = spec if spec
+          opts[:suggest_tests] = true if suggest_tests
           opts
         end
 

data/lib/evilution/reporter/html.rb

@@ -5,7 +5,7 @@ require_relative "suggestion"
 
 module Evilution
   module Reporter
-    class HTML # rubocop:disable Metrics/ClassLength
+    class HTML
       def initialize
         @suggestion = Suggestion.new
       end

data/lib/evilution/reporter/suggestion.rb

@@ -26,8 +26,263 @@ module Evilution
         "argument_removal" => "Add a test that verifies the correct arguments are passed to this method call"
       }.freeze
 
+      CONCRETE_TEMPLATES = {
+        "comparison_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the correct result at the comparison boundary in ##{method_name}' do
+              # Test with values where the original operator and mutated operator
+              # produce different results (e.g., equal values for > vs >=)
+              result = subject.#{method_name}(boundary_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "arithmetic_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'computes the correct arithmetic result in ##{method_name}' do
+              # Assert the exact numeric result, not just truthiness or sign
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "boolean_operator_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the correct result when one condition is true and one is false in ##{method_name}' do
+              # Use inputs where only one operand is truthy to distinguish && from ||
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "boolean_literal_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the expected boolean value from ##{method_name}' do
+              # Assert the exact true/false/nil value, not just truthiness
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "negation_insertion" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the correct boolean from the predicate in ##{method_name}' do
+              # Assert the exact true/false result, not just truthiness
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(true).or eq(false)
+            end
+          RSPEC
+        },
+        "integer_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the exact integer value from ##{method_name}' do
+              # Assert the exact numeric value, not just > 0 or truthy
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "float_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the exact float value from ##{method_name}' do
+              # Assert the exact floating-point result
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "string_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the exact string content from ##{method_name}' do
+              # Assert the exact string value, not just presence or non-empty
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "symbol_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the exact symbol from ##{method_name}' do
+              # Assert the exact symbol value, not just that it is a Symbol
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "array_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the expected array contents from ##{method_name}' do
+              # Assert the exact array elements, not just non-empty or truthy
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "hash_literal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'returns the expected hash contents from ##{method_name}' do
+              # Assert the exact keys and values, not just non-empty or truthy
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "collection_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'uses the return value of the collection operation in ##{method_name}' do
+              # Assert the return value of the collection method, not just side effects
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "conditional_negation" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'exercises both branches of the conditional in ##{method_name}' do
+              # Test with inputs that make the condition true AND false
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "conditional_branch" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'exercises the removed branch of the conditional in ##{method_name}' do
+              # Test with inputs that trigger the branch removed by this mutation
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "statement_deletion" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, _mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: deleted `#{original_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'depends on the side effect of the deleted statement in ##{method_name}' do
+              # Assert a side effect or return value that changes when this statement is removed
+              subject.#{method_name}(input_value)
+              expect(observable_side_effect).to eq(expected)
+            end
+          RSPEC
+        },
+        "method_body_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'verifies the return value or side effects of ##{method_name}' do
+              # Assert the method produces a meaningful result, not just nil
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "return_value_removal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'uses the return value of ##{method_name}' do
+              # Assert the caller depends on the return value, not just side effects
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "method_call_removal" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'depends on the return value or side effect of the call in ##{method_name}' do
+              # Assert the method call's effect is observable
+              result = subject.#{method_name}(input_value)
+              expect(result).to eq(expected)
+            end
+          RSPEC
+        },
+        "nil_replacement" => lambda { |mutation|
+          method_name = parse_method_name(mutation.subject.name)
+          original_line, mutated_line = extract_diff_lines(mutation.diff)
+          <<~RSPEC.strip
+            # Mutation: changed `#{original_line}` to `#{mutated_line}` in #{mutation.subject.name}
+            # #{mutation.file_path}:#{mutation.line}
+            it 'asserts the nil return value from ##{method_name}' do
+              # Assert the method returns nil, not a substituted value
+              result = subject.#{method_name}(input_value)
+              expect(result).to be_nil
+            end
+          RSPEC
+        }
+      }.freeze
+
       DEFAULT_SUGGESTION = "Add a more specific test that detects this mutation"
 
+      def initialize(suggest_tests: false)
+        @suggest_tests = suggest_tests
+      end
+
       # Generate suggestions for survived mutations.
       #
       # @param summary [Result::Summary]
@@ -46,8 +301,26 @@ module Evilution
       # @param mutation [Mutation]
       # @return [String]
       def suggestion_for(mutation)
+        if @suggest_tests
+          concrete = CONCRETE_TEMPLATES[mutation.operator_name]
+          return concrete.call(mutation) if concrete
+        end
+
         TEMPLATES.fetch(mutation.operator_name, DEFAULT_SUGGESTION)
       end
+
+      class << self
+        def parse_method_name(subject_name)
+          subject_name.split(/[#.]/).last
+        end
+
+        def extract_diff_lines(diff)
+          lines = diff.split("\n")
+          original = lines.find { |l| l.start_with?("- ") }
+          mutated = lines.find { |l| l.start_with?("+ ") }
+          [original&.sub(/^- /, "")&.strip, mutated&.sub(/^\+ /, "")&.strip]
+        end
+      end
     end
   end
 end

data/lib/evilution/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Evilution
-  VERSION = "0.11.2"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.11.2
+  version: 0.12.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-21 00:00:00.000000000 Z
+date: 2026-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs