evilution 0.34.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 005b0edbf9ced13a00a85d07939564cec9f38d93dec0e1d923f30a9d7cb2c779
-  data.tar.gz: a7554571383f34fd21ca7d8d61f733e446d1d2c6349816267459b19309605689
+  metadata.gz: 26a7a721749a19cb1f10d77b46a9d78d394ce5c112ba5d5fab8963de4a1a5f14
+  data.tar.gz: 65ee839279c74e07dd84d153015bfff6e29daf56d87929da75991fdef67e49c5
 SHA512:
-  metadata.gz: 6227ee0e3df976329f59f286b21cfaa69bbd4455d00a1fe37dc4c77a9ff553f9e2c4fa7e112b7b19d7e6cc45c5ef2f98ccb2e03f7733fbd97ff7be6ad8582c71
-  data.tar.gz: e4a36d7eaa5826c8621d042beb1bedb7c612a67118b4456a909caa1f813bb0863098b57e113684faf9a8797ac0993f2d2d2ee2ee92562376c6e3a35cbb92ecad
+  metadata.gz: 587598737cb636180b40cfb2466ecd0aac34c827eddb5432b543fc33b2b7e94b2e5b2a03915598fb9c41e9174bab8baad06ffab620f4174d8f686f9173f8fd1b
+  data.tar.gz: 85be8b922c45fab5e0e50fd8f17a6d5a572a9b9a2139181f0ca0283dc52c241bcd54b512e0cb3a5be9588edc31cd8b46fedd10437e8caf0c3e3104229c1f7127

data/.beads/interactions.jsonl

@@ -437,3 +437,14 @@
 {"id":"int-555de29c","kind":"field_change","created_at":"2026-06-16T07:54:17.438977358Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"in_progress","old_value":"open"}}
 {"id":"int-616ccd27","kind":"field_change","created_at":"2026-06-16T09:31:30.217250542Z","actor":"Denis Kiselev","issue_id":"EV-z03y","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Merged via PR #1375 (master). Dep on EV-rxob is provenance only; code fix shipped."}}
 {"id":"int-6d2f9b35","kind":"field_change","created_at":"2026-06-16T10:00:18.493013642Z","actor":"Denis Kiselev","issue_id":"EV-rxob","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"1.0 real-world validation complete. Rounds 2-4 ran 30+ gems across rspec/minitest/test-unit; no crash/memory blowup. All findings filed+fixed+merged: EV-z7f5/#1347, EV-gl1e/#1329, EV-52hf/#1341, EV-5hk5/#1373, EV-bi41/#1374, EV-z03y/#1375. Round-4 OOB re-verify confirmed fixes compound (state_machines 0->0.922, factory_bot/webmock/http real OOB scores, errors=0). Residual resolution-coverage gaps (behavior-named/flat-prefixed/non-std helper) tracked low-pri: EV-ajby/#1376, EV-6rbd/#1377, EV-no5u/#1378."}}
+{"id":"int-46080989","kind":"field_change","created_at":"2026-07-15T12:59:28.484284407Z","actor":"Denis Kiselev","issue_id":"EV-jj18","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-f2064cbf","kind":"field_change","created_at":"2026-07-15T13:25:07.606150972Z","actor":"Denis Kiselev","issue_id":"EV-fkw0","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}
+{"id":"int-eb2c5880","kind":"field_change","created_at":"2026-07-15T13:33:14.202699471Z","actor":"Denis Kiselev","issue_id":"EV-axze","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-fece2dce","kind":"field_change","created_at":"2026-07-15T13:33:14.634226625Z","actor":"Denis Kiselev","issue_id":"EV-7ab0","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-46a5d7e3","kind":"field_change","created_at":"2026-07-15T13:33:52.254966218Z","actor":"Denis Kiselev","issue_id":"EV-2bx6","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-2b8ea434","kind":"field_change","created_at":"2026-07-15T13:33:52.673568305Z","actor":"Denis Kiselev","issue_id":"EV-dgjv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-9f4fbaea","kind":"field_change","created_at":"2026-07-15T13:33:53.013705815Z","actor":"Denis Kiselev","issue_id":"EV-t1qg","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-608d35ec","kind":"field_change","created_at":"2026-07-15T13:33:53.352696649Z","actor":"Denis Kiselev","issue_id":"EV-vlbh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-616f39e1","kind":"field_change","created_at":"2026-07-15T13:33:53.68007233Z","actor":"Denis Kiselev","issue_id":"EV-y194","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-abcaeb3a","kind":"field_change","created_at":"2026-07-15T13:33:54.363899883Z","actor":"Denis Kiselev","issue_id":"EV-j2kz","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Closed"}}
+{"id":"int-b8027311","kind":"field_change","created_at":"2026-07-15T13:34:47.737536249Z","actor":"Denis Kiselev","issue_id":"EV-w07i","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Closed"}}

data/.rubocop_todo.yml

@@ -15,6 +15,7 @@ Metrics/ClassLength:
     - "lib/evilution/runner.rb"
     - "lib/evilution/runner/isolation_resolver.rb"
     - "lib/evilution/cli/parser/options_builder.rb"
+    - "lib/evilution/spec_resolver.rb"
 
 Metrics/MethodLength:
   Exclude:

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 Versioning policy: see [docs/versioning.md](docs/versioning.md).
 
+## [1.0.0] - 2026-07-15
+
+First stable release. From `1.0.0` onward evilution follows [Semantic Versioning](https://semver.org): the public contract — CLI commands and flags, `.evilution.yml` configuration keys, session JSON files, the MCP tool schemas, and process exit codes — is frozen and covered by the SemVer guarantees and deprecation cycle in [docs/versioning.md](docs/versioning.md). The `1.0.0` milestone is the culmination of the readiness work that shipped across the `0.31`–`0.35` line (config and session-JSON schema versioning, MCP tool-contract stabilization, the CLI flag deprecation sweep, real-world Rails validation, the parallel/isolation stress suite, and running evilution against its own suite to a mutation-score target).
+
+### Added
+
+- **Contributor architecture guide (`docs/architecture.md`)** — a single internals map for contributors: a high-level flow diagram, a module map of every `Evilution::` namespace, the end-to-end data flow from source file to scored result, and step-by-step recipes for adding a new mutator, reporter, or test integration. Linked from the README "Development" and "Internals" sections (EV-fkw0, PR #1407, GH #863)
+
+### Changed
+
+- **Public Ruby API frozen as internal (`docs/public_api.md`)** — evilution has no public Ruby API. The entire `Evilution::` namespace is internal and may change in any release; the supported, SemVer-governed surface is the CLI, config file, session JSON, MCP tools, and exit codes. The top-level `Evilution` module and the primary entry points (`Runner`, `CLI`, `Config`) carry an `@api private` YARD marker, the new [docs/public_api.md](docs/public_api.md) documents the contract surfaces, and [docs/versioning.md](docs/versioning.md) is updated to match (the MINOR trigger now covers "introducing a public Ruby facade where none exists" and the deprecation cycle no longer references a Ruby `@deprecated` path) (EV-jj18, PR #1406, GH #854)
+- **Dependency bumps** — `mcp` 0.21.0 → 0.24.0 (PRs #1402/#1403), plus CI/tooling updates (`rubocop` 1.88.2, `ruby/setup-ruby` 1.318.0, `actions/checkout` 7)
+
+## [0.35.0] - 2026-06-24
+
+### Added
+
+- **Test::Unit now scores out-of-the-box: a dedicated canary spec plus a Test::Unit spec resolver** — `--integration test-unit` shared minitest's runtime but not its file conventions, so two things silently broke. (1) The proof-of-life canary always wrote either an RSpec `_spec.rb` or a minitest `_test.rb` and only ever generated RSpec/minitest source; under `test-unit` the synthetic mutation loaded nothing, scored `:error`, and aborted the run before any real mutation ran. The canary now emits a `Test::Unit::TestCase` subclass into a `_test.rb` file for `test-unit` (and keeps the `_test.rb`/`_spec.rb` split keyed on the integration). (2) The config spec-resolver builder fell through to the default `spec/`/`_spec.rb` resolver for `test-unit`, which resolved nothing for a `test/`-rooted suite; it now reuses minitest's `test/` + `_test.rb` resolver since test-unit gems mirror that layout (PR #1386)
+- **Auto-preload finds namespaced gem test helpers (`test/<gem>/helper.rb`)** — gems that namespace their suite keep the bootstrap at `test/<gem>/helper.rb` (e.g. ruby/csv: `test/csv/helper.rb`) rather than a flat `test/test_helper.rb`. The conventional preload chain missed it, so autodetect fell back to the bare gem entry point (`lib/<gem>.rb`) — which never sets up the test framework — and the canary aborted. The gem-helper search now also looks for the namespaced form, deriving the directory from the gem name (dotted form for dash-named gems plus the flat form): `test/<gem>/helper.rb`. `Evilution::GemDetector.gem_name` is exposed publicly so callers can build these conventional paths (PR #1386)
+
+### Fixed
+
+- **`SpecResolver` resolves flat `test_`-prefixed Test::Unit/minitest files (`test/test_connection_pool_timed_stack.rb`)** — some minitest/Test::Unit gems flatten a nested source's path into a single `test_`-prefixed file at the test root (`lib/connection_pool/timed_stack.rb` → `test/test_connection_pool_timed_stack.rb`, with no `test/connection_pool/` subdir), so the resolver found nothing and scored `:unresolved`. The resolver now derives a flat candidate from the **full** lib-relative path (every segment joined with `_`) — deliberately not from namespace-dropped variants, which would yield bare-basename forms (`test_timed_stack.rb`) that collide across namespaces and are already covered by the existing `test_<name>.rb` convention. Top-level sources produce nothing here, and the flat candidate ranks below the mirrored layouts so a 1:1 file always wins. Minitest suffix only (PR #1385)
+- **Unresolved-mutation warnings now name concrete recovery paths for behaviour-named spec layouts** — `SpecResolver` intentionally does not guess for **behaviour-named** layouts (specs named by behaviour, not by lib path, so nothing ties a source file to a spec — e.g. aasm's `lib/aasm/base.rb`, exercised through the public API by `spec/unit/{event,callbacks,guard,api}_spec.rb`). A fuzzy match there would report a misleading score, so every mutation stays `:unresolved` (a coverage gap, `errors=0`). The minitest, RSpec, and Test::Unit unresolved warnings now spell out the explicit opt-ins — name the covering specs via `--spec`/`--spec-dir`, or run the whole suite per mutation with `--fallback-full-suite` — so a behaviour-named layout reads as a fixable resolution choice rather than a silent 0%. Documented in the README "Unresolved mutations — behaviour-named spec layouts" section (PR #1384)
+
 ## [0.34.0] - 2026-06-16
 
 ### Added

data/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/marinazzio/evilution/refs/heads/master/assets/logo/evilution-mark-transparent.svg" width="160" height="160" alt="Evilution mascot">
+</p>
+
 [![Gem Version](https://badge.fury.io/rb/evilution.svg)](https://badge.fury.io/rb/evilution)
 
 # Evilution — Mutation Testing for Ruby
@@ -7,7 +11,7 @@
 * **License**: MIT (free, no commercial restrictions)
 * **Language**: Ruby >= 3.3
 * **Parser**: Prism (Ruby's official AST parser, ships with Ruby 3.3+)
-* **Test frameworks**: RSpec and Minitest
+* **Test frameworks**: RSpec, Minitest, and Test::Unit
 
 ## Installation
 
@@ -59,6 +63,13 @@ The first command writes a sibling `Gemfile.local.lock`. Decide whether to commi
 
 The evilution gemspec already declares `prism >= 1.5, < 2`, so adding the `gem "prism"` line above is only necessary on stacks that also pin prism in `Gemfile.lock`.
 
+## Migrating from `mutant`
+
+Coming from the commercially-licensed [`mutant`](https://github.com/mbj/mutant) gem? See
+[docs/migration-from-mutant.md](docs/migration-from-mutant.md) for a command/config
+mapping, output-terminology differences, and how to diff the two tools' results with
+`evilution compare` (it ingests mutant session JSON directly).
+
 ## Command Reference
 
 ```
@@ -94,7 +105,7 @@ Every command, subcommand, and flag listed in this section is part of evilution'
 | `-f`, `--format FORMAT`      | String  | `text`       | Output format: `text`, `json`, or `html`.         |
 | `--target EXPR`              | String  | _(none)_     | Only mutate matching methods. Supports method name (`Foo::Bar#calculate`), class (`Foo`), namespace wildcards (`Foo::Bar*`), method-type selectors (`Foo#`, `Foo.`), descendants (`descendants:Foo`), and source globs (`source:lib/**/*.rb`). |
 | `--min-score FLOAT`          | Float   | 0.0          | Minimum mutation score (0.0–1.0) to pass.         |
-| `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`, which also resolves non-mirrored (`spec/unit`, `test/unit`) and dir-grouped (`test/unit/<class>/*_test.rb`) layouts. |
+| `--spec FILES`               | Array   | _(none)_     | Spec files to run (comma-separated). Defaults to auto-detection via `SpecResolver`, which also resolves non-mirrored (`spec/unit`, `test/unit`), dir-grouped (`test/unit/<class>/*_test.rb`), and flat `test_`-prefixed (`test/test_connection_pool_timed_stack.rb`) layouts. |
 | `--spec-dir DIR`             | String  | _(none)_     | Include all `*_spec.rb` files in DIR recursively. Composable with `--spec`. |
 | `--spec-pattern GLOB`        | String  | _(none)_     | Restrict resolved spec candidates to files matching GLOB (e.g. `spec/models/**/*_spec.rb`). |
 | `--no-example-targeting`     | Boolean | _(enabled)_  | Disable per-mutation example targeting (always run every example in the resolved spec file). Example targeting scans each example body for symbols from the mutated method and runs only the matching subset. |
@@ -377,7 +388,7 @@ Compatibility policy for the `1.x` gem line:
 | `unresolved` | No spec file resolved for the mutated source — **coverage gap, not a failure**. Use `--fallback-full-suite` to run the full suite instead. | excluded |
 | `unparseable` | Mutated source failed to parse (e.g. dangling heredoc opener after `method_body_replacement`). Short-circuited — never executed. | excluded |
 
-Unresolved mutations indicate a missing test mapping — the file has no corresponding test file that the resolver could find (for example, an RSpec `_spec.rb` file or a Minitest `_test.rb` file, depending on configuration). The resolver searches both the `lib/`-mirrored path and common non-mirrored buckets (`spec/unit`, `spec/lib`, `test/unit`, `test/lib`), so a high unresolved rate usually means a genuinely missing or unconventionally-placed test; a run that leaves many mutations unresolved prints an unresolved-rate warning with a best-guess spec path per source file. They are reported separately so you can act on them (add a test, adjust test naming, pass `--spec`, or opt in to the full-suite fallback) without inflating the error count.
+Unresolved mutations indicate a missing test mapping — the file has no corresponding test file that the resolver could find (for example, an RSpec `_spec.rb` file or a Minitest `_test.rb` file, depending on configuration). The resolver searches the `lib/`-mirrored path, common non-mirrored buckets (`spec/unit`, `spec/lib`, `test/unit`, `test/lib`), and the flat `test_`-prefixed Minitest/Test::Unit convention (`test/test_connection_pool_timed_stack.rb`), so a high unresolved rate usually means a genuinely missing or unconventionally-placed test; a run that leaves many mutations unresolved prints an unresolved-rate warning with a best-guess spec path per source file. They are reported separately so you can act on them (add a test, adjust test naming, pass `--spec`, or opt in to the full-suite fallback) without inflating the error count.
 
 ## Mutation Operators (74 total)
 
@@ -687,6 +698,22 @@ For each entry in `survived[]`:
 
 Entries in the JSON `errors[]` array represent mutations that raised an exception (syntax error, load failure, or runtime crash) rather than producing a test outcome. Each entry includes `error_class`, `error_message`, and the first 5 `error_backtrace` lines. Use these fields to decide whether the error is a bug in the mutation operator (file an issue), a load-time problem in the mutated source (often `NoMethodError: super called outside of method` or constant-redefinition issues), or a genuine crash that the original tests should have caught. Run with `--verbose` to stream the same error details to stderr during the run.
 
+### Unresolved mutations — behaviour-named spec layouts
+
+`SpecResolver` auto-detects mirrored (`spec/foo_spec.rb`), non-mirrored (`spec/unit`, `spec/lib`, `test/unit`), and dir-grouped (`test/unit/<class>/*_test.rb`) layouts. It deliberately does **not** guess for **behaviour-named** layouts — where specs are named by behaviour rather than by lib path, so no path or class name ties a source file to a spec. The canonical example is [aasm](https://github.com/aasm/aasm): `lib/aasm/base.rb` is the central DSL class, but it has no `base_spec.rb`; its behaviour is exercised through the public API by `spec/unit/{event,callbacks,guard,api}_spec.rb`, none of which name `AASM::Base`. Every mutation in such a file resolves to no spec and is reported `:unresolved` (a coverage gap, not a failure — `errors=0`).
+
+This is intentional: a fuzzy content/grep match would pick a wrong-but-plausible spec subset and report a misleading score. `:unresolved` plus the warning is the honest signal. To get a real score, opt into one of the two explicit recovery paths the warning names:
+
+```bash
+# run a directory of specs you know covers the file (--spec-dir globs it)
+bundle exec evilution mutate lib/aasm/base.rb --spec-dir spec/unit
+# or name explicit files as a single comma-separated --spec value (no shell glob)
+bundle exec evilution mutate lib/aasm/base.rb --spec spec/unit/event_spec.rb,spec/unit/callbacks_spec.rb
+
+# or run the whole suite per mutation (slower, but correct-by-superset)
+bundle exec evilution mutate lib/aasm/base.rb --fallback-full-suite
+```
+
 ### Long Minitest fork runs — not a hang
 
 Minitest projects under `--isolation=fork` re-bootstrap the test environment (`test_helper.rb`, plugins, runnable state) once per mutation. On constant-heavy files (e.g. Shopify/liquid's `lib/liquid/lexer.rb`, ~270 mutations) the wall-clock cost is dominated by that per-fork bootstrap and any mutations that hit a `--timeout` rather than killing the test fast. A single-worker run (`-j 1`) on a few hundred mutations can take 4+ minutes; combined with `--no-progress` and a non-TTY stderr (CI, redirected logs) the run looks silent the entire time.
@@ -756,6 +783,12 @@ When Evilution detects a parallel run against a SQLite-backed `config/database.y
 
 ## Development
 
+### Architecture
+
+New to the codebase? [docs/architecture.md](docs/architecture.md) is the
+contributor guide: the end-to-end mutation flow (source → result), a module map,
+and step-by-step recipes for adding a mutator, a reporter, or a test integration.
+
 ### Memory leak check
 
 Run before releasing to verify no memory regressions:
@@ -771,6 +804,9 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 
 ## Internals (for context, not for direct use)
 
+For the full contributor architecture — module map, data flow, and extension
+points — see [docs/architecture.md](docs/architecture.md).
+
 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
@@ -784,6 +820,8 @@ Tests 4 paths (InProcess isolation, Fork isolation, mutation generation + stripp
 
 `evilution` follows [Semantic Versioning](https://semver.org). The full policy — what counts as the public contract, what triggers a major bump, how deprecations work — is documented in [docs/versioning.md](docs/versioning.md).
 
+There is **no public Ruby API**: the entire `Evilution::` namespace is internal and may change in any release. Drive evilution through the CLI, `.evilution.yml`, the MCP tools, or hooks. See [docs/public_api.md](docs/public_api.md).
+
 ## Repository
 
 https://github.com/marinazzio/evilution

data/assets/logo/evilution-mark-transparent.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Evilution — evil ruby mutant mascot">
+  <title>Evilution</title>
+  <defs>
+    <filter id="glow" x="-60%" y="-60%" width="220%" height="220%">
+      <feGaussianBlur stdDeviation="2.4" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- clawed arms (behind gem) -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <path d="M60 124 L40 132 L46 138 L36 142 L48 147 L40 153 L56 150 L64 136 Z" fill="#9A1826"/>
+    <path d="M196 124 L216 132 L210 138 L220 142 L208 147 L216 153 L200 150 L192 136 Z" fill="#7F1420"/>
+  </g>
+
+  <!-- faceted ruby body -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <polygon points="98,82 128,82 128,120 88,120" fill="#D5384A"/>
+    <polygon points="128,82 158,82 168,120 128,120" fill="#B91C2C"/>
+    <polygon points="54,120 88,120 98,82" fill="#E2566B"/>
+    <polygon points="168,120 202,120 158,82" fill="#911A28"/>
+    <polygon points="54,120 88,120 128,214" fill="#A81B2A"/>
+    <polygon points="88,120 128,120 128,214" fill="#911A28"/>
+    <polygon points="128,120 168,120 128,214" fill="#7C1320"/>
+    <polygon points="168,120 202,120 128,214" fill="#5E0F18"/>
+  </g>
+  <polygon points="98,82 158,82 202,120 128,214 54,120" fill="none" stroke="#3A0910" stroke-width="3" stroke-linejoin="round"/>
+
+  <!-- glowing mutant eyes -->
+  <g filter="url(#glow)">
+    <polygon points="100,99 123,106 118,117 96,110" fill="#22D3EE"/>
+    <polygon points="156,99 133,106 138,117 160,110" fill="#22D3EE"/>
+    <polygon points="110,105 118,107 116,113 108,111" fill="#0E1A2B"/>
+    <polygon points="146,105 138,107 140,113 148,111" fill="#0E1A2B"/>
+  </g>
+
+  <!-- fanged grin -->
+  <path d="M106 138 L150 138 L142 149 L134 144 L128 150 L122 144 L114 149 Z" fill="#1B060C"/>
+  <polygon points="118,138 125,138 122,148" fill="#EAF2F8"/>
+  <polygon points="131,138 138,138 134,148" fill="#EAF2F8"/>
+
+  <!-- mutation cracks leaking binary -->
+  <g filter="url(#glow)" fill="none" stroke="#67E8F9" stroke-width="1.7" stroke-linecap="round" opacity="0.92">
+    <polyline points="166,90 156,106 169,120 159,134"/>
+    <polyline points="82,150 92,160 86,172"/>
+  </g>
+  <g fill="#7FE9F7" font-family="monospace" font-size="11" font-weight="700" opacity="0.85">
+    <text x="170" y="128" transform="rotate(12 170 128)">1</text>
+    <text x="176" y="140" transform="rotate(12 176 140)">0</text>
+    <text x="168" y="150" transform="rotate(12 168 150)">1</text>
+    <text x="78" y="184" transform="rotate(-14 78 184)">0</text>
+  </g>
+</svg>

data/assets/logo/evilution-mark.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img" aria-label="Evilution — evil ruby mutant mascot">
+  <title>Evilution</title>
+  <defs>
+    <radialGradient id="bg" cx="50%" cy="40%" r="78%">
+      <stop offset="0%" stop-color="#27364D"/>
+      <stop offset="100%" stop-color="#1E293B"/>
+    </radialGradient>
+    <pattern id="hex" width="56" height="100" patternUnits="userSpaceOnUse" patternTransform="scale(0.42)">
+      <path d="M28 66L0 50L0 16L28 0L56 16L56 50L28 66L28 100M28 0L28 34L0 50M28 34L56 50"
+            fill="none" stroke="#3B4D68" stroke-width="2" opacity="0.30"/>
+    </pattern>
+    <filter id="glow" x="-60%" y="-60%" width="220%" height="220%">
+      <feGaussianBlur stdDeviation="2.4" result="b"/>
+      <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- backdrop -->
+  <rect width="256" height="256" rx="52" fill="url(#bg)"/>
+  <rect width="256" height="256" rx="52" fill="url(#hex)"/>
+
+  <!-- clawed arms (behind gem) -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <path d="M60 124 L40 132 L46 138 L36 142 L48 147 L40 153 L56 150 L64 136 Z" fill="#9A1826"/>
+    <path d="M196 124 L216 132 L210 138 L220 142 L208 147 L216 153 L200 150 L192 136 Z" fill="#7F1420"/>
+  </g>
+
+  <!-- faceted ruby body -->
+  <g stroke="#470B13" stroke-width="2.5" stroke-linejoin="round">
+    <!-- table (top) -->
+    <polygon points="98,82 128,82 128,120 88,120" fill="#D5384A"/>
+    <polygon points="128,82 158,82 168,120 128,120" fill="#B91C2C"/>
+    <!-- crown shoulders -->
+    <polygon points="54,120 88,120 98,82" fill="#E2566B"/>
+    <polygon points="168,120 202,120 158,82" fill="#911A28"/>
+    <!-- pavilion: main facet ridges run from the table corners (88,120 / 168,120)
+         down to the culet, continuing the crown's inclined edges -->
+    <polygon points="54,120 88,120 128,214" fill="#A81B2A"/>
+    <polygon points="88,120 128,120 128,214" fill="#911A28"/>
+    <polygon points="128,120 168,120 128,214" fill="#7C1320"/>
+    <polygon points="168,120 202,120 128,214" fill="#5E0F18"/>
+  </g>
+  <!-- crisp outer silhouette -->
+  <polygon points="98,82 158,82 202,120 128,214 54,120" fill="none" stroke="#3A0910" stroke-width="3" stroke-linejoin="round"/>
+
+  <!-- glowing mutant eyes -->
+  <g filter="url(#glow)">
+    <polygon points="100,99 123,106 118,117 96,110" fill="#22D3EE"/>
+    <polygon points="156,99 133,106 138,117 160,110" fill="#22D3EE"/>
+    <polygon points="110,105 118,107 116,113 108,111" fill="#0E1A2B"/>
+    <polygon points="146,105 138,107 140,113 148,111" fill="#0E1A2B"/>
+  </g>
+
+  <!-- fanged grin -->
+  <path d="M106 138 L150 138 L142 149 L134 144 L128 150 L122 144 L114 149 Z" fill="#1B060C"/>
+  <polygon points="118,138 125,138 122,148" fill="#EAF2F8"/>
+  <polygon points="131,138 138,138 134,148" fill="#EAF2F8"/>
+
+  <!-- mutation cracks leaking binary -->
+  <g filter="url(#glow)" fill="none" stroke="#67E8F9" stroke-width="1.7" stroke-linecap="round" opacity="0.92">
+    <polyline points="166,90 156,106 169,120 159,134"/>
+    <polyline points="82,150 92,160 86,172"/>
+  </g>
+  <g fill="#7FE9F7" font-family="monospace" font-size="11" font-weight="700" opacity="0.85">
+    <text x="170" y="128" transform="rotate(12 170 128)">1</text>
+    <text x="176" y="140" transform="rotate(12 176 140)">0</text>
+    <text x="168" y="150" transform="rotate(12 168 150)">1</text>
+    <text x="78" y="184" transform="rotate(-14 78 184)">0</text>
+  </g>
+</svg>

data/docs/architecture.md

@@ -0,0 +1,220 @@
+# Architecture (contributor guide)
+
+How evilution turns a source file into a mutation-testing report, and where to
+plug in new behavior. This is an internals map for contributors — none of the
+classes named here are a public API (see [public_api.md](public_api.md)); they
+can move or change in any release.
+
+For deeper dives on two subsystems that have their own docs, see
+[isolation.md](isolation.md) (fork vs in-process, sandboxing, signal safety) and
+[integrations.md](integrations.md) (RSpec / Minitest / Test::Unit specifics).
+
+## The one-paragraph version
+
+Evilution parses each target file with [Prism](https://github.com/ruby/prism)
+into an AST with exact byte offsets. Every method becomes a *subject*. Each
+mutation *operator* walks a subject's AST and emits *mutations* — byte-range
+edits applied by source-level surgery (no AST unparsing). For every mutation,
+evilution copies the file, applies the edit, runs the covering specs in an
+isolated worker, and records whether the tests noticed (`killed`) or not
+(`survived`). Results are aggregated into a `Summary`, scored, and handed to a
+reporter.
+
+## High-level flow
+
+```mermaid
+flowchart TD
+    CLI["exe/evilution → Evilution::CLI<br/>Commands::Run"] --> CFG["Config<br/>(YAML + CLI + env, frozen)"]
+    CFG --> RUN["Runner#call<br/>(orchestrator)"]
+    RUN --> SUB["SubjectPipeline<br/>AST::Parser → Subject per method"]
+    SUB --> BASE["BaselineRunner<br/>record already-failing specs"]
+    SUB --> PLAN["MutationPlanner<br/>Mutator::Registry → Mutation objects<br/>dedupe · disable · sig · equivalent"]
+    PLAN --> EXEC["MutationExecutor<br/>jobs=1 Sequential · jobs>1 Parallel::Pool"]
+    BASE --> EXEC
+    EXEC --> ISO["Isolation::Fork / InProcess<br/>apply mutation → Integration runs specs"]
+    ISO --> STAT["classify_status<br/>killed / survived / error / timeout / unresolved"]
+    STAT --> SUM["Result::Summary<br/>counts + score"]
+    SUM --> REP["ReportPublisher → Reporter::{CLI,JSON,HTML}"]
+    REP --> OUT["stdout / evilution-report.html<br/>+ optional Session::Store"]
+```
+
+## Module map
+
+Everything lives under `lib/evilution/`.
+
+| Namespace | Responsibility | Key entry points |
+|---|---|---|
+| `CLI`, `CLI::Commands::*` | Parse argv, build `Config`, dispatch subcommands (`run`, `session`, `compare`), map result to exit code. | `cli.rb`, `cli/commands/run.rb` |
+| `Config`, `Config::*` | Merge `.evilution.yml` + CLI flags + env, validate, freeze. | `config.rb`, `config/sources.rb`, `config/validators/*` |
+| `Runner`, `Runner::*` | Orchestrate the whole run. Each stage is its own collaborator. | `runner.rb`, `runner/*` |
+| `AST`, `Subject` | Prism parse, find method subjects, source surgery, pattern matching, heredoc spans. | `ast/parser.rb`, `ast/source_surgeon.rb`, `subject.rb` |
+| `Mutator`, `Mutator::Operator::*` | 74 operators (default profile) that emit byte-edits; registry + profiles. | `mutator/base.rb`, `mutator/registry.rb`, `mutator/operator/*` |
+| `Mutation` | An immutable mutation record (original/mutated sources, slice, location, parse status). | `mutation.rb` |
+| `SpecResolver`, `SpecSelector` | Map a source file to its covering spec files (layout heuristics + explicit mappings). | `spec_resolver.rb`, `spec_selector.rb` |
+| `Isolation::{Fork,InProcess}`, `ProcessSupervisor` | Run one mutation's tests in isolation; process-group lifecycle, sandboxing, TERM/KILL ladder. | `isolation/fork.rb`, `process_supervisor.rb` |
+| `Integration::{RSpec,Minitest,TestUnit}` | Apply a mutation and run the configured test framework; report the raw outcome. | `integration/base.rb`, `integration/rspec.rb` |
+| `Parallel::{Pool,WorkQueue}` | Fan mutations across worker processes for `jobs > 1`. | `parallel/pool.rb`, `parallel/work_queue.rb` |
+| `Result::{MutationResult,Summary}` | Per-mutation result + aggregated, scored summary. | `result/mutation_result.rb`, `result/summary.rb` |
+| `Reporter::{CLI,JSON,HTML,Suggestion}` | Render a `Summary` to text / JSON / HTML. | `reporter/*` |
+| `Session`, `Compare` | Persist runs to `.evilution/results/*.json`; diff two sessions. | `session/store.rb`, `compare.rb` |
+| `Coverage`, `Equivalent`, `Baseline`, `Cache`, `Hooks`, `MCP` | Coverage-based example targeting, equivalent-mutation detection, baseline capture, incremental cache, lifecycle hooks, MCP server. | respective dirs |
+
+## Data flow, source → result
+
+Driven entirely by `Evilution::Runner#call` (`runner.rb:24`). Each step names the
+class that owns it.
+
+1. **Config** — `Config#initialize` merges YAML + CLI + env (`Config::Sources.merge`),
+   applies `DEFAULTS`, freezes. `Runner#initialize` builds the `AST::Parser`,
+   `Mutator::Registry.for_profile(config.profile)`, and (if `incremental`) a `Cache`.
+2. **Subjects** — `Runner::SubjectPipeline#call` resolves target files (explicit,
+   `source:<glob>`, or `Git::ChangedFiles`), then `AST::Parser#call` runs
+   `Prism.parse` and `AST::SubjectFinder` (a `Prism::Visitor`) emits one
+   `Evilution::Subject` per `def` node. Optional descendant/target/line-range filters follow.
+3. **Baseline** — `Runner::BaselineRunner#call` builds the integration from
+   `Runner::INTEGRATIONS` (`rspec`/`minitest`/`test_unit`) and records spec files
+   that already fail *before* any mutation, so their mutations aren't miscounted.
+   An optional `Runner::Canary` proves the pipeline can observe a known mutation.
+4. **Mutations** — `Runner::MutationPlanner#call` flat-maps subjects through
+   `Mutator::Registry#mutations_for`. The registry instantiates each operator and
+   runs `operator.call(subject, filter:)`; each operator subclasses
+   `Mutator::Base` and calls `add_mutation`, which runs `AST::SourceSurgeon` and
+   builds an immutable `Evilution::Mutation`. The planner then **deduplicates**
+   (by `file_path` + mutated source), and filters **disabled** (`DisableComment`),
+   **Sorbet `sig`** (`AST::SorbetSigDetector`), and **equivalent**
+   (`Equivalent::Detector`) mutations. Equivalent ones become `:equivalent`
+   results directly.
+5. **Spec resolution** — per subject, `SpecSelector#call(source_path)` picks specs
+   (explicit `spec_files` → `spec_mappings` → `SpecResolver#resolve_specs` layout
+   heuristics). Example-level targeting narrows to examples that reference the
+   mutated token (`ExampleFilter` / `CoverageExampleFilter`).
+6. **Execute** — `Runner::MutationExecutor#call` picks a strategy by `config.jobs`:
+   `Strategy::Sequential` for `jobs == 1`, `Strategy::Parallel` (via
+   `Parallel::Pool` / `WorkQueue`) for `jobs > 1`. Either way each mutation reaches
+   `@isolator.call(mutation:, test_command:, timeout:)`.
+7. **Isolate + test** — `Isolation::Fork#call` (default for Rails/gems) spawns a
+   sandboxed worker through `ProcessSupervisor#spawn` (own process group, TERM →
+   grace → KILL ladder, sandbox reap), applies the mutation
+   (`Integration::Loading::MutationApplier`), and runs `Integration::Base#call` →
+   `run_tests`. The child's result is marshaled back over a length-prefixed pipe.
+   `Isolation::InProcess` is the lighter path for plain-Ruby projects.
+8. **Status** — outcome flags come from the integration
+   (`Integration::RSpec::ResultBuilder`: passed / test_crashed / examples-loaded
+   guard / unresolved); the final symbol is chosen by
+   `Isolation::Fork#classify_status`: `:timeout` → `:killed` (crash) →
+   `:unresolved` → `:error` → `:survived` (tests passed) → default `:killed`.
+   A `NeutralizationPipeline` can reclassify results whose covering spec already
+   failed at baseline into `:neutral`.
+9. **Aggregate + report** — `Result::Summary` counts each status and computes
+   `score = killed / score_denominator` (total minus error/neutral/equivalent/
+   unresolved/unparseable). `Runner::ReportPublisher#publish` selects a reporter by
+   `config.format` and writes it; `Session::Store` optionally persists the run.
+   `Commands::Run` maps `summary.success?(min_score:)` to exit code `0`/`1` (`2` on error).
+
+## How to add a new mutator
+
+A mutator is a `Prism::Visitor` subclass that emits byte-range edits.
+
+1. **Create the operator** in `lib/evilution/mutator/operator/<name>.rb`:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   require_relative "../operator"
+
+   class Evilution::Mutator::Operator::MyThing < Evilution::Mutator::Base
+     def visit_integer_node(node)          # a Prism visit_*_node hook
+       add_mutation(
+         offset: node.location.start_offset,
+         length: node.location.length,
+         replacement: "42",                # the source text to splice in
+         node: node
+       )
+       super                               # ALWAYS call super to keep walking
+     end
+   end
+   ```
+
+   - Implement one or more `visit_<node_type>_node(node)` methods (the Prism node
+     names — `visit_call_node`, `visit_if_node`, …). Call `super` so child nodes
+     are still visited.
+   - Emit edits only through `add_mutation(offset:, length:, replacement:, node:)`.
+     It handles heredoc-span extension, the mutation filter, source surgery, and
+     builds the immutable `Mutation`. Never edit source strings directly.
+   - The operator's registered name is auto-derived from the class name
+     (`MyThing` → `my_thing`); that string is the `operator` field in JSON output
+     and is part of the public contract, so name it deliberately.
+
+2. **Require it** in `lib/evilution.rb` alongside the other
+   `require_relative "evilution/mutator/operator/..."` lines.
+
+3. **Register it** in `lib/evilution/mutator/registry.rb`: add the class to the
+   `default` list (runs in every profile) — or, for an aggressive operator meant
+   only for `profile: strict`, to `STRICT_EXTRA_OPERATORS` instead.
+
+4. **Test it** under `spec/evilution/mutator/operator/<name>_spec.rb`, mirroring an
+   existing operator spec. Adding an operator to the `default` profile shifts
+   mutation scores and is a **MINOR** version bump (see [versioning.md](versioning.md)).
+
+## How to add a new reporter
+
+A reporter is `.new(**opts)` + `#call(summary) -> String`. It consumes a frozen
+`Evilution::Result::Summary` and returns the rendered report body.
+
+1. **Create the reporter** in `lib/evilution/reporter/<format>.rb`:
+
+   ```ruby
+   # frozen_string_literal: true
+
+   require_relative "../reporter"
+
+   class Evilution::Reporter::Csv
+     def initialize(integration: :rspec)   # keyword args only; keep them optional
+       @integration = integration
+     end
+
+     def call(summary)                      # returns a String
+       # read summary.results, summary.score, summary.killed, summary.survived,
+       # summary.survived_results, etc. — see Result::Summary for the full API
+       "..."
+     end
+   end
+   ```
+
+   The `Summary` API a reporter reads includes: counts (`total`, `killed`,
+   `survived`, `errors`, `neutral`, `equivalent`, `unresolved`, `unparseable`,
+   `timed_out`), metrics (`score`, `score_denominator`, `success?(min_score:)`,
+   `efficiency`, `peak_memory_mb`), the raw `results`, and filtered lists
+   (`survived_results`, `killed_results`, …). Each result exposes `mutation`
+   (`operator_name`, `file_path`, `line`, `diff`), `status`, `duration`, and
+   status predicates (`killed?`, `survived?`, …).
+
+2. **Require it** in `lib/evilution.rb` (next to the other `reporter/*` requires)
+   **and** in `lib/evilution/runner.rb` (the runner requires reporters
+   independently, near the bottom of the file).
+
+3. **Wire the dispatch** in `Runner::ReportPublisher#build_reporter`
+   (`runner/report_publisher.rb`): add a `when :csv` branch returning your class,
+   and a matching `require_relative "../reporter/csv"` at the top. If the output
+   should go to a file rather than stdout, extend the `#publish` write branch
+   (only `:html` writes a file today; every other format is `$stdout.puts`ed).
+
+4. **Advertise the value.** There is no strict format allowlist to update —
+   `config.format` is only `to_sym`'d, not validated — but update the
+   `--format` help string in `cli/parser/options_builder.rb` so `csv` is
+   discoverable. (The `compare` subcommand keeps its *own* `SUPPORTED_FORMATS`
+   list; touch it only if `compare` should support the new format too.)
+
+Adding a new format is additive — a **MINOR** bump.
+
+## How to add a new test integration (bonus)
+
+Integrations subclass `Evilution::Integration::Base` (`integration/base.rb`),
+which defines the contract: class methods `baseline_runner` / `baseline_options`,
+and instance methods `run_tests(mutation)`, `ensure_framework_loaded`,
+`build_args(mutation)`, `reset_state` (each `raise NotImplementedError` until
+overridden). `Base#call` already handles applying the mutation and firing
+`mutation_insert_pre/post` hooks. Register the new class in
+`Runner::INTEGRATIONS` (`runner/baseline_runner.rb`) and allow its symbol in the
+integration config validator. See [integrations.md](integrations.md) for the
+framework-specific details.

data/docs/isolation.md

@@ -87,6 +87,7 @@ order, falling back to the gem's library entry point (`lib/<gem>.rb`):
 1. `spec/spec_helper.rb` (RSpec)
 2. `test/test_helper.rb` (Minitest / Test::Unit)
 3. `test/helper.rb` (flat-layout convention)
+4. `test/<gem>/helper.rb` (namespaced suites, e.g. ruby/csv's `test/csv/helper.rb`; the namespace is derived from the gem name, with the dotted form for dash-named gems) (PR #1386)
 
 When a gem is detected but none of those helpers exist, evilution prints a
 warning naming the locations it looked in and pointing at `--preload`, so a

data/docs/migration-from-mutant.md

@@ -0,0 +1,226 @@
+# Migrating from `mutant` to Evilution
+
+This guide is for teams moving off [`mutant`](https://github.com/mbj/mutant) — whose
+runtime is under a commercial license — to Evilution, which is MIT-licensed with no
+commercial restrictions. It maps the commands, config, and output you already know
+onto their Evilution equivalents, and is honest about where the two tools differ.
+
+Evilution is not a drop-in fork of mutant. It produces its own mutations with its own
+operator set and selects work by **file path** rather than by subject expression. The
+result is the same kind of signal — surviving mutations expose weak tests — but the
+numbers and the workflow are not identical. The `compare` command (below) exists
+precisely so you can line the two tools up and see the difference for yourself.
+
+## TL;DR
+
+| mutant | Evilution |
+| --- | --- |
+| `mutant run --use rspec -- 'MyApp::Foo*'` | `evilution run lib/my_app/ --target 'MyApp::Foo*'` |
+| `mutant.yml` | `.evilution.yml` (run `evilution init` to scaffold) |
+| `mutant-rspec` / `mutant-minitest` gems | built in: `--integration rspec\|minitest\|test-unit` |
+| "mutation coverage" %, "alive" | "mutation score" 0.0–1.0, "survived" |
+| commercial license for the runtime | MIT |
+
+## 1. Install
+
+Drop the mutant gems and add Evilution:
+
+```ruby
+# Gemfile — remove:  gem "mutant", "mutant-rspec"
+gem "evilution", group: :test
+```
+
+```sh
+bundle install
+bundle exec evilution init   # writes a commented .evilution.yml
+```
+
+There is no separate integration gem to install — RSpec, Minitest, and Test::Unit
+support ships in the core gem.
+
+## 2. The core workflow shift: files, not subjects
+
+mutant is **subject-driven**: you pass a match expression and it finds the code.
+Evilution is **file-driven**: you pass file paths, and optionally narrow with
+`--target`.
+
+```sh
+# mutant
+bundle exec mutant run --use rspec -- 'MyApp::Calculator#add'
+
+# evilution — point at the file, optionally filter to the method
+bundle exec evilution run lib/my_app/calculator.rb --target 'MyApp::Calculator#add'
+
+# whole directory, then filter by expression
+bundle exec evilution run lib/ --target 'MyApp::Calculator*'
+```
+
+`--target` accepts the expression shapes you are used to, plus a source glob:
+
+| Intent | mutant match | Evilution `--target` |
+| --- | --- | --- |
+| One method | `MyApp::Foo#bar` | `MyApp::Foo#bar` |
+| One class | `MyApp::Foo` | `MyApp::Foo` |
+| Namespace (recursive) | `MyApp::Foo*` | `MyApp::Foo*` |
+| All instance methods | `MyApp::Foo#` | `MyApp::Foo#` |
+| All singleton methods | `MyApp::Foo.` | `MyApp::Foo.` |
+| Subclasses | _(n/a)_ | `descendants:MyApp::Foo` |
+| By file glob | _(use file args)_ | `source:lib/**/*.rb` |
+
+## 3. Command mapping
+
+| Task | mutant | Evilution |
+| --- | --- | --- |
+| Run mutation testing | `mutant run -- 'Foo'` | `evilution run lib/foo.rb` (alias `mutate`; binary alias `evil`) |
+| Choose framework | `--use rspec` / `mutant-minitest` | `--integration rspec\|minitest\|test-unit` |
+| Parallel workers | `-j N` / `--jobs N` | `-j N` / `--jobs N` |
+| Fail fast | `--fail-fast` | `--fail-fast [N]` (off by default; N defaults to 1 when the flag is given without a value) |
+| Coverage gate | `--score` (default `1.0` / 100%) | `--min-score` (default `0.0`) |
+| Preview mutations | `mutant util mutation` / `mutant environment subject list` | `evilution util mutation -e 'a + b'` / `evilution subjects lib/foo.rb` |
+| Set load path / requires | `--include lib --require my_app` | handled by `--preload` (auto-detects `spec/spec_helper.rb` etc.) + Bundler |
+| JSON report | session JSON (always written) | `--format json` (`--save-session` to persist) |
+| Inline opt-out | `# mutant:disable` | `# evilution:disable` |
+| Aggressive operators | _(always on)_ | `--profile strict` (or `--strict`) |
+
+### Things mutant has that Evilution does not (yet)
+
+- **`--since <git-ref>`** — mutant can restrict subjects to lines changed since a git
+  ref. Evilution has no diff-aware selection. The closest tools are `--incremental`
+  (caches `killed`/`timeout` results and skips unchanged mutations on re-runs — a
+  different model) and `--target source:<glob>` / explicit file args to scope a run.
+
+### Things Evilution adds
+
+- `--format html` interactive report, and `evilution compare` (see §6).
+- Per-mutation **example targeting** (runs only the examples that exercise the mutated
+  code) — on by default, tune with `example_targeting*` keys.
+- `--suggest-tests` emits concrete test code for survivors.
+- Explicit `:unresolved` status when no spec maps to a source file (a coverage-gap
+  signal rather than a silent skip).
+
+## 4. Config translation (`mutant.yml` → `.evilution.yml`)
+
+```yaml
+# mutant.yml
+integration:
+  name: rspec
+jobs: 8
+includes:
+  - lib
+requires:
+  - my_app
+matcher:
+  subjects:
+    - MyApp::Billing*
+  ignore:
+    - MyApp::Billing::Legacy#deprecated
+```
+
+```yaml
+# .evilution.yml
+integration: rspec
+jobs: 8
+# `includes` / `requires` are usually unnecessary — Evilution preloads the test
+# helper (and the gem entry) automatically. Override only if needed:
+preload: spec/spec_helper.rb
+# `matcher.subjects` -> run file args + --target; expression below is illustrative.
+target: "MyApp::Billing*"
+# `matcher.ignore` -> AST ignore patterns (see docs/ast_pattern_syntax.md) or an
+# inline `# evilution:disable` comment on the method.
+ignore_patterns: []
+```
+
+Key-by-key:
+
+| `mutant.yml` | `.evilution.yml` | Notes |
+| --- | --- | --- |
+| `integration.name: rspec` | `integration: rspec` | string, not a mapping |
+| `jobs` | `jobs` | same |
+| `includes` | _(usually omit)_ | Bundler + `preload` cover the load path |
+| `requires` | `preload` | a single preload file (autodetected by default) |
+| `matcher.subjects` | `target` + file args | one expression; combine with positional paths |
+| `matcher.ignore` | `ignore_patterns` / `# evilution:disable` | AST patterns or inline comments |
+| `fail_fast` | `fail_fast` | integer N or `null` |
+| `--score` gate (CLI; default `1.0`) | `min_score` | evilution defaults to `0.0` — set your own gate |
+| _(n/a)_ | `profile: strict` | opt into aggressive truthiness mutators |
+
+Run `evilution init` for a fully commented template, and point your editor at
+`schema/evilution.config.schema.json` for autocomplete/validation.
+
+> **Note:** the `integration` enum in that JSON schema currently lists only `rspec`
+> and `minitest`. `test-unit` (normalized internally to `test_unit`) is fully
+> supported by the runtime, but a schema-aware editor may flag it as invalid until
+> the schema catches up — it will still run.
+
+## 5. Output differences
+
+The vocabulary and the math differ — read this before comparing dashboards.
+
+| Concept | mutant | Evilution |
+| --- | --- | --- |
+| Detected mutation | `killed` | `killed` |
+| Undetected mutation | `alive` | `survived` |
+| Headline metric | "mutation coverage" (%) | "mutation score" (0.0–1.0) |
+| Pre-existing test failure | `neutral` / `noop` | `neutral` |
+| Operator name in report | **not emitted** | emitted, e.g. `Arithmetic::Swap` |
+| Per-mutation diff | unified diff with `@@` header + context | `- old` / `+ new` pair (and a full `unified_diff` for survivors) |
+| Report shape | nested: session → subject → coverage results | flat per-status buckets |
+
+**Score formula.** mutant's coverage is roughly `killed / (total - neutral)` and the
+culture is to gate at 100%. Evilution's score is:
+
+```
+score = killed / (total - errors - neutral - equivalent - unresolved - unparseable)
+```
+
+i.e. only `killed / (killed + survived + timed_out)`. It defaults to a `min_score` of
+`0.0` (no gate) — set your own threshold in CI with `--min-score`.
+
+**Extra statuses** Evilution reports that mutant has no equivalent for:
+
+- `unresolved` — no spec file mapped to the mutated source (coverage gap, excluded from score)
+- `unparseable` — the mutated source did not parse, so it never ran (excluded)
+- `equivalent` — proven behaviorally identical to the original (excluded)
+- `timeout` / `error` — surfaced explicitly per mutation
+
+**Exit codes:** `0` pass · `1` score below `--min-score` (survivors to address) · `2` error.
+
+## 6. Verify the migration with `compare`
+
+`evilution compare` ingests **both** a mutant session JSON and an Evilution JSON
+report, normalizes them to a common shape, and buckets the mutations so you can see
+whether the same code is being killed:
+
+```sh
+# produce an evilution report
+bundle exec evilution run lib/ --format json --save-session
+
+# line it up against your last mutant session JSON
+bundle exec evilution compare \
+  --against .mutant/results/<session-id>.json \
+  --current .evilution/results/<timestamp>.json \
+  --format text
+```
+
+The tool auto-detects which file came from which tool. Because the two tools use
+different operator sets, expect the mutation **counts** to differ — the useful signal
+is which subjects lose or gain coverage, not an exact 1:1 match. Operator names are
+absent from mutant's JSON, so comparison keys on file + line + normalized diff, not on
+operator.
+
+## 7. Known gaps & parity notes
+
+- **Different mutations.** Evilution ships its own operator registry (`--profile
+  default` / `strict`); it is not mutant's AST-handler set. Counts and specific
+  survivors will differ. Use `compare` to quantify.
+- **No diff-based selection** (`--since <ref>`). Use file args, `--target source:`,
+  or `--incremental`.
+- **File-driven, not subject-driven.** Always pass paths; narrow with `--target`.
+- **100%-coverage culture.** Evilution does not assume a 100% gate; choose `min_score`
+  deliberately, and note that `:unresolved` mutations are excluded from the score
+  rather than counted as failures.
+- **Operator names** appear in Evilution output but not mutant's, so cross-tool diffs
+  match on location + change, not operator identity.
+
+If something you relied on in mutant has no clear equivalent here, please open an issue
+— parity feedback directly shapes the 1.0 roadmap.

data/docs/public_api.md

@@ -0,0 +1,50 @@
+# Public API
+
+This document defines evilution's public, SemVer-governed surface for `1.x`.
+
+## There is no public Ruby API
+
+**The entire `Evilution::` Ruby namespace is internal.** Every class, module,
+method, and constant under `Evilution::` may change, move, or disappear in any
+release — including patch releases — with no deprecation cycle. Do not `require`
+evilution and call into it programmatically expecting stability; internal
+refactors will break you without warning.
+
+Evilution is consumed through its CLI, its configuration file, its session
+output, and its MCP tools — not as a library you embed. The top-level
+`Evilution` module and the primary entry points (`Evilution::Runner`,
+`Evilution::CLI`, `Evilution::Config`) carry an `@api private` YARD marker; the
+namespace as a whole is internal by this declaration, whether or not an
+individual class is tagged.
+
+## What *is* the public contract
+
+These surfaces are stable under the [versioning policy](versioning.md). They are
+the supported way to drive evilution:
+
+| Surface | Authoritative reference |
+|---|---|
+| **CLI commands and flags** | README "Command Reference" |
+| **`.evilution.yml` configuration keys** | README "Configuration" |
+| **Session JSON files** (`.evilution/results/*.json`) | README "JSON Output Schema" |
+| **MCP tool schemas** (`evilution-mutate`, `evilution-session`, `evilution-info`) | README "MCP Server" → "Contract stability" |
+| **Process exit codes** (`0` pass, `1` fail, `2` error) | README "Exit Codes" |
+| **Hook events and payload keys** (configured via the `hooks:` config key) | README "Configuration" / hooks docs |
+
+Anything not in that table — and in particular anything reachable only by calling
+Ruby methods on `Evilution::` objects — is internal.
+
+## Why no Ruby API at 1.0
+
+Evilution's job is to run mutation testing from the command line (and from an MCP
+agent). The value users depend on is the behaviour of `evilution run`, the shape
+of the report it writes, and the config that tunes it — none of which requires a
+frozen object graph. Keeping the Ruby internals unfrozen lets the isolation,
+parallelism, and mutation-operator internals evolve freely across `1.x` without
+spending major-version budget. If a genuine embedding use case emerges, a small
+public facade can be introduced additively in a MINOR release.
+
+## See also
+
+- [Versioning & Upgrade Policy](versioning.md) — what each SemVer bump covers and
+  how deprecations work.

data/docs/versioning.md

@@ -7,14 +7,14 @@ This document defines what `evilution` promises across releases.
 | Bump          | Triggered by                                                                 |
 |---------------|-------------------------------------------------------------------------------|
 | MAJOR (`2.0`) | Removing or renaming anything in the public contract; changing semantics; tightening input validation. |
-| MINOR (`1.X`) | Adding a new CLI flag, config key, mutation operator, public Ruby method, or session/MCP field; relaxing validation; adding an operator to the `default` profile (whether brand-new or promoted from `strict`). |
+| MINOR (`1.X`) | Adding a new CLI flag, config key, mutation operator, or session/MCP field; introducing a public Ruby facade where none exists today; relaxing validation; adding an operator to the `default` profile (whether brand-new or promoted from `strict`). |
 | PATCH (`1.X.Y`) | Bug fix, performance improvement, documentation, internal refactor with no observable contract effect. |
 
 ## Public contract surface
 
 The following surfaces are covered by the SemVer guarantees above:
 
-- **Public Ruby API** — classes and methods explicitly documented as public. Everything else is internal and may change in any release.
+- **Public Ruby API** — there is none. The entire `Evilution::` namespace is internal and may change in any release. See [docs/public_api.md](public_api.md).
 - **CLI flags and commands** — the README "Command Reference" tables are the authoritative list.
 - **`.evilution.yml` configuration keys** — see the README "Configuration" section.
 - **Session JSON files** (`.evilution/results/*.json`) — see the README "JSON Output Schema" section.
@@ -27,7 +27,7 @@ Anything not on this list is internal. It can change in any release without a de
 
 When a feature on the public contract surface is deprecated:
 
-1. It is marked with the YARD `@deprecated` tag (Ruby API), or with a deprecation note in the relevant doc table (CLI flags, config keys, MCP fields).
+1. It is marked with a deprecation note in the relevant doc table (CLI flags, config keys, session/MCP fields).
 2. Where the call site is reachable at runtime, a one-line warning is emitted to stderr.
 3. The deprecated form remains functional for the entire `1.x` line. A feature deprecated in any `1.X` release continues to work in every subsequent `1.X+N` release.
 4. The earliest release that may remove the feature is the next major (`2.0`), per the SemVer table above.

data/lib/evilution/cli.rb

@@ -19,6 +19,7 @@ require_relative "cli/commands/session_gc"
 require_relative "cli/commands/compare"
 require_relative "cli/commands/run"
 
+# @api private
 class Evilution::CLI
   def initialize(argv, stdin: $stdin)
     parsed = Parser.new(argv, stdin: stdin).parse

data/lib/evilution/config/builders/spec_resolver.rb

@@ -6,7 +6,9 @@ require_relative "../../spec_resolver"
 class Evilution::Config::Builders::SpecResolver
   def self.call(integration:)
     case integration
-    when :minitest
+    when :minitest, :test_unit
+      # test-unit gems mirror minitest's layout (test/ root, _test.rb suffix);
+      # without this they default to spec/_spec.rb and resolve to nothing.
       Evilution::SpecResolver.new(test_dir: "test", test_suffix: "_test.rb", request_dir: "integration")
     else
       Evilution::SpecResolver.new

data/lib/evilution/config.rb

@@ -4,6 +4,7 @@ require "yaml"
 require_relative "spec_resolver"
 require_relative "spec_selector"
 
+# @api private
 class Evilution::Config
   CONFIG_FILES = %w[.evilution.yml config/evilution.yml].freeze
   CURRENT_SCHEMA_VERSION = 1
@@ -117,7 +118,6 @@ class Evilution::Config
     FileLoader.load
   end
 
-  # Generates a default config file template.
   def self.default_template
     <<~YAML
       # Evilution configuration

data/lib/evilution/gem_detector.rb

@@ -43,6 +43,13 @@ module Evilution::GemDetector
       @mutex.synchronize { @cache.clear }
     end
 
+    # Public accessor for the resolved gem name (gemspec basename, disambiguated
+    # by target paths for multi-gemspec roots). Callers use it to derive
+    # conventional paths such as a namespaced test helper (test/<gem>/helper.rb).
+    def gem_name(root, target_paths: nil)
+      gem_name_for(root, target_paths: target_paths)
+    end
+
     private
 
     def starting_dir(path)

data/lib/evilution/integration/loading/redefinition_recovery.rb

@@ -63,7 +63,9 @@ class Evilution::Integration::Loading::RedefinitionRecovery
 
   def idempotency_violation?(error)
     msg = error.message
-    IDEMPOTENCY_PATTERNS.any? { |pat| msg.include?(pat) }
+    # `msg` is a String and patterns are substrings, so `include?` is a
+    # substring test — `intersect?` would compare array elements, not text.
+    IDEMPOTENCY_PATTERNS.any? { |pat| msg.include?(pat) } # rubocop:disable Style/ArrayIntersect
   end
 
   def superclass_mismatch?(error)

data/lib/evilution/integration/minitest.rb

@@ -276,8 +276,19 @@ class Evilution::Integration::Minitest < Evilution::Integration::Base
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching test found for #{file_path}, #{action}. " \
-         "Use --spec to specify the test file."
+    warn unresolved_test_message(file_path)
+  end
+
+  # Name both recovery paths when skipping :unresolved; when already falling
+  # back the suite is running, so only the explicit-spec hint applies.
+  # Behaviour-named layouts never auto-resolve (EV-ajby / GH #1376).
+  def unresolved_test_message(file_path)
+    if @fallback_to_full_suite
+      "[evilution] No matching test found for #{file_path}, running full suite. " \
+        "Use --spec to specify the test file."
+    else
+      "[evilution] No matching test found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the test file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/integration/rspec/unresolved_spec_warner.rb

@@ -11,8 +11,22 @@ class Evilution::Integration::RSpec::UnresolvedSpecWarner
     return if @warned.include?(file_path)
 
     @warned << file_path
-    action = fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching spec found for #{file_path}, #{action}. " \
-         "Use --spec to specify the spec file."
+    warn message(file_path, fallback_to_full_suite)
+  end
+
+  private
+
+  # When already falling back the suite is running, so only the explicit-spec
+  # hint is useful. Otherwise the mutation is skipped :unresolved — name BOTH
+  # recovery paths, since behaviour-named layouts (specs not mirroring the lib
+  # path, e.g. aasm's base.rb) never auto-resolve (EV-ajby / GH #1376).
+  def message(file_path, fallback_to_full_suite)
+    if fallback_to_full_suite
+      "[evilution] No matching spec found for #{file_path}, running full suite. " \
+        "Use --spec to specify the spec file."
+    else
+      "[evilution] No matching spec found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the spec file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/integration/test_unit/test_file_resolver.rb

@@ -41,8 +41,19 @@ class Evilution::Integration::TestUnit::TestFileResolver
     return if @warned_files.include?(file_path)
 
     @warned_files << file_path
-    action = @fallback_to_full_suite ? "running full suite" : "marking mutation unresolved"
-    warn "[evilution] No matching test found for #{file_path}, #{action}. " \
-         "Use --spec to specify the test file."
+    warn unresolved_message(file_path)
+  end
+
+  # Name both recovery paths when skipping :unresolved; when already falling
+  # back the suite is running, so only the explicit-spec hint applies.
+  # Behaviour-named layouts never auto-resolve (EV-ajby / GH #1376).
+  def unresolved_message(file_path)
+    if @fallback_to_full_suite
+      "[evilution] No matching test found for #{file_path}, running full suite. " \
+        "Use --spec to specify the test file."
+    else
+      "[evilution] No matching test found for #{file_path}, marking mutation unresolved. " \
+        "Use --spec to specify the test file, or --fallback-full-suite to run the whole suite."
+    end
   end
 end

data/lib/evilution/related_spec_heuristic.rb

@@ -31,14 +31,12 @@ class Evilution::RelatedSpecHeuristic
   def extract_domain(file_path)
     normalized = normalize_path(file_path)
 
-    # Strip common prefixes and get the relative path under app/ or lib/
     relative = normalized
                .delete_prefix("app/controllers/")
                .delete_prefix("app/models/")
                .delete_prefix("app/")
                .delete_prefix("lib/")
 
-    # Remove .rb extension and _controller suffix
     basename = relative.sub(/\.rb\z/, "")
     basename = basename.sub(/_controller\z/, "")
 

data/lib/evilution/runner/canary.rb

@@ -76,13 +76,30 @@ class Evilution::Runner::Canary
   end
 
   def write_spec(dir)
-    minitest = @config.integration == :minitest
-    name = minitest ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
-    path = File.join(dir, name)
-    File.write(path, minitest ? minitest_spec_source : rspec_spec_source)
+    path = File.join(dir, spec_filename)
+    File.write(path, spec_source)
     path
   end
 
+  # minitest and test-unit both live under a `_test.rb` file; rspec uses
+  # `_spec.rb`. Picking the wrong shape makes the integration load nothing (or
+  # raise), so the synthetic mutation scores :error and aborts the run.
+  def spec_filename
+    test_framework? ? "canary_#{suffix}_test.rb" : "canary_#{suffix}_spec.rb"
+  end
+
+  def test_framework?
+    %i[minitest test_unit].include?(@config.integration)
+  end
+
+  def spec_source
+    case @config.integration
+    when :minitest then minitest_spec_source
+    when :test_unit then test_unit_spec_source
+    else rspec_spec_source
+    end
+  end
+
   def rspec_spec_source
     <<~RUBY
       RSpec.describe("evilution proof-of-life canary") do
@@ -103,6 +120,16 @@ class Evilution::Runner::Canary
     RUBY
   end
 
+  def test_unit_spec_source
+    <<~RUBY
+      class EvilutionCanaryTest_#{suffix} < Test::Unit::TestCase
+        def test_pipeline_is_alive
+          assert(true)
+        end
+      end
+    RUBY
+  end
+
   def build_mutation(class_path)
     Evilution::Mutation.new(
       subject: Evilution::Subject.new(

data/lib/evilution/runner/isolation_resolver.rb

@@ -222,7 +222,21 @@ class Evilution::Runner::IsolationResolver
   end
 
   def find_first_existing_gem_helper
-    find_first_existing_under(detected_gem_root, GEM_PRELOAD_CANDIDATES)
+    find_first_existing_under(detected_gem_root, GEM_PRELOAD_CANDIDATES) ||
+      find_first_existing_under(detected_gem_root, nested_gem_helper_candidates)
+  end
+
+  # Gems that namespace their suite keep the helper at test/<gem>/helper.rb
+  # (ruby/csv: test/csv/helper.rb) rather than the flat test/helper.rb, so the
+  # conventional chain misses it and autodetect would fall back to the bare gem
+  # entry — which never sets up the test framework, aborting the canary.
+  # Derive the namespace dir from the gem name (dotted for dash-named gems, plus
+  # the flat form).
+  def nested_gem_helper_candidates
+    name = detected_gem_root && Evilution::GemDetector.gem_name(detected_gem_root, target_paths: target_files)
+    return [] unless name
+
+    [name.tr("-", "/"), name].uniq.map { |ns| File.join("test", ns, "helper.rb") }
   end
 
   def find_first_existing_under(root, candidates)

data/lib/evilution/runner.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../evilution"
 
+# @api private
 class Evilution::Runner
   # Autoloaded: canary.rb subclasses Evilution::Error at class-body eval
   # time, which is not yet defined while evilution.rb is mid-load. Deferring

data/lib/evilution/spec_resolver.rb

@@ -161,7 +161,14 @@ class Evilution::SpecResolver
 
     fallbacks = primary.flat_map { |c| parent_fallback_candidates(c) }
 
-    (primary + fallbacks + prefix_convention_candidates(stripped)).uniq
+    (primary + fallbacks + convention_candidates(stripped)).uniq
+  end
+
+  # Non-mirrored Test::Unit/minitest filename conventions: the `test_<name>.rb`
+  # prefix and the flat namespace-prefixed form. Both rank below the mirrored
+  # layouts assembled in #candidate_test_paths.
+  def convention_candidates(stripped)
+    prefix_convention_candidates(stripped) + flat_prefixed_candidates(stripped)
   end
 
   # Conventional roots that may hold tests: the mirrored root plus the common
@@ -204,6 +211,25 @@ class Evilution::SpecResolver
     end
   end
 
+  # Test::Unit / minitest gems sometimes flatten a nested source's path into a
+  # single `test_`-prefixed file at the test root: lib/connection_pool/timed_stack.rb
+  # -> test/test_connection_pool_timed_stack.rb (no test/connection_pool/ subdir).
+  # Built from the FULL lib-relative path only (every segment joined with `_`),
+  # NOT from namespace-dropped variants — dropping segments would yield bare
+  # basename forms (test_timed_stack.rb) that collide across namespaces and are
+  # already covered by #prefix_convention_candidates. Top-level sources have no
+  # namespace to flatten, so they produce nothing here. Ranked below the mirrored
+  # layouts (appended last) so a 1:1 file always wins. Minitest suffix only.
+  def flat_prefixed_candidates(stripped)
+    return [] unless @test_suffix == MINITEST_SUFFIX
+    return [] unless stripped.include?("/")
+
+    name = stripped.delete_suffix(@test_suffix).tr("/", "_")
+    return [] if name.empty?
+
+    roots.map { |root| "#{root}/test_#{name}.rb" }
+  end
+
   def controller_to_request_test(stripped_path)
     return nil unless stripped_path.start_with?(CONTROLLER_PREFIX)
 

data/lib/evilution/version.rb

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

data/lib/evilution.rb

@@ -129,6 +129,12 @@ require_relative "evilution/cli"
 require_relative "evilution/disable_comment"
 require_relative "evilution/runner"
 
+# Evilution has no public Ruby API. The entire `Evilution::` namespace is
+# internal and may change in any release, including patches. The stable,
+# SemVer-governed contract is the CLI, `.evilution.yml` config keys, session
+# JSON files, the MCP tool schemas, and process exit codes. See
+# docs/public_api.md and docs/versioning.md.
+# @api private
 module Evilution
   # Captured at load time, before any isolator can chdir into a per-mutation
   # sandbox. Used as the anchor for resolving project-relative paths (spec

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evilution
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Denis Kiselev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -99,14 +99,22 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/logo/evilution-mark-1024.png
+- assets/logo/evilution-mark-64.png
+- assets/logo/evilution-mark-transparent-1024.png
+- assets/logo/evilution-mark-transparent.svg
+- assets/logo/evilution-mark.svg
 - claude-swarm.yml
 - comparison_results/baseline_2026-04-09.md
 - comparison_results/operator_classification.md
 - comparison_results/operator_prioritization.md
+- docs/architecture.md
 - docs/ast_pattern_syntax.md
 - docs/integrations.md
 - docs/isolation.md
+- docs/migration-from-mutant.md
 - docs/mutation_density_benchmark.md
+- docs/public_api.md
 - docs/versioning.md
 - exe/evil
 - exe/evilution