Debug exact RSpec examples

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to DebugMCP will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Fixed
+- Launch named RSpec examples using exact debugger CodeLens targets; preserve the first stop and the existing Testing API route for other languages.
+
 ## [2.3.5] - 2026-09-09
 
 ### Fixed

docs/architecture/debuggingExecutor.md

@@ -38,6 +38,13 @@ VS Code's debug API is powerful but requires careful handling. `DebuggingExecuto
 
 ## Key Concepts
 
+### Single-test dispatch
+
+For `*_spec.rb`, exact example names outrank suffix-only provider names. The requested definition line or containing
+range disambiguates candidates; otherwise ambiguous matches raise an error rather than launching another example. Modern Ruby RSpec CodeLenses omit the launch program, so the executor combines the configured
+RSpec command with the entire `file:line` quoted as one POSIX shell argument and starts `ruby_lsp` directly. Every other language and test type retains
+the original `testing.debugAtCursor` path without CodeLens interception.
+
 ### Startup Failure Diagnostics
 
 `src/utils/debugStartup.ts` observes task lifecycle events before dispatching a

docs/architecture/debuggingHandler.md

@@ -111,6 +111,10 @@ than being interpreted as successful test completion.
 Expression evaluation also distinguishes an adapter error from a successful
 command whose result/output was not captured.
 
+## RSpec stops
+
+Named RSpec examples use exact debugger CodeLens dispatch. The first stopped frame is returned unchanged; the handler never infers an entry pause from source-breakpoint mismatch or automatically continues it. See [RSpec debugging](../rspec-debugging.md).
+
 ## Variable inspection
 
 For `ruby_lsp` sessions, Ruby scalar values keep their result even when rdbg attaches metadata children. Synthetic `#class` and `%ancestors` children are omitted only for Ruby. Existing secret redaction and names/types-only descendant rendering remain in force.

docs/rspec-debugging.md

@@ -0,0 +1,38 @@
+# RSpec debugging
+
+Requires Shopify Ruby LSP, the `debug` gem, and `ruby-lsp-rspec` in the active bundle, with CodeLens enabled.
+
+## Debugging one RSpec example
+
+Set the breakpoint in the application or example, then call `start_debugging` with:
+
+- `fileFullPath` set to the spec file;
+- `workingDirectory` set to the bundle root;
+- `testName` set to the example you want to debug.
+
+DebugMCP prefers the matching Ruby LSP debugger CodeLens and preserves its exact `file:line` target. This matters for
+nested example groups and files containing many examples; a whole-file launch can exercise unrelated setup and hide the
+original failure. Exact names take priority over suffix matches; ambiguous matches fail with a diagnostic instead
+of selecting an unrelated example. Generated `file:line` targets are quoted as a single POSIX shell argument, including
+embedded quotes and expansion characters. Provider-supplied programs and the configured runner command stay unchanged.
+
+If the debugger CodeLens is missing:
+
+1. Confirm `ruby-lsp-rspec` is in the active bundle and run `bundle install`.
+2. Confirm Ruby LSP's `codeLens` feature is enabled.
+3. Run **Ruby LSP: Restart** and inspect the **Ruby LSP** Output channel for activation or bundle errors.
+4. If the project needs a wrapper, container command, or non-default bundle, configure the add-on's `rspecCommand`:
+
+```json
+{
+  "rubyLsp.addonSettings": {
+    "Ruby LSP RSpec": {
+      "rspecCommand": "bin/rspec"
+    }
+  }
+}
+```
+
+`rdbg` may pause before the requested breakpoint. DebugMCP returns that first stop unchanged. Inspect it before
+calling `continue_execution`: an unmatched source breakpoint does not distinguish entry from an exception or an
+explicit `debugger` stop. Automatic continuation is deliberately not part of this dispatch path.