kimera 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b2e3996ea52017874468ff4fcb08cb447b1d2f7471613940e00d2692a6bb913
-  data.tar.gz: cd65c78f402d5249626885fa1ad74d6f1a41e7a391dad2dc6355e22e458f8b0d
+  metadata.gz: 95ba2c00cdac5d85b206e1e82ec76af626763f010f88206c756e8b91b0fb617a
+  data.tar.gz: 1212b25f14d752f02ae0144a41f09cf3cf0be48c8ffc1bfbed97ddbf765219f8
 SHA512:
-  metadata.gz: 791af57443de61ddb9e4236b89b0a669f2ce65118f8583034140eeee6c0963c6e043d93b7bb9d00d454eb245dd9bd174eb538d54ba949d9ca176898721113372
-  data.tar.gz: 33f471c99b92840396341354ae14cb8049d751545c1c3dab5cca221c9261e288d963b24c39ef13b30ec0e4f996849822cfdcf8139e5c56730aa6db20291e1067
+  metadata.gz: cbfd38f27c4f1a230a7d3919209e6e4c40e9255d1791f8e0c1676269a2d8e7496008ee3e435a131aefa7d8717c0bed405cf05459d4946e936ed282bbfb24dffd
+  data.tar.gz: 6893b2f9a4ad91dbd0d0f3acdb1922315b584efc4c018226f2ea39d88dd6f3dc2e242beef1cca9b3e6e619bd2dacbf37dd1a09010dd9768f5b5f5af740542bfe

data/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 0.1.6 (2026-09-29)
+
+- A warm worker that hits the soft timeout is replaced before it takes
+  another mutant. The timeout interrupts only the test's own thread, so
+  threads the test started (a lock holder in a concurrency test, say) kept
+  their connections, transactions and locks. Later mutants on that worker
+  blocked on them, timed out, and could be scored as kills.
+- A retiring worker's shutdown (`parallelize_teardown` hooks, emptying its
+  test database) is bounded by the hard timeout. Before, the watchdog stopped
+  watching a worker once the queue drained, so a teardown blocked on a leaked
+  lock hung `kimera run` forever.
+- Emptying a worker's test database at shutdown waits at most 5 seconds for
+  table locks on PostgreSQL and MySQL. If it gives up, kimera warns and still
+  runs the `parallelize_teardown` hooks.
+- `kimera doctor --check-baseline` lists the failing tests (up to ten) of a
+  red baseline, for RSpec and Minitest.
+- Every report result carries a `key`, such as
+  `app/models/discount.rb:44:8557dadd`, that names the mutant in any run. A
+  mutant ID numbers every mutant the run scanned, so `--focus 3740` from a
+  full report meant nothing, or a different mutant, in a one-file run. The
+  key's digest covers the mutant's own code (file, method, operator,
+  whitespace-squeezed source, label, and which repeat it is), not its line or
+  ID, so it is the same whether the run scanned one file or five hundred.
+  `kimera report` and `kimera mutant` show it next to the ID.
+- `--focus` (on `run`, `changed`, and `ci`) and `kimera mutant` accept a key
+  as well as an ID. A key whose line moved still resolves when its path and
+  digest match exactly one mutant; an unknown key is "not in scope".
+- `kimera mutant ID --report R --rerun` re-evaluates the right mutant. It
+  scanned only the mutant's file, where IDs restart at 1, then focused the
+  report's ID, so a mutant outside the report's first file was "not in scope"
+  or silently swapped for another. It now focuses the key. A report written
+  before keys existed can't be rerun; regenerate it.
+- A test that makes code call `exit` or `abort` now fails like any other
+  test. RSpec and Minitest let the `SystemExit` through, so it ended the warm
+  worker and the mutant was `harness_error` ("worker crashed before result");
+  a serial baseline exited kimera silently, and an isolated child died before
+  reporting. The test now fails after its teardown, with the exit status,
+  where it was called and `abort`'s message in the failure. A mutant that
+  makes a test abort is `killed`, and a baseline test that aborts turns the
+  baseline red with that message. `exit!` and interrupts are not caught.
+- A run whose `--tests` leaves out test files the configured `tests:` glob
+  (or the default) would run now says so above the summary: `narrowed run:
+  --tests matched 3 of 1,120 test files from the configured tests: glob;
+  survivors may be killed by tests outside it`. The JSON report's `run`
+  section records `"narrowed": true` and the configured globs. Narrowed runs
+  are faster, but their survivors (and kills that hold only within the narrow
+  set) used to read like a full run's. Verdicts are unchanged.
+- `kimera run --pidfile FILE` writes the run's process id to FILE and removes
+  it when the run ends, including on errors. Scripts waiting with `pgrep -f
+  "kimera run ..."` matched their own shell and waited forever; they can wait
+  on that pid instead.
+- `kimera run --evaluate-ignored` (also `changed` and `ci`) runs ignored
+  mutants, from `ignore:` and from the baseline, like any other. They keep
+  status `ignored`, so they never gate as survivors and still count toward
+  `max_ignored`, but each report row gains a `verdict` (`killed`,
+  `survived`, ...) and a `detail` such as `ignored (killed): ...`. The text
+  report sums them up: how many are now killed (their entries can be
+  pruned) and how many still survive. Until now a baselined mutant was never
+  evaluated, so finding out which entries were still alive meant copying
+  `.kimera.yml` without its `baseline:` line. A `--session` file keeps these
+  verdicts across resumes.
+- `kimera run --no-baseline` leaves out the `baseline:` file's entries, so
+  those mutants are judged and gated like any other; `.kimera.yml`'s own
+  `ignore:` entries still apply.
+- `kimera baseline review BASELINE.yml --report REPORT.json` judges every
+  entry against a report (best one from `--evaluate-ignored` or
+  `--no-baseline`): killed and safe to prune, still surviving, unjudged,
+  stale (the report covers the file but no mutant matches), or out of the
+  report's scope. Without `--report` it still just lists the entries.
+- `kimera baseline prune BASELINE.yml --report REPORT.json [--dry-run]`
+  rewrites the baseline without the killed and stale entries, keeping the
+  order of the rest, prints what it removed, and says by how much
+  `max_ignored` can drop. An incremental (`--since`) report holds only the
+  mutants on changed lines, so prune never treats an entry missing from it
+  as stale. Reports now record `since` in their `run` provenance for this.
+- A line-anchored ignore entry that no longer matches at its line (a line
+  was added above it) still applies when its other anchors (label, plus
+  `original` and `method` when given) single out exactly one mutant in the
+  file. Kimera warns `ignore entry re-anchored: path:12 → 13 [label]` so the
+  entry can be updated, instead of reporting it stale and bringing the same
+  mutant back as a new survivor. `baseline review` and `prune` follow the
+  same rule, and `prune` moves such entries to their current line.
+- `kimera baseline create` records each survivor's `original` snippet next
+  to its file, line, and label, so a re-anchored entry matches only the
+  mutant it was written for. Baselines without it keep working.
+
 ## 0.1.5 (2026-09-27)
 
 - Re-running a mutated concern's `included do` block no longer clobbers a

data/README.md

@@ -101,8 +101,20 @@ suite.
 bundle exec kimera run --report tmp/kimera/report.json
 bundle exec kimera report tmp/kimera/report.json --status survived
 bundle exec kimera mutant 42 --report tmp/kimera/report.json
+bundle exec kimera mutant app/models/discount.rb:44:8557dadd --report tmp/kimera/report.json
+bundle exec kimera mutant 42 --report tmp/kimera/report.json --rerun
 ```
 
+A mutant has two names. Its ID (`42`) numbers every mutant the run scanned,
+so the same mutant gets a different ID when a run covers a different set of
+files. Its key (`app/models/discount.rb:44:8557dadd`, the `key` field of each
+report result) is `path:line:digest`. The digest is computed from the mutant's
+own code (its file, method, operator, source, and label), so the key names
+the same mutant in a one-file run and in a full one. `kimera mutant` and
+`--focus` take either. A key whose line moved still resolves when the path
+and digest match exactly one mutant. `--rerun` re-evaluates only that mutant,
+focused by its key.
+
 For each survivor, write the test that kills it. If a mutant is truly
 equivalent, add it to `ignore:` in `.kimera.yml` with a reason (see
 [Configuration](#configuration)).
@@ -158,6 +170,9 @@ bundle exec kimera run app --since origin/main \
 # (a no_coverage mutant is untested new logic, not a pass)
 bundle exec kimera run app --since origin/main --fail-on-no-coverage
 
+# Evaluate only the given mutants, by report key or by ID (repeatable)
+bundle exec kimera run app/models/discount.rb --focus app/models/discount.rb:44:8557dadd
+
 # N warm workers pull from one shared queue, so this scales with cores
 # even on a single big file
 bundle exec kimera run app --jobs 4
@@ -168,6 +183,12 @@ bundle exec kimera run app --jobs 4
 # only slow under parallel load
 bundle exec kimera run app --jobs 8 --hard-timeout 60
 
+# Run only some test files, for speed. --tests replaces the configured tests:
+# glob, so verdicts hold only for those files: a survivor may be killed by a
+# test left out. The report says so ("narrowed run: --tests matched 1 of 1,120
+# test files ...", and "narrowed": true in the JSON report's run section)
+bundle exec kimera run app/models/order.rb --tests 'spec/models/order_spec.rb'
+
 # Drop spec files that can't run this way (order-dependent, need a browser)
 # without rewriting the whole --tests glob
 bundle exec kimera run app --exclude-test 'spec/system/**/*_spec.rb'
@@ -196,8 +217,26 @@ bundle exec kimera mutant 42 --report tmp/kimera/report.json
 bundle exec kimera baseline create tmp/kimera/report.json --reason "adopting Kimera"
 # Add the printed `baseline:` entry to .kimera.yml, then review it in code review
 bundle exec kimera baseline review .kimera-baseline.yml
+
+# Burn the baseline down: evaluate the ignored mutants too, see which entries
+# are now killed or stale, and drop them
+bundle exec kimera run --evaluate-ignored --report tmp/kimera/report.json
+bundle exec kimera baseline review .kimera-baseline.yml --report tmp/kimera/report.json
+bundle exec kimera baseline prune .kimera-baseline.yml --report tmp/kimera/report.json
 ```
 
+Ignored mutants, from `ignore:` or the baseline, are skipped by default.
+`--evaluate-ignored` runs them anyway: each keeps status `ignored` (it never
+gates as a survivor and still counts toward `max_ignored`) and its report row
+gains a `verdict` (`killed`, `survived`, ...). `--no-baseline` leaves the
+baseline out entirely, so its mutants are judged and gated like any other.
+
+`baseline review --report` sorts the entries into killed (safe to prune),
+still surviving, unjudged, stale (the report covers the file but no mutant
+matches), and out of the report's scope. `baseline prune` drops the killed and
+stale ones (`--dry-run` only prints them) and says how far `max_ignored` can
+drop. After an incremental `--since` run it never prunes an entry as stale.
+
 ### Output formats and exit codes
 
 - `--format json`, `ndjson`, `github`, and `sarif` write *only* that format to
@@ -206,6 +245,10 @@ bundle exec kimera baseline review .kimera-baseline.yml
 - Text output honors `NO_COLOR`. `--no-color` forces it off.
 - `--quiet` suits scripts that only need an artifact. `--verbose` prints the
   resolved scope. `--log FILE` keeps the final text report.
+- `--pidfile FILE` writes kimera's process id to FILE when the run starts and
+  removes the file when the run ends, whether it passes, fails or errors
+  (short of `kill -9`). A script that waits on a background run can watch
+  that pid; `pgrep -f "kimera run"` also matches the shell that started it.
 
 Exit codes:
 
@@ -299,7 +342,10 @@ max_ignored: 1
 
 # Known-equivalent mutants. Equivalence is undecidable, so Kimera doesn't
 # guess: you mark a mutant and it stops being a survivor. An entry without
-# a reason: is rejected at startup.
+# a reason: is rejected at startup. Anchors: file (a glob, required), line,
+# column, label, method, original. If a line anchor drifts (a line was added
+# above), the entry still applies when its label (plus original/method, if
+# given) singles out one mutant in the file; Kimera warns so you can update it.
 ignore:
   - file: app/models/discount.rb
     line: 33
@@ -519,6 +565,18 @@ source ──Prism──▶ registry (mutation points, JSON) ──┬─▶ syn
     Before the kill it asks the worker for every thread's backtrace (SIGQUIT)
     and puts them in the verdict's `detail`, or in the baseline error. A test
     interrupted by the soft timeout is a `timeout`, not the mutant's killer.
+    The interrupt reaches only the test's own thread, so threads it started
+    may still hold connections and locks: after a soft timeout the worker
+    takes no more mutants and is replaced. A retiring worker's teardown stays
+    under the hard timeout too.
+  - Code under test that calls `exit` or `abort` (a rake task, a CLI entry
+    point): RSpec and Minitest let the `SystemExit` through, so it would end
+    the worker. Kimera records it as that test's failure instead, after the
+    test's teardown, with the status, where it was called, and `abort`'s
+    message (`SystemExit: exit(1) called from lib/tasks/import.rb:12:in
+    'Kernel#abort': no such file`). A mutant that makes a test exit is killed;
+    a baseline test that exits turns the baseline red. `exit!` still ends the
+    process, and interrupts still stop the run.
   - Slow tests under parallel load: a baseline test whose worker hits the hard
     timeout reruns once, alone. If it passes, the run goes on with a notice and
     the stacks. If it times out again, the baseline is red.

data/lib/kimera/cli/baseline/entry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../../scope/ignore_list"
+
+class Kimera::CLI::Baseline::Entry
+  include Kimera::IgnoreList::Drift
+
+  KILLING = %w[killed timeout error].freeze
+  PRUNABLE = %i[killed stale].freeze
+
+  attr_reader :fields
+
+  def initialize(fields, rows, missing: :stale)
+    @fields = fields
+    @rows = rows
+    @missing = missing
+  end
+
+  def kind
+    return :out_of_scope if @rows.empty?
+    hits.empty? ? @missing : verdict
+  end
+
+  def prunable? = PRUNABLE.include?(kind)
+
+  def moved = exact.empty? ? hits.first&.fetch("line") : nil
+
+  def statuses = hits.map { |row| row["verdict"] || row["status"] }.uniq
+
+  def kept = moved ? @fields.merge("line" => moved) : @fields
+
+  def place
+    file, line, label = @fields.values_at("file", "line", "label")
+    "#{[file, line].compact.join(":")}#{" → #{moved}" if moved} [#{label}]"
+  end
+
+  private
+
+  def verdict
+    return :surviving if statuses.include?("survived")
+    (statuses - KILLING).empty? ? :killed : :unjudged
+  end
+
+  def anchors = @_anchors ||= @fields.except("file").transform_keys(&:to_sym)
+
+  def matching(anchors) = @rows.select { |row| fits?(anchors, row) }
+
+  def fits?(anchors, row)
+    anchors.all? do |key, value|
+      field = key.to_s
+      !row.key?(field) || squeeze(value) == squeeze(row[field])
+    end
+  end
+
+  def squeeze(value) = value.to_s.split.join(" ")
+end

data/lib/kimera/cli/baseline/ledger.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../report_file"
+require_relative "entry"
+
+class Kimera::CLI::Baseline::Ledger
+  attr_reader :path, :report
+
+  def initialize(path, report)
+    @path = path
+    @report = report
+  end
+
+  def document = @_document ||= YAML.safe_load_file(@path) || {}
+
+  def entries = @_entries ||= Array(document["ignore"]).map { |fields| judged(fields) }
+
+  private
+
+  def judged(fields)
+    Kimera::CLI::Baseline::Entry.new(fields, scoped(fields["file"].to_s), missing: missing)
+  end
+
+  def scoped(glob) = rows.select { |row| File.fnmatch?(glob, row["file"].to_s, File::FNM_PATHNAME) }
+
+  def rows = @_rows ||= parsed.fetch("results", [])
+
+  def missing = parsed.dig("run", "since") ? :out_of_scope : :stale
+
+  def parsed = @_parsed ||= Kimera::CLI::ReportFile.parse(@report)
+end

data/lib/kimera/cli/baseline/prune.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+class Kimera::CLI::Baseline::Prune
+  Tense = Data.define(:removed, :holds)
+  DONE = Tense.new("Removed", "now holds")
+  PREVIEW = Tense.new("Would remove", "would hold")
+
+  def initialize(ledger, io: $stdout)
+    @ledger = ledger
+    @io = io
+  end
+
+  def preview
+    summarize(PREVIEW)
+    @io.puts("(dry run: #{@ledger.path} is unchanged)")
+    0
+  end
+
+  def apply
+    summarize(DONE)
+    File.write(@ledger.path, YAML.dump(pruned)) if changed?
+    0
+  end
+
+  private
+
+  def entries = @ledger.entries
+
+  def dropped = entries.select(&:prunable?)
+
+  def kept = entries.reject(&:prunable?)
+
+  def moved = kept.select(&:moved)
+
+  def changed? = !(dropped.empty? && moved.empty?)
+
+  def pruned = @ledger.document.merge("ignore" => kept.map(&:kept))
+
+  def summarize(tense)
+    return unchanged unless changed?
+    removed(tense)
+    anchored
+    total(tense)
+  end
+
+  def unchanged = @io.puts("Nothing to prune: #{@ledger.path} keeps its #{entries.size} accepted mutant(s).")
+
+  def removed(tense)
+    return if dropped.empty?
+    @io.puts("#{tense.removed} #{dropped.size} entr(ies) from #{@ledger.path}:")
+    dropped.each { |entry| @io.puts("  - #{entry.place} (#{entry.kind})") }
+  end
+
+  def anchored
+    return if moved.empty?
+    @io.puts("Re-anchored #{moved.size} entr(ies) to their mutant's current line:")
+    moved.each { |entry| @io.puts("  #{entry.place}") }
+  end
+
+  def total(tense)
+    @io.puts(
+      "#{@ledger.path} #{tense.holds} #{kept.size} accepted mutant(s) " \
+        "(was #{entries.size}); max_ignored can be lowered by #{dropped.size}."
+    )
+  end
+end

data/lib/kimera/cli/baseline/review.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Kimera::CLI::Baseline::Review
+  Group =
+    Data.define(:kind, :title) do
+      def entries(grouped) = grouped.fetch(kind, [])
+
+      def heading(count) = "#{title} (#{count}):"
+    end
+  GROUPS = [
+    Group.new(:killed, "Killed, safe to prune"),
+    Group.new(:surviving, "Still surviving"),
+    Group.new(:unjudged, "Unjudged (no verdict in this report)"),
+    Group.new(:stale, "Stale: the report covers the file, but no mutant matches"),
+    Group.new(:out_of_scope, "Not in the report's scope")
+  ].freeze
+
+  def initialize(io: $stdout)
+    @io = io
+  end
+
+  def show(ledger)
+    entries = ledger.entries
+    @io.puts("#{entries.size} accepted mutant(s) in #{ledger.path}, judged against #{ledger.report}:")
+    groups(entries.group_by(&:kind))
+    advise(ledger, entries)
+    0
+  end
+
+  private
+
+  def groups(grouped) = GROUPS.each { |group| list(group, group.entries(grouped)) }
+
+  def list(group, entries)
+    return if entries.empty?
+    @io.puts("", group.heading(entries.size))
+    entries.each { |entry| @io.puts("  #{entry.place}#{verdicts(entry)} — #{entry.fields["reason"]}") }
+  end
+
+  def verdicts(entry)
+    statuses = entry.statuses
+    statuses.empty? ? "" : " (#{statuses.join(", ")})"
+  end
+
+  def advise(ledger, entries)
+    unevaluated(entries.count { |entry| entry.statuses.include?("ignored") })
+    prunable = entries.count(&:prunable?)
+    return if prunable.zero?
+    @io.puts("", "Prune #{prunable} entr(ies): kimera baseline prune #{ledger.path} --report #{ledger.report}")
+  end
+
+  def unevaluated(count)
+    return if count.zero?
+    @io.puts("", "#{count} entr(ies) were not evaluated: rerun with `kimera run --evaluate-ignored --report FILE`")
+  end
+end

data/lib/kimera/cli/baseline.rb

@@ -6,8 +6,9 @@ require_relative "flag"
 require_relative "report_file"
 
 class Kimera::CLI::Baseline
-  COMMANDS = { "create" => :create, "review" => :review }.freeze
+  COMMANDS = { "create" => :create, "review" => :review, "prune" => :prune }.freeze
   ENTRY_KEYS = %w[file line label].freeze
+  REPORT_FLAG = Kimera::Flag.build("--report FILE", :report, "Judge each entry against this report")
 
   CREATE = Kimera::FlagTable.new(
     banner: "Usage: kimera baseline create REPORT.json --reason TEXT [--output FILE]",
@@ -18,6 +19,16 @@ class Kimera::CLI::Baseline
     ]
   )
 
+  REVIEW = Kimera::FlagTable.new(
+    banner: "Usage: kimera baseline review BASELINE.yml [--report REPORT.json]",
+    flags: [REPORT_FLAG]
+  )
+
+  PRUNE = Kimera::FlagTable.new(
+    banner: "Usage: kimera baseline prune BASELINE.yml --report REPORT.json [--dry-run]",
+    flags: [REPORT_FLAG, Kimera::Flag.build("--dry-run", :dry_run, "Print what would change; leave the file as is")]
+  )
+
   def initialize(io: $stdout, errors: $stderr)
     @io = io
     @errors = errors
@@ -32,7 +43,9 @@ class Kimera::CLI::Baseline
 
   private
 
-  def command(name) = COMMANDS.fetch(name) { raise(Kimera::UsageError, "usage: kimera baseline <create|review> ...") }
+  def command(name)
+    COMMANDS.fetch(name) { raise(Kimera::UsageError, "usage: kimera baseline <create|review|prune> ...") }
+  end
 
   def create(argv)
     options = { reason: nil, output: ".kimera-baseline.yml", force: false }
@@ -60,13 +73,35 @@ class Kimera::CLI::Baseline
   end
 
   def review(argv)
-    file = argv.shift
-    raise(Kimera::UsageError, "usage: kimera baseline review BASELINE.yml") unless file && argv.empty?
-    raise(Kimera::UsageError, "no such baseline: #{file}") unless File.file?(file)
-    list(file, Array((YAML.safe_load_file(file) || {})["ignore"]))
+    options = { report: nil }
+    file = baseline(REVIEW, argv, options)
+    report = options[:report]
+    report ? Review.new(io: @io).show(ledger(file, report)) : list(file)
+  end
+
+  def prune(argv)
+    options = { dry_run: false }
+    file = baseline(PRUNE, argv, options)
+    report = options.fetch(:report) { raise(Kimera::UsageError, "baseline prune needs --report FILE") }
+    pruning = Prune.new(ledger(file, report), io: @io)
+    options[:dry_run] ? pruning.preview : pruning.apply
   end
 
-  def list(file, entries)
+  def baseline(table, argv, options)
+    file, *rest = table.parse(argv, options)
+    raise(Kimera::UsageError, table.banner) unless file && rest.empty?
+    existing(file)
+  end
+
+  def existing(file) = File.file?(file) ? file : raise(Kimera::UsageError, "no such baseline: #{file}")
+
+  def ledger(file, report)
+    raise(Kimera::UsageError, "no such report: #{report}") unless File.file?(report)
+    Ledger.new(file, report)
+  end
+
+  def list(file)
+    entries = Array((YAML.safe_load_file(file) || {})["ignore"])
     @io.puts("#{entries.size} accepted mutant(s) in #{file}:")
     entries.sort_by { |entry| [entry["file"], entry["line"], entry["label"]] }.each { |entry| @io.puts(line(entry)) }
     0
@@ -79,9 +114,14 @@ class Kimera::CLI::Baseline
   end
 
   def entry(row, reason)
-    id, *fields = row.values_at("mutant_id", *ENTRY_KEYS)
-    ENTRY_KEYS.zip(fields).to_h { |key, value| [key, value || missing(key, id)] }.merge("reason" => reason)
+    id, *fields, original = row.values_at("mutant_id", *ENTRY_KEYS, "original")
+    ENTRY_KEYS.zip(fields).to_h { |key, value| [key, value || missing(key, id)] }
+      .merge({ "original" => original }.compact, "reason" => reason)
   end
 
   def missing(key, id) = raise(Kimera::UsageError, "report is missing #{key} for mutant ##{id}")
 end
+
+require_relative "baseline/ledger"
+require_relative "baseline/prune"
+require_relative "baseline/review"

data/lib/kimera/cli/help_text.rb

@@ -21,12 +21,12 @@ module Kimera
 
       Investigate:
         report REPORT.json    Filter a saved report (survivors, uncovered, errors)
-        mutant ID --report R  Show one mutant in full detail
+        mutant ID --report R  Show one mutant, by ID or key, in full detail
         registry [paths...]   Inspect what Kimera would mutate
         synthesize [paths...] Write schemata sources for inspection
 
       Setup:
-        baseline ...          Create or review a baseline of accepted survivors
+        baseline ...          Create, review, or prune a baseline of accepted survivors
         completion SHELL      Print Bash, Zsh, or Fish completion setup
         skill                 Print the guide for AI agents running Kimera
         version               Print version

data/lib/kimera/cli/mutant.rb

@@ -8,7 +8,7 @@ require_relative "survivors"
 
 class Kimera::CLI::Mutant
   OPTIONS = Kimera::FlagTable.new(
-    banner: "Usage: kimera mutant ID --report REPORT.json",
+    banner: "Usage: kimera mutant ID|KEY --report REPORT.json",
     flags: [
       Kimera::Flag.build("--report FILE", :report, "Report generated by kimera run"),
       Kimera::Flag.build("--rerun", :rerun, "Re-evaluate only this mutant in the current project")
@@ -38,26 +38,25 @@ class Kimera::CLI::Mutant
   def identify(id, options)
     raise(Kimera::UsageError, "mutant ID is required") unless id
     raise(Kimera::UsageError, "--report REPORT.json is required") unless options[:report]
-    Integer(id)
-  rescue ArgumentError
-    raise(Kimera::UsageError, "mutant ID must be an integer")
+    id
   end
 
   def show(id, options)
     report = options[:report]
     return rerun(id, report) if options[:rerun]
-    Kimera::CLI::Survivors.new(io: @io, errors: @errors).run([report, "--id", id.to_s])
+    Kimera::CLI::Survivors.new(io: @io, errors: @errors).run([report, "--id", id])
   end
 
   def rerun(id, report)
     document = Kimera::CLI::ReportFile.parse(report)
     row = locate(document, id)
-    @io.puts("Re-running mutant ##{id} in #{row["file"]}.")
-    Kimera::CLI::Run.new(io: @io, errors: @errors).run(arguments_for(row, id, provenance(document)))
+    settings = provenance(document)
+    @io.puts("Re-running mutant ##{row["mutant_id"]}: #{keyed(row)}")
+    Kimera::CLI::Run.new(io: @io, errors: @errors).run(arguments_for(row, settings))
   end
 
   def locate(document, id)
-    row = document.fetch("results", []).find { |result| result["mutant_id"] == id }
+    row = Kimera::CLI::ReportFile.row(document.fetch("results", []), id)
     raise(Kimera::UsageError, "no mutant ##{id} in this report") unless row
     raise(Kimera::UsageError, "mutant ##{id} has no source file") unless row["file"]
     row
@@ -68,14 +67,21 @@ class Kimera::CLI::Mutant
       raise(Kimera::UsageError, "report has no run provenance; rerun with a report created by this Kimera version")
   end
 
-  def arguments_for(row, id, settings)
-    [row.fetch("file"), "--focus", id.to_s, "--framework", settings.fetch("framework", "rspec")]
+  def keyed(row)
+    row["key"] ||
+      raise(Kimera::UsageError, "report has no mutant keys; regenerate it with kimera run --report, then rerun")
+  end
+
+  def arguments_for(row, settings)
+    [row.fetch("file"), "--focus", keyed(row), "--framework", settings.fetch("framework", "rspec")]
       .push("--source-root", settings["source_root"])
       .concat(Array(settings["tests"]).flat_map { |glob| ["--tests", glob] })
       .push("--operators", Array(settings["operators"]).join(","))
-      .concat(modes(settings))
+      .concat(modes(settings)).concat(waived(row))
   end
 
+  def waived(row) = row["status"] == "ignored" ? ["--evaluate-ignored"] : []
+
   def modes(settings)
     [settings["coverage"] == false ? "--no-coverage" : nil, settings["isolated"] ? "--isolated" : nil].compact
   end

data/lib/kimera/cli/report_file.rb

@@ -12,6 +12,10 @@ end
 module Kimera::CLI::ReportFile
   module_function
 
+  def row(results, token)
+    results.find { |result| [result["mutant_id"].to_s, result["key"]].include?(token.to_s) }
+  end
+
   def parse(path)
     JSON.parse(File.read(path, encoding: Encoding::UTF_8))
   rescue JSON::ParserError => error

data/lib/kimera/cli/run/arguments.rb

@@ -16,20 +16,22 @@ class Kimera::CLI::Run::Arguments
 
   def finish(options, rest)
     validate(options)
-    options.except(:cli_tests).merge(scoped(options, rest))
+    options.except(:cli_tests, :baseline_ignore).merge(scoped(options, rest))
   end
 
   def validate(options) = Kimera::Report::Formats.new.normalize(options[:format])
 
   def scoped(options, rest)
     {
-      tests: Kimera::Config.prefer(options[:cli_tests], options[:tests], Kimera::CLI::RunOptions::DEFAULT_TESTS),
+      tests: tests(options[:cli_tests], options), configured_tests: tests([], options),
       paths: Kimera::Config.prefer(rest, options[:paths], Kimera::FileSet::DEFAULT_GLOBS)
     }.merge(arrays(options))
   end
 
+  def tests(cli, options) = Kimera::Config.prefer(cli, options[:tests], Kimera::CLI::RunOptions::DEFAULT_TESTS)
+
   def arrays(options)
-    { exclude: Array(options[:exclude]), ignore: Array(options[:ignore]) }
+    { exclude: Array(options[:exclude]), ignore: Kimera::Config.ignores(options) }
       .merge(isolate_when_covered_by: Array(options[:isolate_when_covered_by]), focus: Array(options[:focus]))
   end
 
@@ -46,12 +48,14 @@ class Kimera::CLI::Run::Arguments
 
   def gates
     { since: nil, session: nil, max_survivors: nil }.merge(max_ignored: nil, max_errors: 0, jobs: 1)
+      .merge(evaluate_ignored: false, baseline: nil)
   end
 
   def scope
     { exclude: [], exclude_tests: [], config: nil }
       .merge(ignore: [], isolate_db: false, isolated: false)
       .merge(fail_on_no_coverage: false, progress: nil, color: nil, quiet: false, verbose: false, log: nil)
+      .merge(pidfile: nil)
       .merge(isolate_when_covered_by: [])
       .merge(cli_tests: [])
   end