backspin 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6373427307003e8469435ce1c461e6f9bf6ff307c952bce87f07c393470f5fdc
-  data.tar.gz: 3e8487ba8345a4fef0b8419487de0e84b756c302ada8b313e2bf0e5cd6c1ec1a
+  metadata.gz: d2fd83cd35c05021e0df8e585060247f0bee2fd1034d43861bf462bbb1d67101
+  data.tar.gz: 1ee344e3596a9442d17dbbaab2aaa541d676fb2f734d13b28ad34d49948b684b
 SHA512:
-  metadata.gz: d7f1915e4632d8fb4b08ae6a8ff0e6e9846ed3f1cd783c7dcc283ca2d3816afb518173a50cd519b5859eb6d991be7636a81a48e34fb63f0176d14c9a2bdd500a
-  data.tar.gz: 7307a43c18730ec430f39dbadecb301eaad177ecc3795906f9682ec3e4781e9d5d9ec2b8c913220f8c5985393ae90e73974e5f2855a40ea17d33f87914b5a527
+  metadata.gz: 9be21d06b0087032243e2df85bfffa060fa9a8f411ce4733a125fffbdbe40ac58d2637d1f18f9b70831730917ef9aa0baff38f6021439d37c444984f7acee886
+  data.tar.gz: 2720731b166213d551c0dd58e7478e23d20637b1d4157945fcac090298ff5059fdce1c86e3e98e20087fc5bd27de52a522b35e1a124158c914c23ede4fa53dfe

data/.circleci/config.yml

@@ -12,14 +12,22 @@ jobs:
       ruby-version:
         type: string
     docker:
-      - image: cimg/ruby:<< parameters.ruby-version >>
+      - image: ghcr.io/jdx/mise:2026.9.15-debian
+    environment:
+      MISE_RUBY_VERSION: << parameters.ruby-version >>
+      MISE_YES: "1"
     steps:
       - checkout
+      - run:
+          name: Install project tools
+          command: |
+            apt-get update && apt-get install -y --no-install-recommends build-essential libyaml-dev
+            mise install
       - ruby/install-deps:
-          key: gems-v1-ruby<< parameters.ruby-version >>
+          key: gems-v2-mise-ruby<< parameters.ruby-version >>
       - run:
-          name: Run specs
-          command: bundle exec rake spec
+          name: Run specs with Plur
+          command: plur spec
       - run:
           name: Run fake gem specs
           command: bundle exec rake spec:fake_gem

data/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      previous-ref:
+        description: Tag or commit before the version increase (for retrying an unpublished release)
+        required: true
+        type: string
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    uses: rsanheim/.github/.github/workflows/gem-release.yml@4ced52859dd60019b930a3f2023424e77b37ee2a
+    with:
+      gem: backspin
+      ruby-version: "4.0.0"

data/.gitignore

@@ -7,6 +7,7 @@
 /tmp/
 /.claude
 /.cursor
+/checksums/
 
 /backspin*.gem
 # rspec failure tracking

data/.ruby-version

@@ -1 +1 @@
-4.0.0
+4

data/.standard.yml

@@ -2,6 +2,11 @@
 parallel: true
 format: progress
 
+# Match the gemspec's required_ruby_version. Without this, Standard infers the
+# target from .ruby-version (4) and flags requires that are only redundant on
+# Ruby >= 3.5 - removing them would break the 3.x versions we still support.
+ruby_version: 3.2
+
 ignore:
   - 'tmp/**/*'
   - 'vendor/**/*'

data/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
-## 0.12.0
+## 0.14.0
+* Improved verification errors with per-field summaries for stdout, stderr, and exit status, plus three lines of context around output changes. Long diffs are limited to 50 lines; set `BACKSPIN_FULL_DIFF=1` to show the full diff.
+* Preserved custom matcher failure reasons and made missing final newlines visible in output diffs.
+* Fixed `backspin_dir` configuration to accept String paths as well as Pathname objects.
+
+## 0.13.0
+* Added `Backspin.compare(reference:, actual:)` for differential testing - runs both commands live and compares their filtered output, with no record file. Only stdout, stderr, and exit status are compared, so the two commands may differ in argv and env without normalization.
+* Added `Backspin::ReferenceCommandError`, raised when a compare's reference command produces no output at all (usually a sign it failed to start), rather than comparing empty to empty.
+* Raised the minimum supported Ruby to 3.2 (3.1 reached end-of-life in March 2025).
+* Fixed snapshot timestamps to be recorded as UTC rather than local time, so re-recording in a different timezone no longer produces noisy diffs.
+* Fixed a missing `require "time"`, which could raise `NoMethodError` on `Time#iso8601` in consumers that never load the time stdlib themselves.
+
+## 0.12.0 - 2026-02-11
 * Added `BACKSPIN_MODE` environment variable to globally override recording mode (`auto`, `record`, `verify`).
 * Explicit `mode:` kwarg still takes highest precedence, followed by the env var, then auto-detection.
 * Added configurable logger to `Backspin::Configuration` (defaults to WARN level, logfmt-lite format, and can be disabled with `config.logger = nil`).

data/CLAUDE.md

@@ -24,9 +24,11 @@ bin/rspec spec/[file]:[line]    # Run specific test
 ### Building and Releasing
 ```bash
 bin/rake install     # Install gem locally for testing
-bin/rake release     # Release to RubyGems (updates version, tags, pushes)
+bin/rake build       # Build the gem locally
 ```
 
+Releases use a pull request that updates `lib/backspin/version.rb` and adds a matching nonempty section to `CHANGELOG.md`. Use normal premerge CI to establish readiness. After merge to `main`, the shared GitHub Actions workflow rechecks the version and changelog, invokes `rubygems/release-gem@v1` and Bundler for tagging and gem publication, then creates the GitHub release from the changelog notes. Invalid release notes prevent publication. See `CONTRIBUTING.md` for trusted publisher setup.
+
 ### Code Quality
 ```bash
 script/lint                      # Run Standard Ruby linter

data/CONTRIBUTING.md

@@ -11,6 +11,7 @@ Note that Backspin is in early development and the API _will_ change before stab
 - [Making Changes](#making-changes)
 - [Testing](#testing)
 - [Submitting Changes](#submitting-changes)
+- [Release Maintainer Setup](#release-maintainer-setup)
 - [Code Style](#code-style)
 - [Reporting Issues](#reporting-issues)
 - [Feature Requests](#feature-requests)
@@ -161,6 +162,25 @@ end
 - Update examples in README.md if changing public APIs
 - Ensure CI passes (tests against Ruby 3.2, 3.3, 3.4, and 4.0)
 
+## Release Maintainer Setup
+
+Before the first automated release, configure a RubyGems trusted publisher for the `backspin` gem using the [reusable workflow setup](https://guides.rubygems.org/trusted-publishing/#using-reusable-workflows):
+
+- Repository owner: `rsanheim`
+- Repository name: `backspin`
+- Workflow filename: `gem-release.yml`
+- Workflow Repository Owner: `rsanheim`
+- Workflow Repository Name: `.github`
+- Environment: `release`
+
+The workflow filename identifies the shared reusable workflow. The caller is `.github/workflows/release.yml`, which grants GitHub OIDC permission (`id-token: write`). No long-lived RubyGems API key is needed.
+
+Release pull requests update `lib/backspin/version.rb` and add a nonempty `## VERSION` section to `CHANGELOG.md`; the section body becomes the GitHub release notes. Keep the version change and its notes in the same pull request. Use the normal premerge CI checks to establish release readiness. Merging to `main` starts the release workflow, which rechecks the version and changelog before publishing; invalid release notes prevent publication. Ordinary merges do not publish anything.
+
+If publication fails before the gem is uploaded, fix the cause and manually run the Release workflow on `main`, setting `previous-ref` to the tag before the version increase. Confirm the target version is still unpublished before retrying.
+
+The shared release workflow is pinned in `.github/workflows/release.yml`. Update that commit deliberately when adopting shared release changes. Bundler's standard `build`, `install`, and `release` tasks remain available; the automated workflow is the normal publishing path.
+
 ## Code Style
 
 Backspin uses [Standard Ruby](https://github.com/standardrb/standard) for code formatting. Run the linter before committing:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    backspin (0.12.0)
+    backspin (0.14.0)
       logger
 
 GEM
@@ -9,64 +9,64 @@ GEM
   specs:
     ast (2.4.3)
     diff-lcs (1.6.2)
-    json (2.16.0)
-    language_server-protocol (3.17.0.5)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    prism (1.6.0)
+    prism (1.9.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
-    regexp_parser (2.11.3)
-    rspec (3.13.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.81.7)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.48.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.52.0)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.81.7)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    timecop (0.9.10)
+      rubocop-performance (~> 1.26.0)
+    timecop (0.9.11)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
@@ -83,4 +83,4 @@ DEPENDENCIES
   timecop (~> 0.9)
 
 BUNDLED WITH
-  4.0.5
+  4.0.16

data/README.md

@@ -75,6 +75,25 @@ end
 
 Block capture records a single combined stdout/stderr snapshot. Exit status is a placeholder (`0`) in this mode.
 
+### Differential Testing (Compare)
+
+Use `Backspin.compare` when the question is "does my tool produce the same output as this reference tool?" Both commands run live and their output is compared directly - nothing is recorded to disk:
+
+```ruby
+result = Backspin.compare(
+  reference: ["bundle", "exec", "rspec", "spec/failing_spec.rb"],
+  actual: ["my-runner", "spec/failing_spec.rb"]
+)
+
+result.expected.stdout  # reference output
+result.actual.stdout    # output from the command under test
+result.verified?        # true when they match
+```
+
+Only stdout, stderr, and exit status are compared, so the two commands can differ in argv and environment without any normalization. `filter` and `matcher` work exactly as they do for `Backspin.run`, and a mismatch raises `Backspin::VerificationError` unless `raise_on_verification_failure` is disabled.
+
+If the reference command produces no output at all - usually a sign it failed to start rather than that its output is genuinely empty - `compare` raises `Backspin::ReferenceCommandError` instead of comparing empty to empty.
+
 ### Recording Modes
 
 Backspin supports different modes for controlling how commands are recorded and verified:
@@ -211,7 +230,7 @@ Backspin.run(["echo", "id=123"], name: "record_only", filter: normalize_filter,
 
 ### Working with the Result Object
 
-The API returns a `Backspin::BackspinResult` object with helpful methods:
+The API returns a `Backspin::BackspinResult` object with details on run.
 
 ```ruby
 result = Backspin.run(["sh", "-c", "echo out; echo err >&2; exit 42"], name: "my_test")
@@ -234,6 +253,23 @@ result.error_message  # Human-readable error if verification failed
 result.diff  # Diff between expected and actual output
 ```
 
+### Verification diffs
+
+Verification errors include the failure reason and a summary of changes to stdout, stderr,
+and exit status. Output diffs show three lines of context around each change, with `...`
+where unchanged lines are omitted. A `\ No newline at end of output` marker identifies
+output without a final newline.
+
+Diffs are limited to 50 lines by default. To see every diff line, run your tests with:
+
+```sh
+BACKSPIN_FULL_DIFF=1 bundle exec rake spec
+```
+
+The limit applies to `result.diff` and the diff portion of `result.error_message`. The
+environment variable removes the size limit; unchanged lines outside the context windows
+are still omitted.
+
 ### Configuration
 
 You can configure Backspin's behavior globally:
@@ -325,16 +361,24 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 This repo also includes a decoupled full-stack fixture gem at `fixtures/projects/dummy_cli_gem` that uses Backspin the way downstream projects do. Run it with:
 
 ```bash
-bundle exec rake full_stack:dummy_app
+bundle exec rake spec:fake_gem
 ```
 
 To re-record that fixture's committed YAML snapshots:
 
 ```bash
-bundle exec rake full_stack:record_dummy_app
+bundle exec rake spec:fake_gem_record
 ```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Releasing
+
+Open a pull request that updates `lib/backspin/version.rb` and adds a nonempty matching version section to `CHANGELOG.md` (for example, `## 0.14.0`). CI checks the effective gemspec version and fails if a version change has no release notes.
+
+Use the normal premerge CI checks to establish release readiness. After the pull request merges into `main`, the shared workflow rechecks the version and changelog, then invokes `rubygems/release-gem@v1`. The official action uses OIDC trusted publishing and Bundler's standard release task to build the gem, create and push `vVERSION`, and publish to RubyGems. After the action succeeds, the shared workflow creates a GitHub release using that changelog section. Invalid release notes prevent publication. Commits that leave the gem version unchanged do not trigger a release.
+
+The release implementation lives in [`rsanheim/.github`](https://github.com/rsanheim/.github) and is pinned to a commit in `.github/workflows/release.yml`. See [the maintainer setup](CONTRIBUTING.md#release-maintainer-setup) before enabling releases.
 
 ## Contributing
 

data/Rakefile

@@ -34,5 +34,3 @@ namespace :spec do
 end
 
 task default: %i[spec standard]
-
-load "release.rake" if File.exist?("release.rake")

data/backspin.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Backspin is a Ruby library for characterization testing of command-line interfaces. Inspired by VCR's cassette-based approach, it records and replays CLI interactions to make testing faster and more deterministic."
   spec.homepage = "https://github.com/rsanheim/backspin"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage

data/docs/compare-api-plan.md

@@ -0,0 +1,193 @@
+# Compare API Plan — differential testing between two commands
+
+Date: 2026-07-20 (revised 2026-07-25)
+
+## Motivation
+
+The most common way Backspin is used in the `plur` test suite is *differential
+testing*: "does tool B produce the same output as reference tool A?" plur is a
+Go reimplementation of a parallel RSpec runner, and its golden specs assert that
+plur's output matches `rspec`'s own output byte-for-byte.
+
+Backspin has no first-class API for this, so today it is expressed as an
+implicit two-call dance with the same record name:
+
+```ruby
+# record rspec baseline
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+# verify plur against it
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+That pattern works but has sharp edges, each of which has bitten a real plur
+spec:
+
+1. **Ordering is load-bearing and invisible.** The first `run` records only
+   because the record file happens not to exist yet; if it does exist, *both*
+   calls verify against the stored baseline — a different meaning than the code
+   reads like.
+2. **A stale baseline requires a manual `rm`.** Change the fixture and the
+   committed `.yml` no longer matches the reference command, so the first call
+   fails on `reference-vs-stale-baseline`. Nothing signals that deleting the
+   snapshot is the fix.
+3. **The command line must be neutralized by hand.** The two commands *differ*
+   on purpose (`rspec …` vs `plur …`), so specs stuff `"args" => ["[PLACEHOLDER]"]`
+   into the filter to stop the recorded command from mismatching.
+4. **The filter is passed twice** and must be identical on both calls.
+5. **The dance can span two examples.** plur's minitest golden test records in
+   one `it` and verifies in a *different* `it` — order-dependent across
+   examples, so it only works because RSpec runs in defined order.
+
+The gap is small and specific: `Backspin.run` assumes the *record command* and
+the *verify command* are the same. Differential testing needs them to differ.
+
+## The idea
+
+Add `Backspin.compare`, which runs a **reference** command and an **actual**
+command and compares their (filtered) output. It is pure orchestration over
+primitives Backspin already has — no new filtering, snapshot, diff, matcher, or
+result code, and no record file.
+
+```ruby
+Backspin.compare(
+  reference:,   # String/Array command that defines correct output
+  actual:,      # String/Array command under test
+  env: nil,
+  matcher: nil, # reused as-is
+  filter: nil   # reused as-is
+)
+# => BackspinResult
+```
+
+`reference` maps to `result.expected`, `actual` maps to `result.actual` — which
+is exactly the existing `BackspinResult` contract (expected = baseline, actual =
+what just ran). See `docs/backspin-result-api-sketch.md`.
+
+## Scope: live-vs-live only
+
+An earlier draft also proposed a snapshot-backed mode (`name:` + `mode:`), where
+`compare` would record the reference to a `.yml` and later verify `actual`
+against it. That is deliberately **not** in scope:
+
+- In `mode: :verify` the `reference:` argument would be silently ignored. You
+  could change the reference command and nothing would happen until someone
+  deleted the record — sharp edge #2 wearing a new hat, plus a dead keyword arg.
+- It roughly doubles the API surface (`name`, `mode`, `BACKSPIN_MODE`,
+  `filter_on`) for a caller that does not exist yet. plur always has `rspec`
+  available, in dev and in CI.
+
+If a real caller shows up with a reference command that is expensive or absent
+in CI, add it then. `Backspin.run` already covers "freeze one command's output."
+
+## Reuse map — what each need already maps to
+
+| Need | Existing primitive | Location |
+|---|---|---|
+| Run a command → stdout/stderr/status | `execute_command(command, env)` | `lib/backspin.rb` |
+| Build a snapshot value object | `Snapshot.new(command_type: Open3::Capture3, …)` | `lib/backspin/snapshot.rb` |
+| Apply `filter` to both sides | `CommandDiff#build_comparison_snapshot` | `lib/backspin/command_diff.rb` |
+| Compare (default = stdout/stderr/status; custom matcher/hash) | `CommandDiff` + `Matcher` | `lib/backspin/command_diff.rb`, `lib/backspin/matcher.rb` |
+| `verified?` / `diff` / `summary` | `CommandDiff` | `lib/backspin/command_diff.rb` |
+| Result object (`expected`, `actual`, `verified?`, `diff`, `error_message`) | `BackspinResult` | `lib/backspin/backspin_result.rb` |
+| Raise on mismatch (config-gated) | `raise_on_verification_failure!(result)` | `lib/backspin.rb` |
+
+The heart of it: `CommandDiff.new(expected:, actual:, matcher:, filter:)`
+already takes two snapshots, applies the filter to both, runs the matcher, and
+produces `verified?`/`diff`. `compare` just has to hand it two snapshots.
+
+## Semantics that fall out for free
+
+- **args/env are not compared.** The default matcher only looks at stdout,
+  stderr, status (`Matcher#evaluate_default`), and `CommandDiff#diff` only diffs
+  those three. So two intentionally-different commands compare cleanly with no
+  `args` placeholder — deleting plur boilerplate.
+- **command_type matches.** Both sides are `Open3::Capture3`, so
+  `CommandDiff#command_types_match?` is true.
+- **Strict-by-default is preserved.** `raise_on_verification_failure!` already
+  raises `VerificationError` (with `result.diff`) unless
+  `raise_on_verification_failure = false`. `compare` reuses it verbatim.
+
+## Guard: a broken reference must not pass
+
+Live-vs-live has one failure mode the two-call dance did not: if the reference
+command fails to *run at all* — wrong directory, `bundle` not on `PATH`, a load
+error — it produces empty stdout and a non-zero status. If `actual` fails the
+same way, `verified?` is true and the spec goes green while testing nothing.
+
+`compare` raises `Backspin::ReferenceCommandError` when the reference command
+produces no output on either stream. Exit status can't be the signal: plur's
+golden specs deliberately run failing suites that exit 1.
+
+## The new code
+
+1. `Backspin.compare` public method (validation + orchestration + the guard).
+2. A private `capture_command_snapshot(command, env)` wrapping
+   `execute_command` + `Snapshot.new`. This is **extracted from existing
+   duplication** — `perform_command_run` builds that same snapshot twice, so
+   pulling it out DRYs `run` as well.
+3. One fix in `raise_on_verification_failure!`: only emit the `Record:` line
+   when there is a record path, so `compare` failures don't render a dangling
+   `Record: ` label.
+
+No changes to `CommandDiff`, `Matcher`, `Snapshot`, `Record`, or
+`BackspinResult`. `compare` lives beside `run`/`capture` in `lib/backspin.rb`.
+
+### Notes
+
+- There is no `filter_on:` keyword. `filter_on: :record` would mean "filter only
+  when persisting", and `compare` never persists — passing it would silently
+  disable filtering. Omitting the keyword makes that a plain `ArgumentError`.
+- `record_path` is `nil` on the result, and `mode` is `:verify` (nothing was
+  recorded, so `recorded?` is false).
+
+## Before / after (plur golden spec)
+
+Today (`spec/integration/spec/aggregate_failure_golden_spec.rb` in plur):
+
+```ruby
+chdir(fixture) { Backspin.run(rspec_cmd, name: "x", filter: normalize) }
+result = chdir(fixture) { Backspin.run(plur_cmd, name: "x", filter: normalize) }
+expect(result.verified?).to be(true)
+```
+
+With `compare`:
+
+```ruby
+result = chdir(fixture) do
+  Backspin.compare(reference: rspec_cmd, actual: plur_cmd, filter: normalize)
+end
+expect(result.verified?).to be(true)
+```
+
+A `dir:` option to drop the `chdir` wrapper is a possible follow-up; not needed
+here, since one wrapper now covers what took two.
+
+## Success criteria
+
+1. `Backspin.compare(reference:, actual:)` runs both and returns a
+   `BackspinResult` with `expected` = reference snapshot, `actual` = actual
+   snapshot, and boolean `verified?`.
+2. On mismatch, `result.diff` / `result.error_message` are populated by the
+   existing `CommandDiff`, and `VerificationError` is raised unless
+   `raise_on_verification_failure = false`. The failure message has no empty
+   `Record:` line.
+3. `filter` / `matcher` behave exactly as in `run` (same objects, same code
+   paths).
+4. Two commands with different argv compare on output only — no `args`
+   normalization needed.
+5. No record file is written or read.
+6. A reference command that produces no output raises
+   `ReferenceCommandError` rather than comparing empty-to-empty.
+7. No new filtering / snapshot / diff / matcher / result implementation — only a
+   `compare` entry point, the extracted `capture_command_snapshot` helper, and
+   the nil-`record_path` message fix.
+
+## Downstream: what this buys plur
+
+Six call-site pairs across four files collapse to a single call each:
+`single_failure_golden_spec.rb` (three examples), `aggregate_failure_golden_spec.rb`,
+`pending_output_spec.rb`, and `minitest_integration_spec.rb` (the cross-example
+one). Five fixture YAMLs get deleted, along with every `"args" => [...]`
+placeholder line. plur's other five Backspin specs are ordinary single-command
+snapshot tests and are untouched.

data/fixtures/projects/dummy_cli_gem/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../../..
   specs:
-    backspin (0.11.0)
+    backspin (0.14.0)
       logger
 
 PATH
@@ -40,7 +40,7 @@ DEPENDENCIES
   rspec (~> 3)
 
 CHECKSUMS
-  backspin (0.11.0)
+  backspin (0.14.0)
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   dummy_cli_gem (0.1.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203

data/fixtures/projects/dummy_cli_gem/dummy_cli_gem.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.description = "Fixture gem that shells out to unix utilities and is tested via Backspin snapshots."
   spec.homepage = "https://example.com/dummy_cli_gem"
   spec.license = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.files = Dir.chdir(__dir__) do
     Dir["lib/**/*.rb", "exe/*", "spec/**/*", "script/**/*", "README.md", "LICENSE.txt"]

data/lib/backspin/backspin_result.rb

@@ -36,10 +36,18 @@ module Backspin
       return nil unless verified? == false
       return "Output verification failed" unless @command_diff
 
-      msg = "Output verification failed:\n\n"
-      msg += @command_diff.summary
-      msg += "\n#{@command_diff.diff}" if @command_diff.diff
-      msg
+      parts = ["Output verification failed:", @command_diff.summary, "", "Summary:"]
+      @command_diff.field_summary.each do |line|
+        parts << "  #{line}"
+      end
+
+      diff = @command_diff.diff
+      if diff && !diff.empty?
+        parts << ""
+        parts << diff
+      end
+
+      parts.join("\n")
     end
 
     def success?

data/lib/backspin/command_diff.rb

@@ -3,6 +3,9 @@
 module Backspin
   # Represents the difference between expected and actual snapshots.
   class CommandDiff
+    CONTEXT_LINES = 3
+    MAX_DIFF_LINES = 50
+
     attr_reader :expected, :actual, :matcher
 
     def initialize(expected:, actual:, matcher: nil, filter: nil, filter_on: :both)
@@ -26,6 +29,15 @@ module Backspin
       @verified = @matcher.match?
     end
 
+    # @return [Array<String>] Per-field change status lines
+    def field_summary
+      lines = []
+      lines << stdout_field_summary
+      lines << stderr_field_summary
+      lines << status_field_summary
+      lines
+    end
+
     # @return [String, nil] Human-readable diff if not verified
     def diff
       return nil if verified?
@@ -48,7 +60,8 @@ module Backspin
         parts << "Exit status: expected #{expected_compare.status}, got #{actual_compare.status}"
       end
 
-      parts.join("\n\n")
+      result = parts.join("\n\n")
+      maybe_truncate(result)
     end
 
     # @return [String] Single line summary for error messages
@@ -62,6 +75,30 @@ module Backspin
 
     private
 
+    def stdout_field_summary
+      if expected_compare.stdout == actual_compare.stdout
+        "stdout: unchanged"
+      else
+        "stdout: changed"
+      end
+    end
+
+    def stderr_field_summary
+      if expected_compare.stderr == actual_compare.stderr
+        "stderr: unchanged"
+      else
+        "stderr: changed"
+      end
+    end
+
+    def status_field_summary
+      if expected_compare.status == actual_compare.status
+        "status: unchanged"
+      else
+        "status: changed (expected #{expected_compare.status}, actual #{actual_compare.status})"
+      end
+    end
+
     def command_types_match?
       expected.command_type == actual.command_type
     end
@@ -83,25 +120,77 @@ module Backspin
     end
 
     def generate_line_diff(expected, actual)
-      expected_lines = (expected || "").lines
-      actual_lines = (actual || "").lines
+      expected_lines = split_lines(expected)
+      actual_lines = split_lines(actual)
+      max_lines = [expected_lines.length, actual_lines.length].max
+
+      changed = Array.new(max_lines, false)
+      max_lines.times do |i|
+        changed[i] = (expected_lines[i] != actual_lines[i])
+      end
+
+      visible = Array.new(max_lines, false)
+      max_lines.times do |i|
+        next unless changed[i]
+        range_start = [i - CONTEXT_LINES, 0].max
+        range_end = [i + CONTEXT_LINES, max_lines - 1].min
+        (range_start..range_end).each { |j| visible[j] = true }
+      end
 
       diff_lines = []
-      max_lines = [expected_lines.length, actual_lines.length].max
+      first_visible = visible.index(true)
+      diff_lines << "..." if first_visible&.positive?
+      in_hunk = false
 
       max_lines.times do |i|
-        expected_line = expected_lines[i]
-        actual_line = actual_lines[i]
+        unless visible[i]
+          if in_hunk
+            diff_lines << "..."
+            in_hunk = false
+          end
+          next
+        end
+
+        in_hunk = true
 
-        if expected_line != actual_line
-          diff_lines << "-#{expected_line.chomp}" if expected_line
-          diff_lines << "+#{actual_line.chomp}" if actual_line
+        if changed[i]
+          diff_lines << "-#{render_line(expected_lines[i])}" if i < expected_lines.length
+          diff_lines << "+#{render_line(actual_lines[i])}" if i < actual_lines.length
+        else
+          line = expected_lines[i] || actual_lines[i]
+          diff_lines << " #{render_line(line)}"
         end
       end
 
       diff_lines.join("\n")
     end
 
+    def split_lines(value)
+      (value || "").lines
+    end
+
+    def render_line(line)
+      rendered = line.to_s.chomp
+      return rendered if line.to_s.end_with?("\n")
+
+      "#{rendered}\n\\ No newline at end of output"
+    end
+
+    def maybe_truncate(diff_text)
+      return diff_text if full_diff?
+
+      lines = diff_text.lines
+      return diff_text if lines.length <= MAX_DIFF_LINES
+
+      truncated = lines.first(MAX_DIFF_LINES).join
+      truncated.chomp!
+      truncated + "\n(diff truncated, set BACKSPIN_FULL_DIFF=1 for full output)"
+    end
+
+    def full_diff?
+      ENV["BACKSPIN_FULL_DIFF"] == "1"
+    end
+
     attr_reader :expected_compare
 
     attr_reader :actual_compare

data/lib/backspin/configuration.rb

@@ -8,7 +8,7 @@ module Backspin
   class Configuration
     attr_accessor :scrub_credentials
     # The directory where backspin will store its files - defaults to fixtures/backspin
-    attr_accessor :backspin_dir
+    attr_reader :backspin_dir
     # Whether to raise an exception when verification fails in `run`/`capture` - defaults to true
     attr_accessor :raise_on_verification_failure
     # Logger for Backspin diagnostics - defaults to WARN level, logfmt-lite format
@@ -24,6 +24,10 @@ module Backspin
       @logger = default_logger
     end
 
+    def backspin_dir=(path)
+      @backspin_dir = Pathname.new(path)
+    end
+
     def add_credential_pattern(pattern)
       @credential_patterns << pattern
     end

data/lib/backspin/record.rb

@@ -44,7 +44,7 @@ module Backspin
 
     def set_snapshot(snapshot)
       @snapshot = snapshot
-      snapshot_recorded_at = snapshot.recorded_at || Time.now.iso8601
+      snapshot_recorded_at = snapshot.recorded_at || Time.now.utc.iso8601
       @first_recorded_at ||= snapshot_recorded_at
       @recorded_at = snapshot_recorded_at
       self

data/lib/backspin/recorder.rb

@@ -26,7 +26,7 @@ module Backspin
         stdout: captured_stdout,
         stderr: captured_stderr,
         status: 0,
-        recorded_at: Time.now.iso8601
+        recorded_at: Time.now.utc.iso8601
       )
 
       record.set_snapshot(actual_snapshot)

data/lib/backspin/version.rb

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

data/lib/backspin.rb

@@ -4,6 +4,7 @@ require "yaml"
 require "fileutils"
 require "open3"
 require "pathname"
+require "time"
 require "backspin/version"
 require "backspin/configuration"
 require "backspin/snapshot"
@@ -18,6 +19,10 @@ module Backspin
 
   class RecordNotFoundError < StandardError; end
 
+  # Raised when the reference command in a compare produced no output at all,
+  # which almost always means it failed to run rather than that it is correct.
+  class ReferenceCommandError < StandardError; end
+
   class VerificationError < StandardError
     attr_reader :result
 
@@ -115,6 +120,49 @@ module Backspin
       perform_capture(record_name, mode: mode, matcher: matcher, filter: filter, filter_on: filter_on, &block)
     end
 
+    # Differential testing - runs a reference command and a command under test
+    # and compares their filtered output. Nothing is recorded to disk.
+    #
+    # Only stdout, stderr, and status are compared, so the two commands may
+    # differ in argv and env without any normalization.
+    #
+    # @param reference [String, Array] Command that defines the correct output
+    # @param actual [String, Array] Command under test
+    # @param env [Hash] Environment variables passed to both commands
+    # @param matcher [Proc, Hash] Custom matcher for verification
+    # @param filter [Proc] Custom filter applied to both sides before comparing
+    # @return [BackspinResult] expected = reference, actual = command under test
+    def compare(reference:, actual:, env: nil, matcher: nil, filter: nil)
+      normalized_env = normalize_env(env)
+
+      expected_snapshot, = capture_command_snapshot(reference, normalized_env)
+      if expected_snapshot.stdout.empty? && expected_snapshot.stderr.empty?
+        raise ReferenceCommandError,
+          "Reference command produced no output (exit status #{expected_snapshot.status}): #{reference.inspect}"
+      end
+
+      actual_snapshot, = capture_command_snapshot(actual, normalized_env)
+
+      command_diff = CommandDiff.new(
+        expected: expected_snapshot,
+        actual: actual_snapshot,
+        matcher: matcher,
+        filter: filter
+      )
+      result = BackspinResult.new(
+        mode: :verify,
+        record_path: nil,
+        actual: actual_snapshot,
+        expected: expected_snapshot,
+        verified: command_diff.verified?,
+        command_diff: command_diff
+      )
+
+      raise_on_verification_failure!(result)
+
+      result
+    end
+
     private
 
     def perform_capture(record_name, mode:, matcher:, filter:, filter_on:, &block)
@@ -147,27 +195,18 @@ module Backspin
 
       record = Record.load_or_create(record_path)
 
-      normalized_env = env.nil? ? nil : normalize_env(env)
+      normalized_env = normalize_env(env)
 
       result = case mode
       when :record
-        stdout, stderr, status = execute_command(command, normalized_env)
-        actual_snapshot = Snapshot.new(
-          command_type: Open3::Capture3,
-          args: command,
-          env: normalized_env,
-          stdout: stdout,
-          stderr: stderr,
-          status: status.exitstatus,
-          recorded_at: Time.now.iso8601
-        )
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
         record.set_snapshot(actual_snapshot)
         record.save(filter: filter)
         BackspinResult.new(
           mode: :record,
           record_path: record.path,
           actual: actual_snapshot,
-          output: [stdout, stderr, status]
+          output: output
         )
       when :verify
         raise RecordNotFoundError, "Record not found: #{record.path}" unless record.exists?
@@ -178,15 +217,7 @@ module Backspin
           raise RecordFormatError, "Invalid record format: expected Open3::Capture3 for run"
         end
 
-        stdout, stderr, status = execute_command(command, normalized_env)
-        actual_snapshot = Snapshot.new(
-          command_type: Open3::Capture3,
-          args: command,
-          env: normalized_env,
-          stdout: stdout,
-          stderr: stderr,
-          status: status.exitstatus
-        )
+        actual_snapshot, output = capture_command_snapshot(command, normalized_env)
         command_diff = CommandDiff.new(
           expected: expected_snapshot,
           actual: actual_snapshot,
@@ -201,7 +232,7 @@ module Backspin
           expected: expected_snapshot,
           verified: command_diff.verified?,
           command_diff: command_diff,
-          output: [stdout, stderr, status]
+          output: output
         )
       else
         raise ArgumentError, "Unknown mode: #{mode}"
@@ -212,7 +243,22 @@ module Backspin
       result
     end
 
+    def capture_command_snapshot(command, env)
+      stdout, stderr, status = execute_command(command, env)
+      snapshot = Snapshot.new(
+        command_type: Open3::Capture3,
+        args: command,
+        env: env,
+        stdout: stdout,
+        stderr: stderr,
+        status: status.exitstatus,
+        recorded_at: Time.now.utc.iso8601
+      )
+      [snapshot, [stdout, stderr, status]]
+    end
+
     def normalize_env(env)
+      return nil if env.nil?
       raise ArgumentError, "env must be a Hash" unless env.is_a?(Hash)
 
       env.empty? ? nil : env
@@ -234,7 +280,7 @@ module Backspin
       return unless configuration.raise_on_verification_failure && result.verified? == false
 
       error_message = "Backspin verification failed!\n"
-      error_message += "Record: #{result.record_path}\n"
+      error_message += "Record: #{result.record_path}\n" if result.record_path
       details = result.error_message || result.diff
       error_message += "\n#{details}" if details
 

data/mise.toml

@@ -1,2 +1,3 @@
 [tools]
 ruby = "4.0.0"
+"github:rsanheim/plur" = { version = "latest", minimum_release_age = "0s" }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: backspin
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Rob Sanheim
@@ -33,7 +33,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
-- ".gem_release.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
@@ -52,6 +52,7 @@ files:
 - bin/rspec
 - bin/setup
 - docs/backspin-result-api-sketch.md
+- docs/compare-api-plan.md
 - examples/match_on_example.rb
 - fixtures/backspin/.gitkeep
 - fixtures/projects/dummy_cli_gem/.rspec
@@ -83,9 +84,7 @@ files:
 - lib/backspin/snapshot.rb
 - lib/backspin/version.rb
 - mise.toml
-- release.rake
 - script/lint
-- script/run_affected_tests
 homepage: https://github.com/rsanheim/backspin
 licenses:
 - MIT
@@ -100,7 +99,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/.gem_release.yml

@@ -1,13 +0,0 @@
-# Configuration for gem-release
-bump:
-  commit: true
-  message: "Bump version to %{version}"
-  skip_ci: false
-  push: true
-
-tag:
-  tag: v%{version}
-  sign: true
-
-release:
-  host: https://rubygems.org

data/release.rake

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-
-# Simplified release tasks using gem-release
-# Install with: gem install gem-release
-# https://github.com/svenfuchs/gem-release
-namespace :release do
-  desc "Release a new version (bump, tag, release)"
-  task :version, [:level] do |t, args|
-    level = args[:level] || "patch"
-
-    # Pre-release checks
-    # Rake::Task["release:check"].invoke
-
-    puts "\nReleasing #{level} version..."
-
-    # Use gem-release to bump, tag, and release to rubygems and github
-    sh "gem bump --version #{level}"
-    new_version = File.read("lib/backspin/version.rb").match(/VERSION = "(\d+\.\d+\.\d+)"/)[1]
-
-    sh "bundle install"
-    sh "git commit -am 'Bump version to #{new_version}'"
-    sh "git push"
-
-    sh "gem release --tag --push"
-    Rake::Task["release:github"].invoke(new_version)
-  end
-
-  desc "Create GitHub release for specified version or current version"
-  task :github, [:version] do |t, args|
-    version = args[:version] || Backspin::VERSION
-
-    if system("which gh > /dev/null 2>&1")
-      puts "\nCreating GitHub release for v#{version}..."
-      sh "gh release create v#{version} --title 'Release v#{version}' --generate-notes"
-    else
-      puts "\nGitHub CLI not found. Create release manually at:"
-      puts "https://github.com/rsanheim/backspin/releases/new?tag=v#{version}"
-    end
-  end
-
-  desc "Check if ready for release"
-  task :check do
-    require "open-uri"
-    require "json"
-
-    current_version = Backspin::VERSION
-    errors = []
-
-    # Check RubyGems for latest version
-    begin
-      gem_data = JSON.parse(URI.open("https://rubygems.org/api/v1/gems/backspin.json").read)
-      latest_version = gem_data["version"]
-
-      if Gem::Version.new(current_version) <= Gem::Version.new(latest_version)
-        errors << "Current version (#{current_version}) is not greater than latest released version (#{latest_version})"
-      else
-        puts "✓ Version #{current_version} is ready for release (latest: #{latest_version})"
-      end
-    rescue => e
-      puts "⚠ Could not check RubyGems version: #{e.message}"
-    end
-
-    # Check git status
-    if system("git diff --quiet && git diff --cached --quiet")
-      puts "✓ No uncommitted changes"
-    else
-      errors << "You have uncommitted changes"
-    end
-
-    # Check branch
-    current_branch = `git rev-parse --abbrev-ref HEAD`.strip
-    if current_branch != "main"
-      puts "⚠ Not on main branch (currently on #{current_branch})"
-      print "Continue anyway? (y/N): "
-      response = $stdin.gets.chomp
-      errors << "Not on main branch" unless response.downcase == "y"
-    else
-      puts "✓ On main branch"
-    end
-
-    unless errors.empty?
-      puts "\n❌ Cannot release:"
-      errors.each { |e| puts "  - #{e}" }
-      abort
-    end
-
-    puts "\n✅ All checks passed!"
-  end
-end
-
-# Convenience tasks
-desc "Release patch version"
-task "release:patch" => ["release:version"]
-
-desc "Release minor version"
-task "release:minor" do
-  Rake::Task["release:version"].invoke("minor")
-end
-
-desc "Release major version"
-task "release:major" do
-  Rake::Task["release:version"].invoke("major")
-end

data/script/run_affected_tests

@@ -1,179 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "json"
-require "pathname"
-require "open3"
-
-class AffectedTestRunner
-  EXIT_SUCCESS = 0
-  EXIT_FAILURE = 2
-
-  def initialize
-    @project_dir = ENV["CLAUDE_PROJECT_DIR"]
-    validate_environment!
-  end
-
-  def run
-    input_data = parse_input
-    file_path = extract_file_path(input_data)
-
-    return EXIT_SUCCESS unless ruby_file?(file_path)
-
-    validated_path = validate_and_normalize_path(file_path)
-    return EXIT_SUCCESS unless validated_path
-
-    test_file = determine_test_file(validated_path)
-    return EXIT_SUCCESS unless test_file
-
-    run_tests(test_file)
-  rescue => e
-    abort_to_claude("Unexpected error: #{e.message}")
-  end
-
-  private
-
-  def validate_environment!
-    unless @project_dir
-      abort_to_claude("CLAUDE_PROJECT_DIR environment variable not set")
-    end
-
-    unless Dir.exist?(@project_dir)
-      abort_to_claude("CLAUDE_PROJECT_DIR does not exist: #{@project_dir}")
-    end
-
-    @project_path = Pathname.new(@project_dir).realpath
-  rescue => e
-    abort_to_claude("Invalid CLAUDE_PROJECT_DIR: #{e.message}")
-  end
-
-  def parse_input
-    input = $stdin.read
-    JSON.parse(input)
-  rescue JSON::ParserError => e
-    abort_to_claude("Invalid JSON input: #{e.message}")
-  end
-
-  def extract_file_path(data)
-    file_path = data.dig("tool_input", "file_path")
-
-    unless file_path && !file_path.empty?
-      abort_to_claude("No file_path provided in input")
-    end
-
-    file_path
-  end
-
-  def ruby_file?(file_path)
-    file_path.end_with?(".rb")
-  end
-
-  def validate_and_normalize_path(file_path)
-    # Expand the path to get absolute path
-    expanded_path = File.expand_path(file_path, @project_dir)
-    normalized_path = Pathname.new(expanded_path).cleanpath
-
-    # Check if the path is within the project directory
-    unless normalized_path.to_s.start_with?(@project_path.to_s)
-      log_info("File path outside project directory: #{file_path}")
-      return nil
-    end
-
-    # Convert back to relative path from project root for consistency
-    normalized_path.relative_path_from(@project_path).to_s
-  rescue => e
-    log_info("Invalid file path: #{file_path} - #{e.message}")
-    nil
-  end
-
-  def determine_test_file(file_path)
-    log_info("Determining tests for: #{file_path}")
-
-    if spec_file?(file_path)
-      # If a spec file was modified, run just that spec
-      test_file = file_path
-      log_info("Running single spec: #{test_file}")
-    elsif lib_file?(file_path)
-      # If a lib file was modified, try to find corresponding spec
-      test_file = lib_to_spec_path(file_path)
-
-      if File.exist?(File.join(@project_dir, test_file))
-        log_info("Running corresponding spec: #{test_file}")
-      else
-        # No corresponding spec found, run all tests
-        log_info("No corresponding spec found, running all tests")
-        test_file = "spec"
-      end
-    else
-      # For other Ruby files, run all tests
-      log_info("Running all tests")
-      test_file = "spec"
-    end
-
-    # Validate test file/directory exists
-    full_test_path = File.join(@project_dir, test_file)
-    unless File.exist?(full_test_path)
-      abort_to_claude("Test file/directory does not exist: #{test_file}")
-    end
-
-    test_file
-  end
-
-  def spec_file?(file_path)
-    file_path.match?(%r{^.*spec/.*_spec\.rb$})
-  end
-
-  def lib_file?(file_path)
-    file_path.match?(%r{^.*lib/.*})
-  end
-
-  def lib_to_spec_path(lib_path)
-    # Convert lib/backspin/foo.rb to spec/backspin/foo_spec.rb
-    lib_path.sub(%r{^(.*/)?lib/}, '\1spec/')
-      .sub(/\.rb$/, "_spec.rb")
-  end
-
-  def run_tests(test_file)
-    rspec_path = File.join(@project_dir, "bin", "rspec")
-
-    unless File.executable?(rspec_path)
-      abort_to_claude("rspec binary not found or not executable: #{rspec_path}")
-    end
-
-    log_info("Running: bin/rspec #{test_file}")
-
-    # Change to project directory for command execution
-    Dir.chdir(@project_dir) do
-      stdout, stderr, status = Open3.capture3("bin/rspec", test_file)
-
-      # Output both stdout and stderr
-      $stdout.print stdout
-      $stderr.print stderr
-
-      if status.success?
-        log_info("✅ Tests passed")
-        EXIT_SUCCESS
-      else
-        warn("❌ Tests failed - fix before continuing")
-        EXIT_FAILURE
-      end
-    end
-  rescue => e
-    abort_to_claude("Failed to run tests: #{e.message}")
-  end
-
-  def log_info(message)
-    warn(message)
-  end
-
-  def abort_to_claude(message)
-    warn("❌ ERROR: #{message}")
-    exit EXIT_FAILURE
-  end
-end
-
-# Run the script
-if __FILE__ == $0
-  runner = AffectedTestRunner.new
-  exit runner.run
-end