mutineer 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e18649829a9226ea7a5f654ef38602eabff4005ebf8a516fca4402460a7aac09
-  data.tar.gz: 9e3c166e5e2e513278aaf210f271ed0f070cd335d0de588318cb8aa71f6b6a06
+  metadata.gz: 50113a063a85737ad99476f85e78cb2ac015f267018d19ba6350ba36ff4ac6df
+  data.tar.gz: c12343a00d2df6d495859644c326bc650e33d013ddf009f2648c06a199aceb86
 SHA512:
-  metadata.gz: 2e10e1214d0b55a4c93c7fa13d4c3b39503d4e2b1e367a995e2d813e98bd55ce2c2774b429bd690f2ae55019a39c7ee539e3ef60ea51bf25e2bc61c602ab72b6
-  data.tar.gz: 146768f9f599d41af9e6549f65ad7658cdd55e3d57a6f35fa6d094cfef6be73b036bb3dc8ebe8616d03cf358cdaf78e5d8a3b40a996c7a4d18a06898b9454824
+  metadata.gz: a170b15c6883a4dcec6a2798c3b102a5f9c9ded1f46c166df98d0e5bdf5b891ca5b24892efe06245680b45a94da38638adc36ca9a48a48d2ac1c07b29126f173
+  data.tar.gz: a30272ff6afb48dd666d6945c6532d987ef335e0e78dc422420cf26cdbec639ee1c850118a10ba25e10a426a2644b3926e39698126eaad0646707a4f2be2e719

data/CHANGELOG.md

@@ -6,6 +6,255 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-06
+
+### Added
+- **`--timeout SECONDS` and `--capture-timeout SECONDS`**, also `timeout:` and
+  `capture_timeout:` in `.mutineer.yml`. They set the in-process per-mutant
+  time limit (default 10s) and the coverage-capture time limit (default 120s),
+  which were fixed. On a large Rails suite the clean run of the unmutated
+  tests took longer than 120s, so every run that offered the whole suite
+  stopped as not green, and a mutant on a line many tests cover took longer
+  than 10s and was scored `timeout`. `--daemon` keeps its own per-mutant
+  limit but uses `--capture-timeout` for its coverage capture;
+  `--test-command` uses neither. Either backend warns about a limit it was
+  given and does not use.
+- **`--cache-dir DIR`**, also `cache_dir:` in `.mutineer.yml`, sets where the
+  coverage cache is written (default `.mutineer`, as before). Two runs from the
+  same project root shared `.mutineer/coverage.json` and could overwrite each
+  other's map; each can now have its own directory. `--daemon` uses it too.
+  A blank value (an unset CI variable) exits 2 rather than writing the cache
+  into the project root.
+- **The README states how timeouts affect the score** (#62): a timed-out
+  mutant is left out of the score, and counts as a mutant with no verdict
+  under `--threshold`.
+- **`--matrix` reports which tests kill each mutant** (`matrix: true` in
+  `.mutineer.yml`). Each mutant runs every test in its covering files instead
+  of stopping at the first failure, and the child sends each test's outcome to
+  the parent as it is recorded. The report names blind tests, which ran in a
+  complete row and killed no mutant, and redundant tests, whose every kill
+  another test also makes. Redundancy is judged one test at a time, so delete
+  redundant tests one at a time. The human report lists up to 20 of each, the
+  HTML report all of them, and the JSON report moves to schema `1.5` with a
+  `matrix` block that appears only with the flag. A test is its file and its
+  id (the example id under RSpec), so examples that share a description stay
+  apart and an example whose generated description changes with the mutant
+  stays one test. Verdicts, the score and the exit code do not change: each
+  mutant gets the verdict a run without the flag gives. After a serial test
+  fails, an exit, a crash or the timeout in a later test, class or group
+  leaves it `killed`; an end in the code that run still reaches (the failing
+  test's class wrapper or group hooks, the suite's own cleanup) and a failure
+  in a `parallelize_me!` class keep the exit status. A row is complete only
+  when the child's stream arrived in order and every test reported (under
+  Minitest the recorder saw every test, under RSpec every planned example),
+  so a caught `Interrupt` leaves it incomplete. The human report names up
+  to 20 incomplete rows and the HTML and JSON reports all of them; the human
+  and HTML reports warn not to delete a blind test until its rows are
+  complete.
+  Minitest and RSpec 3.3+ are supported, on the in-process backend only;
+  `--daemon`, `--test-command`, `--fail-fast` and `--dry-run` exit 2 with it.
+  `--no-matrix` and `--no-fail-fast` beat the matching `.mutineer.yml` key,
+  so a file that sets one can still run with a flag that conflicts with it.
+- **`no_coverage[]` and `uncapturable[]` name each mutant.** Every entry in
+  the JSON report now has `operator`, `token` and `id`, as `ignored[]` has, so
+  mutants on one line can be told apart and an `id` can go in `ignore:`. The
+  entries are sorted by `(file, line, operator, id)`. `schema_version` is `1.6`.
+
+- **The site and README explain "clean-room" and compare Mutineer with
+  Mutant**, and the landing page hero has a one-minute explainer video. It
+  plays at 55% volume while in view (not with reduced motion; muted until
+  the first click or key where the browser requires it), pauses when it scrolls
+  away or the tab is hidden, and has an Enlarge button.
+
+### Changed
+- **The human report has a `Timeout:` row**, and the score line lists timeouts
+  apart from errored mutants. Before, the `Errored:` row and the score line
+  added the two together, while the JSON report kept them apart. The HTML
+  summary now shows a `timeout` count apart from `errored` too.
+- **A test file given as a source after `--test` exits 2.** `--test` takes one
+  file, so in `mutineer run app/x.rb --test spec/a_spec.rb spec/b_spec.rb` the
+  second spec became a source to mutate, and the run tested with one spec file
+  without a word. Now a source named `*_test.rb` or `*_spec.rb` inside a
+  `test/` or `spec/` directory, given with `--test`, is a usage error that says
+  to repeat `--test`. The usage line now reads `--test <test> [--test <test>...]`.
+
+### Fixed
+- **The RSpec runner keeps what gems configured before the run.** It called
+  `RSpec.reset`, which drops the whole configuration. Under `rails: true`, a
+  `--boot` file or `require:`, the app's gems load first, so a setting such as
+  rspec-retry's `verbose_retry` was gone, and a support file that set it
+  raised `NoMethodError`. The run stopped with "the unmutated suite is not
+  green". The runner now calls `RSpec.clear_examples`, which keeps the
+  configuration. Hooks that gems added now apply too: an example with
+  rspec-retry's `retry: 3` runs up to 3 times per mutant, as under `rspec`.
+- **`--since` no longer scores a file that Git ignores** (#168). A file
+  outside the index is scored in full, so a new file is not missed. That
+  check also caught files that Git ignores on purpose (`.gitignore`,
+  `.git/info/exclude` or the global excludes file), such as generated code
+  inside a directory run. Those files now get no mutants under `--since`,
+  and a warning names each one. Other untracked files are still scored in
+  full, and so is a file when Git cannot tell, such as one beyond a symlink or
+  inside a submodule.
+- **The human report escapes control characters from the source** (#163).
+  A surviving line that held a terminal control byte (for example ESC) was
+  printed as that byte, so it could change what the terminal showed. The
+  token, the replacement, the diff lines, method names, file paths and the
+  kill matrix's test names now print each control character except tab as
+  its Ruby escape (`\e`), and a byte that is not valid UTF-8 (a Latin-1
+  source) as `\xNN`. The JSON and HTML
+  reports already escaped text and do not change.
+- **One edit on a line is scored once** (#159). Some opt-in operators emitted
+  two mutants that give the same source: `literal_mutation` on `0` (the
+  "change to 1" and "add 1" rules), `negation_removal` on `!!x` (either `!`
+  removed), and `chain_link` or `operand_removal` on a repeated part such as
+  `a.b.b.c` or `x || x`. Each copy had its own id, so one surviving edit
+  counted twice. Now only the first copy on a line runs. Copies that start
+  on different lines (a multi-line chain) both stay, so `--since` never
+  loses the edit. Ids are assigned before the copy is dropped, so every kept
+  mutant keeps its id, and the dropped copy's id simply stops appearing.
+  Default runs do not change. If you use these operators with `--baseline`,
+  regenerate the baseline after upgrading: the score can move with no code
+  change, and in a full (unscoped) comparison a dropped copy that survived
+  is listed as fixed. An ignore entry for one copy's id still ignores only
+  that copy; the other copy still runs.
+- **`# mutineer:disable-line` inside a string no longer silences a line**
+  (#158). The marker was found with a text search, so a string such as
+  `"# mutineer:disable-line"` ignored every mutant on its line and left
+  them out of the score. Only a real `#` comment counts now. A heredoc or
+  regex that holds the text is ignored too.
+- **`./lib/x.rb` and an absolute path pair with a test** (#104). Auto-pairing
+  found the test for `lib/calc.rb` but not for `./lib/calc.rb` or the
+  absolute path to the same file. It reported "no test found by convention"
+  and exited 2. A file argument inside the project is now made relative to
+  the project root first, so equivalent spellings (`./`, `..`, absolute)
+  pair with the same test and run once. A symlink keeps its own name, so it
+  stays a separate source from its target. Reports show that root-relative
+  path. A path outside the project stays as typed.
+- **A mutant on another line of a multi-line statement runs its tests**
+  instead of being reported as `no_coverage`. Ruby counts one line of a
+  statement only. When the mutant's own line has no count, the runner now uses
+  the tests that ran the statement that holds the mutation. A heredoc body
+  belongs to its statement. This fallback skips a first or last line that also
+  holds other code, such as the `def` line, and the body of `x while c` and
+  `x until c`. It also gives no tests to a mutant in code of the statement
+  that runs only sometimes: a `when` or `in` condition, a `rescue` class
+  list, a parameter default, the rescue side of `x rescue y`, the value of
+  `||=` or `&&=`, the operand of `defined?`, the right side of `a ||` or
+  `a &&`, a branch of `x if c`, `x unless c`, a ternary or `else`, the
+  pattern of `v in p` or `v => p`, an
+  argument or block of `x&.m(...)`, and the value of `x&.m += v`. Those
+  mutants stay `no_coverage`, as before.
+- **A survivor diff for a multi-line mutant applies with `git apply`** (#106).
+  The JSON `diff` header always read `@@ -N +N @@`, even when the mutant
+  removed two lines and added one, so `git apply` rejected the patch as
+  corrupt. The header now carries each side's line count (`@@ -3,2 +3 @@`).
+  A one-line diff keeps its old header. A mutant that empties a line now
+  shows that empty line as a `+` line. A side whose last line has no final
+  newline gets ``. Lines of a CRLF file now keep
+  their `\r`, so the patch applies to that file.
+- **Split test files pair with their source** (#87). A source such as
+  `app/foo/bar.rb` now also uses `test/foo/bar_upsert_test.rb` and
+  `test/foo/bar_guards_test.rb`, together with `test/foo/bar_test.rb` when
+  that file exists. The same names under `test/lib/` pair with a `lib/`
+  source. Before, only the exact `bar_test.rb` name was tried, so a suite
+  split across `bar_*_test.rb` files was skipped and a gate could pass with
+  no mutants run. A spec the old rules already find is unchanged. The
+  split name is left for `user_session.rb` when that file exists, so
+  `user.rb` does not run `user_session_test.rb`. The same rule holds outside
+  `app/` and `lib/`: `src/user.rb` does not take `test/src/user_session_test.rb`
+  when `src/user_session.rb` exists. A longer source claims a split file
+  only when that source itself searches the directory the file is in.
+  A failed capture of `test/foo/bar_upsert_test.rb` can mark `app/foo/bar.rb`
+  uncapturable only when no successful capture covered that source and
+  `bar_upsert.rb` does not exist. A test outside that directory does not,
+  and neither does a source that only shares the test basename.
+  `user_session__test.rb` stays with `user.rb` when `user_session.rb`
+  exists, because that name is not the exact test or a split test for
+  `user_session`. A failed exact spec in the mirrored `spec/` or `spec/lib/` directory
+  marks an `app/` or `lib/` source the same way. A failed spec in another
+  directory does not. A project rooted at `/` still finds split tests
+  inside that root. A stored failure keeps the pairing from the moment it
+  was checked. Adding or deleting a longer source rebuilds the coverage
+  map, so that failure is not moved onto the shorter source.
+- **A blank `operators` key no longer runs zero mutants and exits 0** (#167).
+  `operators:` with no value became an empty list. The run made no mutants
+  and the gate passed. A blank operator list is now an error, and so is a
+  list of only unknown operator names. An empty `require` or `ignore` list
+  is still valid. `--operators` on the command line still replaces the
+  file list, including a blank or unknown file list.
+- **The daemon no longer runs the tool's Ruby settings inside the app** (#100).
+  Open3 keeps a variable when the spawn hash omits it, so a parent `RUBYOPT`
+  ran inside the app. The child now gets the environment Bundler saved before
+  it activated, passed with `unsetenv_others`. The app keeps its gem home,
+  excluded groups, Bundler config, and chruby path. An `RBENV_VERSION` or
+  `ASDF_RUBY_VERSION` already in the environment stays. That pin is often
+  the Ruby that started the tool. `.ruby-version` applies only when no pin
+  is set. The tool's `RUBYOPT` and `RUBYLIB` do not reach the child, including
+  a value Bundler had saved. A gem home, `BUNDLE_PATH`, or `BUNDLE_WITHOUT`
+  reaches the child only when Bundler saved the app's value. The same
+  rule covers `GEM_PATH` and `BUNDLER_VERSION`. An rbenv version
+  bin under `RBENV_ROOT`, or under `~/.rbenv` when that variable is unset,
+  leaves `PATH` only when that root has a shim directory. An asdf version
+  bin leaves only when an asdf shim directory exists, including
+  `ASDF_DATA_DIR/shims`. Without that shim, the bin stays and `bundle` can
+  still be found. The app Gemfile, an explicit Ruby pin, and Rails env are
+  applied after that.
+- **The Action refuses to run when `output` and `baseline` are the same file** (#160).
+  That setup used to work, and a failing run copied its report onto the
+  baseline. The next run then treated the failed report as the baseline, so
+  the gate could pass. The Action now stops before the run and exits 2.
+  The baseline may come from the `baseline` input, from `--baseline` in
+  `extra-args`, or from `.mutineer.yml`. A numeric path such as `123` is
+  read the same way as the CLI. Write the report to a separate path. Copy
+  that file onto the baseline in a later step, and only when this step
+  exits 0. You can also refresh the baseline with the CLI, and keep the
+  file only when the run exits 0. The next release moves the `v1` tag, so
+  workflows on `@v1` get this refusal then.
+- **A mutation no longer leaves a heredoc body behind as Ruby** (#134).
+  Replacing a node deletes the heredoc opener and not the body. The body
+  then parses as code, raises, and counts as a kill. A mutation that drops
+  the opener is skipped. A replacement that still contains the opener stays.
+- **A bare `public`, `private` or `protected` ends `module_function` mode**,
+  so later `def`s in the module body are named as instance methods, not
+  singleton methods (#144).
+- **Turning on reduced motion mid-visit finishes the landing page count-ups**,
+  so no number keeps changing after the visitor asks for less motion (#176).
+- **`rake site:build` can no longer delete a directory such as `lib/` or
+  `.git`** (#162). The task removed the destination it was given, and only
+  refused the checkout, its parents and `docs/`. It now always builds into
+  `_site/` at the checkout root, and `rake "site:build[DEST]"` and
+  `SITE_BUILD_DEST` are gone.
+- **Documentation matches the 1.4 behavior.** Config examples use supported keys,
+  agent loops check the exit code and a real score, and report totals explain
+  partial `--fail-fast` runs. The README lists every config key and its validation
+  rules. API README links work outside GitHub, repeated changelog headings have
+  unique anchors, and the website checks validate built links and anchors.
+  Mutant-id wording and the gem's Minitest/RSpec description are also corrected.
+- **A mutant in a nested method counts once** (#157). A `def` inside
+  another method is a subject of its own, but most operators also mutated
+  its code on the outer method. The same edit then counted twice in the
+  score, with two ids. Every operator now skips a nested `def` when it
+  mutates the outer method. A `def` inside `class << obj`, where `obj` is
+  not `self`, is not a subject, so the outer method still mutates its code.
+  `array_literal`, `chain_link`, `condition_true`, `condition_false`,
+  `operand_removal`, `operator_assignment` and `return_nil` skipped that
+  code before. Their new mutants there can show as new survivors against a
+  baseline.
+
+  A mutant id includes an ordinal among the mutants with the same operator
+  and token in a subject. When the duplicates leave the outer method, the
+  ordinals of its own mutants change. An old duplicate id can then name a
+  different mutant on the outer method, and an `ignore:` entry or a
+  baseline entry with that id applies to that mutant with no warning. If
+  your code has nested methods, regenerate the `ignore:` entries and the
+  baseline for the outer methods.
+
+  Under `--strategy redefine` (the `--rails` default), a mutant in a nested
+  method can survive or error even when a test would catch it. `redefine`
+  loads only the inner method, and a call to the outer method defines the
+  original inner method again. Before, the copy of the edit on the outer
+  method was killed. Now each edit has one verdict, from the inner method.
+
 ## [1.4.0] - 2026-09-30
 
 ### Added
@@ -677,6 +926,7 @@ Rails hardening + CI batch (issues #8–#13), all verified Rails-free.
 - `.mutineer.yml` configuration (CLI > config > default precedence).
 - Byte-correct source handling for multibyte (UTF-8) sources.
 
+[1.5.0]: https://github.com/davidteren/mutineer/releases/tag/v1.5.0
 [1.4.0]: https://github.com/davidteren/mutineer/releases/tag/v1.4.0
 [1.3.0]: https://github.com/davidteren/mutineer/releases/tag/v1.3.0
 [1.2.0]: https://github.com/davidteren/mutineer/releases/tag/v1.2.0

data/README.md

@@ -9,12 +9,19 @@ change at a time, runs your test suite (Minitest or RSpec) against each mutant,
 ones your tests failed to catch — the gaps where your suite isn't actually
 testing anything.
 
+"Clean-room" means Mutineer was written from scratch. It contains no code from
+[Mutant](https://github.com/mbj/mutant) or any other mutation-testing tool.
+Mutineer's own code is licensed under MIT. See
+[Mutineer and Mutant](https://github.com/davidteren/mutineer#mutineer-and-mutant)
+for how the two tools differ.
+
 - **Prism + stdlib only** — zero runtime dependencies (Ruby ≥ 3.4).
 - **One mutation per mutant**, validity-checked by re-parsing.
 - **Fork-isolated**, parallel execution (Linux + macOS).
 - **Coverage-guided** — each mutant runs only the test files that cover its line.
 - **Stops at the first failing test** — in-process runs (not `--daemon` or
-  `--test-command`) stop a mutant's test run at the first failure.
+  `--test-command`) stop a mutant's test run at the first failure, unless
+  `--matrix` asks for every covering test.
 
 📖 **[mutineer.github.io →](https://davidteren.github.io/mutineer/)** — overview, operators, and usage.
 
@@ -33,7 +40,7 @@ gem "mutineer", group: :test
 ## Usage
 
 ```sh
-mutineer run <source...> --test <test...> [options]
+mutineer run <source...> --test <test> [--test <test>...] [options]
 ```
 
 Mutate `lib/calculator.rb`, checking it against its test, and fail CI if the
@@ -47,24 +54,30 @@ mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
 
 | Flag | Meaning |
 |------|---------|
-| `--test FILE` | Test file covering the sources (repeatable) |
+| `--test FILE` | Test file covering the sources; one file per flag, so repeat it for each (`--test a_test.rb --test b_test.rb`) |
 | `--operators LIST` | Comma-separated operator names (default: the Tier-1 set) |
 | `--threshold FLOAT` | Exit 1 when the score is below FLOAT, or when nothing could be scored and something broke, or more than one mutant produced no verdict and they exceed 10% of those attempted (default: 0 = off) |
 | `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
 | `--framework NAME` | `minitest` (default) or `rspec`; auto-detected as rspec when most `--test` files end in `_spec.rb` |
-| `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`) — ideal for PR CI |
+| `--since REF` | Only mutate lines changed since git `REF` (e.g. `origin/main`). Untracked files are scored in full unless Git ignores them. |
 | `--no-since` | Disable diff scoping; a typed no beats a `.mutineer.yml` `since:` key |
-| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (score drop is skipped under `--since`, whose score covers a different denominator; see [CI](#ci-gating)) |
+| `--baseline FILE` | Compare against a prior `--format json` run; exit 1 on new survivors / score drop (score drop is skipped under `--since`, whose score covers a different denominator; see [CI](https://github.com/davidteren/mutineer#ci-gating)) |
 | `--baseline-epsilon FLOAT` | Score-drop tolerance for `--baseline` (default: 0) |
-| `--jobs N` | Parallel worker count (default: processor count; `1` under `--rails`) |
+| `--jobs N` | Parallel worker count (default: processor count); forced to `1` by `--test-command`, `--fail-fast`, or `--rails` without `--daemon` |
+| `--boot FILE` | Require an app entry point once before forking; select at least one test file |
+| `--rails` | Boot `config/environment` and reconnect ActiveRecord per fork; without `--daemon`, defaults to `redefine` and runs serially |
 | `--verbose` | Surface the real error when a fork capture fails (alias `--debug`) |
 | `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
-| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](#apps-on-ruby--34) |
-| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend) |
+| `--timeout SECONDS` | Per-mutant time limit for in-process runs, in whole seconds (default: 10). A mutant whose tests run longer is a `timeout`; see [Timeouts and the score](https://github.com/davidteren/mutineer#timeouts-and-the-score). `--daemon` and `--test-command` keep their own limits |
+| `--capture-timeout SECONDS` | Time limit for each in-process coverage-capture subprocess and for the clean run of the unmutated tests, in whole seconds (default: 120). A suite slower than this stops the run as not green. `--daemon` uses it for its coverage capture; `--test-command` ignores it and says so |
+| `--cache-dir DIR` | Directory for the coverage cache (default: `.mutineer`). Give two runs from the same project root different directories so they do not share `coverage.json`. `--test-command` builds no cache, so it ignores it and says so |
+| `--test-command CMD` | Run the suite as a subprocess in the app's own runtime (for apps on Ruby < 3.4); `CMD` must contain `%{files}`. See [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34) |
+| `--daemon` | Boot the app once in a persistent daemon and fork per mutant, with per-worker DB isolation so `--jobs N` is safe under Rails (needs `--rails`/`--boot`; not with `--test-command`). See [the daemon backend](https://github.com/davidteren/mutineer#faster-parallel-safe-rails-the---daemon-backend) |
 | `--format human\|json\|html` | Report format (default: human; `html` is a self-contained file) |
 | `--output FILE` | Write the report to FILE instead of stdout |
 | `--dry-run` | List candidate mutations without executing (honors suppression) |
-| `--fail-fast` | Stop at the first surviving mutant |
+| `--fail-fast` | Stop at the first surviving mutant (`--no-fail-fast` beats a `.mutineer.yml` `fail_fast:` key) |
+| `--matrix` | Run every covering test for each mutant and report the blind and redundant tests; the JSON report also lists each mutant's killers. In-process only; exits 2 with `--daemon`, `--test-command`, `--fail-fast` or `--dry-run`. RSpec needs 3.3 or later. `--no-matrix` beats a `.mutineer.yml` `matrix:` key. See [Kill matrix](https://github.com/davidteren/mutineer#kill-matrix) |
 | `--list-operators` | List available operators (default vs optional) and exit |
 | `--version`, `--help` | Print version / usage and exit |
 
@@ -99,8 +112,8 @@ RAILS_ENV=test bundle exec mutineer run \
 ```
 
 `--rails` boots `config/environment` once in the parent process (every mutant
-then forks and inherits it), defaults `--strategy` to `redefine` (surgical — it
-avoids reloading files into the app tree), and reconnects ActiveRecord in each
+then forks and inherits it), defaults `--strategy` to `redefine` without `--daemon`
+(surgical — it avoids reloading files into the app tree; `--daemon` keeps `reload`), and reconnects ActiveRecord in each
 fork so the database connection is fork-safe. Use `--boot FILE` to boot a
 different entry point. Boot mode requires at least one `--test` file and is
 coverage-guided — each mutant runs only the test files that exercise its line
@@ -135,9 +148,10 @@ RAILS_ENV=test bundle exec mutineer run \
 - **One backend at a time** — `--daemon` can't be combined with `--test-command`
   (choose one), and it needs an app to boot (`--rails` or `--boot`).
 
-Status: **SQLite** today (hermetic, CI-proven). **Postgres** per-worker
-provisioning is in progress (#34/#35); until it lands, use `--daemon` with a
-SQLite test database, or drop `--jobs` to run serially on other adapters.
+Status: **SQLite** only (hermetic, CI-proven). Per-worker provisioning for
+**Postgres** and other adapters is not supported: on those, `--daemon` scores
+every mutant as `error`. Use `--daemon` with a SQLite test database, or drop
+`--daemon` to run serially on other adapters.
 
 ### Apps on Ruby < 3.4
 
@@ -207,7 +221,23 @@ Tradeoffs — this path is correct but not free:
   front (a "smoke check") if your unmutated suite isn't green.
 - **Reload strategy only** (`--strategy redefine` is rejected on this path) and
   **serial** (`--jobs` is forced to 1). For apps on Ruby ≥ 3.4, `--daemon` gives
-  safe parallelism instead (see [the daemon backend](#faster-parallel-safe-rails-the---daemon-backend)).
+  safe parallelism instead (see [the daemon backend](https://github.com/davidteren/mutineer#faster-parallel-safe-rails-the---daemon-backend)).
+
+## Timeouts and the score
+
+The mutation score is `killed / (killed + survived)`. A mutant whose tests run
+past `--timeout` is a `timeout`. It is neither killed nor survived, so it is
+left out of the score, like `no_coverage`, `uncapturable`, `errored`, skipped
+and ignored mutants. A timeout is not counted as a kill, because a hang the
+mutant caused and a suite that is just slow look the same. The human report
+shows the count in its `Timeout:` row, and the JSON report in `summary.timeout`.
+
+Under `--threshold`, a timeout is a mutant with no verdict. The run exits 1 when
+more than one mutant produced no verdict and they exceed 10% of those attempted,
+or when nothing could be scored and something broke. If a slow suite times out
+mutants that its tests would catch, raise `--timeout`. A limit set below what
+the suite needs does not raise the score: it turns those mutants into timeouts,
+and once they pass 10% of the attempted mutants the run fails.
 
 ## Suppressing equivalent mutants
 
@@ -268,6 +298,77 @@ Ids are relative to the directory you run mutineer from. mutineer finds
 (other than your home directory), it warns that the ignore ids will not match
 and tells you which directory to run from.
 
+## Kill matrix
+
+`--matrix` reports which tests kill each mutant, and from that, which tests
+add nothing to the suite.
+
+```sh
+mutineer run lib/calculator.rb --test test/calculator_test.rb --matrix
+```
+
+For each mutant, Mutineer runs every test in its covering files instead of
+stopping at the first failure, and records which tests failed. Coverage is
+recorded per test file, so that set also holds tests that never reach the
+mutated line; they pass and count as having run. A mutant's row is complete
+when its whole covering set ran and the suite returned normally (under
+Minitest, an `Interrupt` that cut the run short does not count as returning
+normally). The report
+names two kinds of test:
+
+- **Blind:** the test ran in at least one complete row and killed no mutant
+  in any row. It would still pass with this run's mutations of the code, so
+  it guards none of them. It can still check behavior outside this run's
+  mutants (code in other files, or edits no operator makes), so look at what
+  it asserts before you delete it, or give it an assertion that can fail.
+- **Redundant:** every mutant the test kills, another test kills too. That
+  makes it a candidate for deletion, one test at a time: two redundant tests
+  can be the only killers of one mutant, so re-run after each deletion.
+
+The answers cover this run's mutants only. A test of code outside the sources
+you passed kills nothing here, so mutate the code a test exercises before you
+call the test blind.
+
+The matrix changes no verdict, score or exit code: each mutant gets the
+verdict a run without `--matrix` gives. That run skips every later test,
+test class and example group after the first failure, so when a later one
+exits the process, crashes or runs into the time limit, the mutant is still
+`killed`. The run without `--matrix` still runs the code around the failing
+test (the rest of its Minitest class `run` wrapper, the `after(:all)` hooks of
+its RSpec groups) and the suite's own cleanup (RSpec's `after(:suite)`), so an
+end there keeps the exit status. A failure in a Minitest `parallelize_me!`
+class also keeps it: those run after every serial class and cannot be stopped
+once queued, while a failure in a serial class still stops the run.
+
+Under RSpec, `--matrix` needs RSpec 3.3 or later, whose example ids tell
+apart examples on one line. With an older RSpec every row is incomplete.
+
+The human report lists up to 20 blind and 20 redundant tests, and the HTML
+report lists them all. `--format json` adds a `matrix` block with every test
+and each mutant's killers (see the
+[JSON schema](https://davidteren.github.io/mutineer/json-schema.html#matrix)).
+A test is its file and its id. The name is `CalculatorTest#test_add` under
+Minitest, or the example's full description under RSpec, where the example id
+(`./spec/calc_spec.rb[1:2]`) tells apart examples that share a description
+and keeps an example whose generated description changes with the mutant as
+one test.
+
+Each mutant runs its whole covering set, so every mutant costs what a survivor
+costs. In 1.4, stopping at the first failure cut a full run of rack's
+`lib/rack/utils.rb` from 86 to 89 seconds down to 35 to 41, so expect a matrix
+run to take 2.1 to 2.5 times as long as a normal one. A mutant that reaches the
+per-mutant time limit (`--timeout`, 10 seconds by default) after a test already failed stays `killed`
+with its row marked incomplete. The report names each incomplete row and warns
+that a blind test may have killed one of those mutants, so do not delete a
+blind test until its rows are complete. Raise `--timeout` (or `timeout:` in
+`.mutineer.yml`) to get complete rows.
+
+`--matrix` runs on the in-process backend only. It exits 2 with `--daemon`,
+`--test-command`, `--fail-fast` or `--dry-run`, and the message says whether
+each setting came from the command line or `.mutineer.yml`. To run one of
+those with `matrix: true` in the file, pass `--no-matrix`; to run `--matrix`
+with `fail_fast: true` in the file, pass `--no-fail-fast`.
+
 ## CI gating
 
 Store a JSON run as a baseline, then fail the build only when a PR makes things
@@ -277,10 +378,15 @@ worse:
 mutineer run app/ --baseline .mutineer/baseline.json   # exit 1 on NEW survivors or a score drop
 ```
 
-`--baseline` reports which survivors are new (by [mutant id](#mutant-ids)) and any score drop. It
+`--baseline` reports which survivors are new (by [mutant id](https://github.com/davidteren/mutineer#mutant-ids)) and any score drop. It
 combines with `--threshold` (the worse of the two sets the exit code). Pass a
 directory (or several sources) to audit a whole layer in one boot — tests are
-auto-paired by convention and the report breaks down per source.
+auto-paired by convention and the report breaks down per source. A source
+`app/foo/bar.rb` pairs with `test/foo/bar_test.rb` and with unclaimed
+`test/foo/bar_*_test.rb` files in that directory, such as `bar_upsert_test.rb`.
+It does not take `user_session_test.rb` when `user_session.rb` exists in the same directory.
+It does not take `bar_upsert_guards_test.rb` when `bar_upsert.rb` exists.
+A spec that already pairs is left as that one file.
 
 ### GitHub Action
 
@@ -316,17 +422,17 @@ the format.
 
 ## For AI agents & pipelines
 
-Mutineer is built for programmatic use — versioned JSON, [mutant ids](#mutant-ids) that survive unrelated edits,
+Mutineer is built for programmatic use — versioned JSON, [mutant ids](https://github.com/davidteren/mutineer#mutant-ids) that survive unrelated edits,
 structured exit codes, and diff-scoped runs. See:
 
 - **AI agents & CI recipes** — the agent inner-loop and CI-gate recipes (and how
   to avoid infinite loops on equivalent mutants):
   [rendered](https://davidteren.github.io/mutineer/agentic-coding.html) ·
-  [source](docs/agentic-coding.md)
+  [source](https://davidteren.github.io/mutineer/agentic-coding.md)
 - **JSON schema reference** — the `--format json` schema and its versioning
   contract:
   [rendered](https://davidteren.github.io/mutineer/json-schema.html) ·
-  [source](docs/json-schema.md)
+  [source](https://davidteren.github.io/mutineer/json-schema.md)
 - **Ruby API (YARD)** — class reference for the shipped gem:
   [https://davidteren.github.io/mutineer/api/](https://davidteren.github.io/mutineer/api/)
 
@@ -335,11 +441,44 @@ structured exit codes, and diff-scoped runs. See:
 Mutineer reads an optional `.mutineer.yml` from the project root (nearest one,
 walking up). CLI flags override config; config overrides defaults.
 
-Sources are positional CLI arguments and test files come from `--test`; the
-config file accepts these keys: `operators`, `threshold`, `jobs`, `only`,
-`require` (extra files to load before mutating), `boot`/`rails`, and
-`test_command` (the external-runtime suite command — see
-[Apps on Ruby < 3.4](#apps-on-ruby--34)).
+Sources are positional CLI arguments and test files come from `--test`. The
+config file accepts these keys:
+
+| Key | Value and purpose |
+|-----|-------------------|
+| `operators` | An operator name or list of names; defaults to the Tier-1 set |
+| `threshold` | A number from 0 to 100; 0 turns the score gate off |
+| `jobs` | A positive integer; the default is the processor count. `test_command`, `fail_fast`, or `--rails` without `--daemon` forces 1. |
+| `only` | A fully-qualified subject name, such as `Calculator#add` |
+| `require` | A path or list of extra files to load before mutating |
+| `boot` | The app entry point to require once before forking |
+| `rails` | `true` or `false`; enables the Rails boot defaults |
+| `since` | A nonblank git ref, or `false` to disable diff scoping |
+| `framework` | `minitest` or `rspec`; an explicit value is kept during test pairing |
+| `verbose` | `true` or `false`; shows capture diagnostics |
+| `ignore` | A mutant id or list of ids to suppress |
+| `baseline` | The path to a prior JSON report |
+| `fail_fast` | `true` or `false`; stops scheduling after the first survivor |
+| `test_command` | The external-runtime suite command, including `%{files}`; see [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34) |
+| `daemon` | `true` or `false`; uses the persistent app daemon with worker DB isolation |
+| `timeout` | A positive integer; the per-mutant time limit in seconds (default 10) |
+| `capture_timeout` | A positive integer; the coverage-capture time limit in seconds (default 120) |
+| `cache_dir` | The coverage cache directory (default `.mutineer`) |
+| `matrix` | `true` or `false`; runs every covering test for each mutant and adds the kill matrix to the report |
+
+Invalid values for known scalar keys, and a blank `operators` list, exit 2
+with a message naming the file and key. An unknown operator name warns and
+is skipped. If none of the names are known, the run exits 2. An empty
+`require` or `ignore` list is valid. Boolean keys take `true` or `false` (quoted forms also work), not `"yes"`.
+`jobs` must be positive; a string value contains digits only. String values for
+`threshold` and the CLI-only `--baseline-epsilon` use plain decimals such as `90`
+or `0.5`, not `+2`, `1e2`, or `1_0`. String options such as `only` and `baseline`
+cannot be null or boolean. A blank `since` is invalid; use `since: false` to turn
+scoping off. Unknown keys warn and are ignored. Unknown operator names warn and are skipped, and the run exits 2 when none remain. `--operators` replaces a blank or unknown file list.
+
+`format`, `strategy`, `output`, `baseline_epsilon`, and `dry_run` are CLI-only.
+For JSON output, use `--format json`, not a `format:` config key. To select RSpec
+in the file, add `framework: rspec`.
 
 ```yaml
 # .mutineer.yml
@@ -351,8 +490,40 @@ require:
 ```
 
 Coverage results are cached in `.mutineer/coverage.json` (digest-keyed; rebuilt
-automatically when sources change). Add `.mutineer/` to your `.gitignore`.
+automatically when sources change). Add `.mutineer/` to your `.gitignore`, and
+the directory you set with `--cache-dir` if it is inside the project. Keep
+`.mutineer/` ignored even then: `--test-command` writes lock files to
+`.mutineer/` beside each source file.
+
+## Mutineer and Mutant
+
+[Mutant](https://github.com/mbj/mutant), by Markus Schirp, is the established
+mutation-testing tool for Ruby. It has been in development since 2012 and is
+the subject of published research. Mutineer is a separate tool, and it shares
+no code with Mutant.
+
+| Aspect | Mutineer | Mutant |
+|---|---|---|
+| License | MIT, for every use | Free for open source (`--usage opensource`); commercial use needs a paid subscription |
+| Runtime dependencies | None (Prism + stdlib) | `parser`, `unparser`, `regexp_parser`, `sorbet-runtime` and others |
+| Ruby | 3.4 and later to run Mutineer; an app on an older Ruby works through `--test-command` (see [Apps on Ruby < 3.4](https://github.com/davidteren/mutineer#apps-on-ruby--34)) | 3.3 and later |
+| Test frameworks | Minitest and RSpec, in one gem | RSpec, Minitest and Test::Unit, one integration gem each |
+| What you mutate | Files (`mutineer run lib/foo.rb --test test/foo_test.rb`), narrowed to one method with `--only 'Foo#bar'` | Subjects named by expression (`mutant run 'Foo#bar'`, `'Foo*'`) |
+| Which tests run | The test files whose coverage reaches the mutated line | The tests that declare the subject (an RSpec description or a Minitest `cover`), or the tests that ran it in a per-test coverage recording |
+| Operators | 20 (5 by default, 15 opt-in) | A larger set; the default `light` set applies almost all of it (`full` adds `#==` to `#eql?`) |
+| CI gating | `--threshold`, `--baseline` deltas, `--since`, and a GitHub Action | Incremental mode (`--since`) and a recorded session history |
+| Machine-readable output | Versioned JSON report schema | Session JSON schema |
+
+Choose Mutineer when you want an MIT-licensed tool with no extra gems in your
+bundle, file-based runs, and a JSON contract built for CI gates and AI agents.
+Choose Mutant when you need its deeper operator set, Test::Unit support, or
+subject expressions that select whole namespaces. The two tools do not
+conflict, so you can run both on one project.
+
+This comparison describes Mutant 0.17 (checked on 2026-10-06). Check
+[Mutant's README](https://github.com/mbj/mutant#readme) for its current
+license terms and features.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/davidteren/mutineer/blob/main/LICENSE).