branchproof 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c76fa40f75fbd8122fc0fbb45a1c9d460fa3478f783951674e0e4c2707d44175
-  data.tar.gz: b4b0b88c1a0d5e61797ab52174f1841c57f1dde359d405dc1205bcff27810968
+  metadata.gz: ac29ee2c9df680fb49df3bc144ed102168320ad48908bcf9ec665521ebcfec0b
+  data.tar.gz: c31a3385bdbf3e42c538d4bd85c0120ee414da71bb184653287ab644ff7d243e
 SHA512:
-  metadata.gz: c32db269cece96c843093cc72accffd3921e56eb2a6b974b61c2d87cd696444ffd0d7fff25ed50ac3c5cadf2e6c316ccfd99aaf4f6c28344112c30451cf8e22a
-  data.tar.gz: 54a46ff6c7a753e2015bdb814d13fc576bc2d9bd88fa18d0bb4bee8f1f939fbcea62b9f006d31a3c5e99ac0d9c95de8a8bbea8d43db05c1a767c3ff828430f8b
+  metadata.gz: 9edc32c189cdbf5fbab52e224f9a2292e3cc1ec3ac20090408f0371b2dcd76198a6295059bd65be868eb041f12f62cae54b0a4a0a61e1cc7302cd6d90cfe3475
+  data.tar.gz: 2c60434afbc2940cfcb17717c37787a3560e18d8278b46fbe7e1571bd4556e7230de7648bdff883e85666be066396c3ffbdc154937913bae54dbf365cadfde7e

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-09-21
+
+- Add the first-release RSpec execution path for plain Ruby and Rails projects.
+  It supports RSpec 3.13, including Rails 8.1 with rspec-rails 8.x on CRuby 3.4.
+  Integration is verified against rspec-rails 8.0.4 and native RSpec behavior.
+- Add `--framework auto|minitest|rspec`, native RSpec discovery that respects
+  exclusions and custom patterns, full-description labels, and status mapping for pending,
+  skipped, fixed pending, and failed examples.
+- Keep Rails helper ownership with the application after Branchproof's loader;
+  transaction behavior, in-process specs, and context/suite/unattributed
+  evidence are recorded explicitly.
+- Allow focused pure-Ruby specs inside Rails projects without requiring Rails boot.
+- Match RSpec examples across saved reports only when spec and declaration
+  revisions agree, preventing false matches after examples are inserted or reordered.
+- Stream test progress to stderr, show quoted RSpec rerun commands, and explain
+  unmatched test globs, empty suites, and filters selecting no examples.
+- Document repeated ordinary and shared-example benchmarks with allocations
+  and peak process memory; end-to-end overhead remains substantial.
+
+## [0.9.0] - 2026-09-18
+
+- Measure contextual predicates, guarded pattern selection, dynamic case splat
+  groups, required pattern matching, and safe-navigation compound assignment.
+- Add coverage for rescue paths, optional argument binding, standalone
+  predicates, value alternatives, iteration, and source-visible callbacks.
+- Preserve Boolean criteria for Boolean decisions and report other choices as
+  alternative coverage, including their source locations and supporting tests.
+- Exercise 144 Ruby construct fixtures and 406 native cases across source inventory, native behavior,
+  runtime evidence, analysis, reports, saved reports, and CLI integration.
+- Preserve nonlocal control transfers on the right side of logical expressions.
+- Harden default-argument, exception, and iteration instrumentation around
+  implicit parameters, nonlocal transfers, nested frames, and deferred callbacks.
+- Remove unreachable integer bitwise alternatives and keep their exclusions out
+  of coverage denominators.
+- Cache repeated value evidence while preserving vector counts, test/phase
+  attribution, and saved-report coverage semantics.
+
 ## [0.8.0] - 2026-09-17
 
 - Derive a reduced decision table for every supported Boolean decision from its

data/README.md

@@ -1,7 +1,7 @@
 # Branchproof
 
 Branchproof measures decision, condition, modified condition/decision (MC/DC),
-and decision-table coverage from one serial Minitest run. It discovers Ruby
+and decision-table coverage from one serial Minitest or RSpec run. It discovers Ruby
 decisions through Prism, records their runtime paths, and attributes evidence
 to tests. Boolean decisions receive the coverage ladder; `case`, pattern
 alternatives, safe navigation, and conditional assignments receive alternative
@@ -22,10 +22,13 @@ Or add it to a bundle:
 bundle add branchproof
 ```
 
-Branchproof targets CRuby 3.3 and 3.4, Minitest 5.x, and Prism 1.x. The
-published core runtime matrix is the CI matrix. Rails support is optional and
-has been locally checked against Rails 8.1.3.1 on CRuby 3.4.5; Rails is
-supplied by the application and is not a runtime dependency of this gem.
+Branchproof targets CRuby 3.3 and 3.4, Minitest 5.x, RSpec 3.13, and Prism 1.x. The
+published core runtime matrix is the CI matrix. Rails/RSpec execution is limited
+to Rails 8.1.x, rspec-rails 8.x, RSpec 3.13.x, and CRuby 3.4.x; passing core
+tests on Ruby 4.0 does not imply Rails/RSpec support. Integration has been checked
+with Rails 8.1.3.1, rspec-rails 8.0.4, RSpec Core 3.13.6, and CRuby 3.4.7.
+Rails and RSpec are optional dependencies supplied by the application.
+Minitest 5.x remains a runtime dependency of this gem.
 Unsupported syntax and incomplete observations remain visible in the report
 instead of being counted as coverage.
 
@@ -33,7 +36,7 @@ instead of being counted as coverage.
 
 Run `branchproof analyze` with the source files or globs to inspect, followed by
 options. A second `--` separates Branchproof options from arguments passed to
-Minitest unchanged:
+the selected test framework:
 
 ```sh
 branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
@@ -58,22 +61,60 @@ the application's bundle and Rails version remain in effect:
 bundle exec branchproof analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
 ```
 
+Choose the test framework independently from project kind:
+
+```sh
+bundle exec branchproof analyze 'app/**/*.rb' --project rails --framework rspec
+```
+
+`--framework auto|minitest|rspec` is explicit about the adapter. Auto mode
+selects RSpec when `.rspec` or `spec/**/*_spec.rb` markers exist and Minitest
+when `test/**/*_test.rb` or `test/**/test_*.rb` markers exist. If both are
+present, specify the framework. RSpec discovery uses `spec/**/*_spec.rb`; an
+explicit `--test` selection remains authoritative. Project roots are resolved
+explicitly, and report paths are relative to that root so reports from
+different checkouts can be compared.
+
+Install `rspec` in the application's test bundle; Rails applications also need
+`rspec-rails`. RSpec reads its usual option files and `SPEC_OPTS`, including
+helper requires, filters, ordering, and file or example-ID selectors. Selectors
+from RSpec configuration replace default discovery. Combining those selectors
+with an explicit Branchproof `--test` is rejected as ambiguous; ordinary filters
+such as `--tag` and `--example` can accompany `--test`.
+
+RSpec before hooks, eager `let!`, and around-hook prefixes own setup evidence.
+The example body and helpers evaluated there own body evidence; after hooks,
+mock cleanup, and around-hook suffixes own teardown evidence. Suite and context
+hooks remain unattributed. Pending and skipped examples do not invent execution;
+an unexpectedly passing pending example remains a failure.
+
+RSpec support is serial: dry-run, bisect, DRb, custom runners, nested runs, and
+repeated example attempts are rejected. Rails/RSpec supports Rails 8.1.x with
+rspec-rails 8.x on CRuby 3.4.x. Feature and system specs use the in-process
+Capybara `rack_test` driver; browser drivers require execution-context support
+outside this release. Capybara is optional for apps that do not use those specs.
+
 For a project rooted at the current directory, `--project auto` is the
 default. It selects Rails only when both `config/application.rb` and
 `config/environment.rb` exist; otherwise it selects a plain Ruby project.
 Use `--project ruby` or `--project rails` to override detection. An explicit
 Rails project without both boot files is a usage error.
 
-Project defaults discover the sorted, de-duplicated union of
+Minitest defaults discover the sorted, de-duplicated union of
 `test/**/*_test.rb` and `test/**/test_*.rb`. Helper, support, and fixture files
 are excluded from that default set. `--test` remains authoritative when test
 files are selected explicitly. The worker prepends the project's `lib` and
-`test` directories to its child load path, so application `require` calls
+`test` directories (`lib` and `spec` for RSpec) to its child load path, so application `require` calls
 resolve without changing the parent process.
 
-Rails analysis boots `config/environment.rb` and `rails/test_help` inside the
-isolated worker after Branchproof's loader and Minitest hooks are installed. The
-child receives `RAILS_ENV=test`, `RACK_ENV=test`, `PARALLEL_WORKERS=1`,
+Rails analysis boots the application inside the isolated worker after
+Branchproof's loader and the selected framework hooks are installed. The
+application's `rails_helper` owns requiring and configuring `rspec/rails` after
+the loader; the helper must not require `branchproof` again. Selected specs
+may require only `spec_helper` and run without booting Rails,
+even when project detection selects Rails. Once Rails is loaded, Branchproof
+requires an initialized application and enforces the Rails/RSpec support limits.
+The child receives `RAILS_ENV=test`, `RACK_ENV=test`, `PARALLEL_WORKERS=1`,
 `DISABLE_BOOTSNAP=1`, and `DISABLE_SPRING=1`; the invoking process environment
 is unchanged. The Rails metadata in the report identifies the selected
 project and Rails version.
@@ -93,6 +134,17 @@ the witness pair or missing counterpart constraints beside each condition;
 Level 2 and Level 3 also list named supporting tests. Repeated supporting-set
 rows are collapsed in terminal output only.
 
+RSpec owners use the example's `full_description` and positional `example_id`.
+Terminal views include quoted rerun commands, including selectors for shared
+examples. These selectors apply to the recorded spec revision. Comparisons
+require matching spec and declaration digests before matching example owners;
+changed specs and older reports without digests are treated conservatively.
+Runner output streams to stderr while JSON reports remain on stdout.
+Pending, skipped, fixed-pending, and failed examples map to the corresponding
+baseline statuses; suite and context lifecycle events remain visible, and
+observations without a test owner are counted as unattributed. The same levels
+and terminal views are available for both adapters.
+
 For example, running the contents of the small `decision.rb` /
 `test_decision_test.rb` fixture from a project `lib/` and `test/` directory
 with the terminal format produces a summary like this:
@@ -542,6 +594,13 @@ ID. Repeated equivalent executions aggregate into a vector's `count`, retaining
 the supporting tests. Ternary outcomes likewise describe the predicate, not
 the value returned by the chosen branch.
 
+Value decisions remain enabled by default. For each decision, evidence caches
+the most recent successful completed trace, keyed by its observations, outcome,
+test, and phase. Consecutive equivalent executions increment vector and phase
+counts without repeating serialization and digest work. When observations,
+test, or phase changes, the execution is recorded normally, so alternating
+traces retain their full evidence and attribution.
+
 Other constructs use alternative coverage, separate from MC/DC:
 
 | Construct | Kind | Context | Required alternatives |
@@ -551,6 +610,18 @@ Other constructs use alternative coverage, separate from MC/DC:
 | `receiver&.method` | `implicit` | `safe_navigation` | Receiver nil / non-nil |
 | `lhs ||= rhs` | `implicit` | `or_assignment` | RHS skipped / executed |
 | `lhs &&= rhs` | `implicit` | `and_assignment` | RHS skipped / executed |
+| `receiver&.value ||= rhs` / `&&=` | `multiway` | `or_assignment` / `and_assignment` | Receiver nil / RHS skipped / RHS evaluated |
+| `value => pattern` | `pattern` | `required_pattern` | Matched / mismatch |
+| Rescue regions | `exception` | `rescue` | Normal completion / rescue clause / unhandled exception |
+| Optional positional and keyword arguments | `implicit` | `default_argument` | Supplied / default evaluated |
+| Standalone predicate calls | `implicit` | `predicate` | Falsey / truthy result |
+| `<=>` | `multiway` | `comparison` | Negative / zero / positive / nil |
+| `[]` lookup | `multiway` | `lookup` | Truthy / false / nil result |
+| `send`, `public_send`, and `__send__` | `implicit` | `dispatch` | Successful return / exception |
+| Regular-expression match capture | `implicit` | `match_capture` | False / true |
+| Iterator bodies | `implicit` | `iteration` | Empty / entered |
+| Lazy iterator callbacks | `multiway` | `lazy_callback` | Callback entered |
+| `fetch` with a fallback block | `implicit` | `fetch_fallback` | Value present / fallback entered |
 
 Each safe-navigation operation in a chain is a distinct decision. Assignment
 instrumentation preserves Ruby's native local, instance, class, global,
@@ -572,16 +643,30 @@ that fails before choosing a branch is aborted, not counted as a selected
 alternative. Selected branches and assignment paths remain observed even when
 their bodies or right-hand sides subsequently raise or return.
 
-Unsupported syntax stays visible and outside coverage denominators. Current
-exclusions include guarded `case/in` (`unsupported_pattern_guard`), dynamic
-`when` splats (`unsupported_case_splat`), safe-navigation compound assignment
-(`unsupported_assignment_target`), and rescue alternatives
-(`unsupported_rescue_control_flow`). A guard predicate can still supply Boolean
-evidence when Ruby evaluates it; an unsupported guarded case does not claim
-pattern-match coverage from that evidence. Flip-flops remain
-`unsupported_flip_flop`. Decisions inside `defined?`, contextual regular
-expressions, heredocs, unsafe predicates, and limit overflows retain explicit
-exclusions. Ruby-defined custom `!` methods keep their runtime behavior;
+Guarded pattern alternatives measure the selected clause, including guard
+acceptance. The guard also supplies Boolean evidence when Ruby evaluates it.
+A dynamic `when *candidates` is one static candidate group; the report does not
+claim coverage of individual elements in that runtime collection.
+
+Flip-flops and implicit regular-expression conditions retain Ruby's conditional
+semantics and contribute one atomic predicate outcome. `defined?` measures its
+result without evaluating or instrumenting the operand. Standalone predicate
+calls record returned truthiness as alternative coverage; they do not claim
+short-circuit conditions or coverage of library internals. Eager bitwise `&`,
+`|`, and `^` are excluded because integer results do not represent Ruby
+truthiness decisions: integer `0` is truthy in Ruby. These expressions add no
+decisions or coverage obligations.
+Dynamic dispatch records completion or exception, and preserves the original
+return value. Lazy callback observations arise only when the callback runs.
+Lookup coverage cannot distinguish an absent key from a stored nil; `fetch`
+fallback coverage measures that separate absence-based choice.
+Optional argument probes use generated local flags and preserve parameter
+signatures, defaults, and existing local bindings. Code that enumerates its own
+local variables can see these instrumentation locals.
+
+Unsupported syntax stays visible and outside coverage denominators. Heredocs,
+unsafe predicates, data sections, and limit overflows retain explicit exclusions.
+Ruby-defined custom `!` methods keep their runtime behavior;
 evidence that contradicts Boolean negation is rejected instead of proving
 coverage with an invalid logical model.
 
@@ -621,12 +706,14 @@ the serial Minitest runner. This is useful for seeds and name filters:
 branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
-The 0.2 release supports serial Minitest execution in plain Ruby projects and
-Rails applications. Rails lazy and eager loading are supported when the
-application does not enable reloading for the test run. RSpec, parallel or
-forked runners, mutation execution, Rails system/browser tests, custom Rails
-test commands, generated tests, and reloading configurations are outside this
-release and produce diagnostics rather than a passing analysis.
+The first release supports serial Minitest and RSpec execution in plain Ruby
+projects and Rails applications. Rails lazy and eager loading are supported
+when the application does not enable reloading for the test run. Transactions
+and in-process specs are supported within the serial process policy. Parallel
+or forked runners, remote or threaded browser drivers, mutation execution,
+Rails system/browser tests, custom Rails test commands, generated tests, and
+reloading configurations are explicitly unsupported and produce diagnostics
+rather than a passing analysis.
 
 ## Library entry points
 
@@ -639,7 +726,8 @@ Branchproof::Records.id(name: "stable identity")
 
 `require "mcdc"` and `MCDC` are compatibility aliases for the same public
 namespace. The CLI is the supported way to run a complete analysis;
-`Branchproof::Project` exposes project selection and child-environment policy,
+`Branchproof::Project` exposes project and framework selection and
+child-environment policy,
 and `Branchproof::RailsSupport` is the optional Rails boot boundary. The library
 classes expose the source, runtime, evidence, analysis, and report contracts
 for adapters and integrations.
@@ -672,6 +760,10 @@ Run the commands with the Ruby executable you intend to validate. The checked
 release environments are CRuby 3.3.6 and 3.4.5. Each runtime
 must provide the declared Minitest 5.x and Prism 1.x dependencies.
 
+The repeatable native-versus-instrumented adapter benchmark and its captured
+Ruby 3.4.7 result are in
+[`docs/benchmarks/rspec-adapter.md`](docs/benchmarks/rspec-adapter.md).
+
 ## License
 
 Branchproof is available under the [Apache License, Version 2.0](LICENSE.txt).

data/doc/Branchproof/DefaultInstrumentation.md

@@ -0,0 +1,13 @@
+# Module Branchproof::DefaultInstrumentation <a id="module-Branchproof-DefaultInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_instrumentation.rb |
+
+Defaults stay inline in their original lexical scope. The owner decision makes
+body entry edits part of the same original AST edit tree as the parameter
+expression edits.
+
+## Public Instance Methods
+### `rewrite(unit:)` <a id="method-i-rewrite"></a> <a id="rewrite-instance_method"></a>
+Not documented.

data/doc/Branchproof/DefaultRuntime.md

@@ -0,0 +1,11 @@
+# Module Branchproof::DefaultRuntime <a id="module-Branchproof-DefaultRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_runtime.rb |
+
+Binding events are immediate; no pending state survives a failed default.
+
+## Public Instance Methods
+### `default_binding(decision_id, index)` <a id="method-i-default_binding"></a> <a id="default_binding-instance_method"></a>
+Not documented.

data/doc/Branchproof/DefaultSyntax.md

@@ -0,0 +1,7 @@
+# Module Branchproof::DefaultSyntax <a id="module-Branchproof-DefaultSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/default_syntax.rb |
+
+Each optional parameter has an independent supplied/defaulted obligation.

data/doc/Branchproof/Evidence.md

@@ -44,3 +44,6 @@ Not documented.
 
 ### `snapshot()` <a id="method-i-snapshot"></a> <a id="snapshot-instance_method"></a>
 Not documented.
+
+### `test_phase_counts()` <a id="method-i-test_phase_counts"></a> <a id="test_phase_counts-instance_method"></a>
+Not documented.

data/doc/Branchproof/ExceptionInstrumentation.md

@@ -0,0 +1,9 @@
+# Module Branchproof::ExceptionInstrumentation <a id="module-Branchproof-ExceptionInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_instrumentation.rb |
+
+Textual edits for native rescue control flow.  The edits only add calls at
+Ruby's own protected-region and handler boundaries; exception matching, `$!`,
+retry, ensure ordering, and nonlocal transfers remain Ruby-owned.

data/doc/Branchproof/ExceptionRuntime.md

@@ -0,0 +1,27 @@
+# Module Branchproof::ExceptionRuntime <a id="module-Branchproof-ExceptionRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_runtime.rb |
+
+Record native clause selection and escaping exceptions. Generated wrappers
+re-raise the same exception; nonlocal transfers remain aborted observations.
+
+## Public Instance Methods
+### `exception_enter(decision_id, unhandled_index)` <a id="method-i-exception_enter"></a> <a id="exception_enter-instance_method"></a>
+Not documented.
+
+### `exception_finish(decision_id, value)` <a id="method-i-exception_finish"></a> <a id="exception_finish-instance_method"></a>
+Not documented.
+
+### `exception_leave(decision_id)` <a id="method-i-exception_leave"></a> <a id="exception_leave-instance_method"></a>
+Not documented.
+
+### `exception_path(decision_id, index)` <a id="method-i-exception_path"></a> <a id="exception_path-instance_method"></a>
+Not documented.
+
+### `exception_unhandled(decision_id)` <a id="method-i-exception_unhandled"></a> <a id="exception_unhandled-instance_method"></a>
+Not documented.
+
+### `exception_value(decision_id, value, index)` <a id="method-i-exception_value"></a> <a id="exception_value-instance_method"></a>
+Not documented.

data/doc/Branchproof/ExceptionSyntax.md

@@ -0,0 +1,9 @@
+# Module Branchproof::ExceptionSyntax <a id="module-Branchproof-ExceptionSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/exception_syntax.rb |
+
+Replaces unsupported standalone rescue-clause records with decisions for
+Ruby's enclosing protected region.  Ruby chooses a rescue clause as part of
+executing BeginNode; a RescueNode by itself is not executable syntax.

data/doc/Branchproof/ExtendedAlternativeRuntime.md

@@ -0,0 +1,19 @@
+# Module Branchproof::ExtendedAlternativeRuntime <a id="module-Branchproof-ExtendedAlternativeRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/extended_alternative_runtime.rb |
+
+Runtime hooks for decisions whose native evaluation has a third path. Runtime
+includes this module explicitly; it is kept separate so the ordinary two-path
+helpers remain unchanged.
+
+## Public Instance Methods
+### `flow_assignment_finish(decision_id, value, default_path = nil)` <a id="method-i-flow_assignment_finish"></a> <a id="flow_assignment_finish-instance_method"></a>
+Not documented.
+
+### `flow_assignment_path(decision_id, index)` <a id="method-i-flow_assignment_path"></a> <a id="flow_assignment_path-instance_method"></a>
+Not documented.
+
+### `flow_assignment_receiver(decision_id, receiver)` <a id="method-i-flow_assignment_receiver"></a> <a id="flow_assignment_receiver-instance_method"></a>
+Not documented.

data/doc/Branchproof/Instrumenter.md

@@ -3,7 +3,7 @@
 |  |  |
 | --- | --- |
 | **Inherits** | Object |
-| **Includes** | [Branchproof::FlowInstrumentation](FlowInstrumentation.md) |
+| **Includes** | [Branchproof::DefaultInstrumentation](DefaultInstrumentation.md), [Branchproof::ExceptionInstrumentation](ExceptionInstrumentation.md), [Branchproof::FlowInstrumentation](FlowInstrumentation.md), [Branchproof::IterationInstrumentation](IterationInstrumentation.md), [Branchproof::ValueInstrumentation](ValueInstrumentation.md) |
 | **Defined in** | lib/branchproof/instrumenter.rb |
 
 Applies the smallest possible source edits around inventoried expressions. The

data/doc/Branchproof/IterationInstrumentation.md

@@ -0,0 +1,7 @@
+# Module Branchproof::IterationInstrumentation <a id="module-Branchproof-IterationInstrumentation"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_instrumentation.rb |
+
+Keep matching and iteration in the original lexical scope.

data/doc/Branchproof/IterationRuntime.md

@@ -0,0 +1,21 @@
+# Module Branchproof::IterationRuntime <a id="module-Branchproof-IterationRuntime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_runtime.rb |
+
+Runtime support for callback based iteration, including lazy receivers whose
+callbacks execute after the constructing call has returned.
+
+## Public Instance Methods
+### `flow_iteration_begin(decision_id, receiver, alternative_count = 2)` <a id="method-i-flow_iteration_begin"></a> <a id="flow_iteration_begin-instance_method"></a>
+Not documented.
+
+### `flow_iteration_callback(decision_id, alternative_count = 2)` <a id="method-i-flow_iteration_callback"></a> <a id="flow_iteration_callback-instance_method"></a>
+rubocop:disable-next Metrics/MethodLength
+
+### `flow_iteration_finish(decision_id, value, default_path = nil)` <a id="method-i-flow_iteration_finish"></a> <a id="flow_iteration_finish-instance_method"></a>
+Not documented.
+
+### `flow_iteration_leave(decision_id)` <a id="method-i-flow_iteration_leave"></a> <a id="flow_iteration_leave-instance_method"></a>
+Not documented.

data/doc/Branchproof/IterationSyntax.md

@@ -0,0 +1,11 @@
+# Module Branchproof::IterationSyntax <a id="module-Branchproof-IterationSyntax"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/iteration_syntax.rb |
+
+Observe entry into source-visible callback bodies, not library internals.
+
+## Constants
+### `ITERATORS` <a id="constant-ITERATORS"></a> <a id="ITERATORS-constant"></a>
+Not documented.

data/doc/Branchproof/Project.md

@@ -8,6 +8,9 @@
 Resolves the project policy used by the isolated analysis worker.
 
 ## Constants
+### `FRAMEWORKS` <a id="constant-FRAMEWORKS"></a> <a id="FRAMEWORKS-constant"></a>
+Not documented.
+
 ### `MODES` <a id="constant-MODES"></a> <a id="MODES-constant"></a>
 Not documented.
 
@@ -15,7 +18,7 @@ Not documented.
 Not documented.
 
 ## Public Instance Methods
-### `initialize(root:, mode: = "auto")` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+### `initialize(root:, mode: = "auto", framework: = "auto")` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
 - **@raise** [ArgumentError]
 - **@return** [Project] a new instance of Project
 

data/doc/Branchproof/RSpecAdapter/ClassRunnerGuard.md

@@ -0,0 +1,11 @@
+# Module Branchproof::RSpecAdapter::ClassRunnerGuard <a id="module-Branchproof-RSpecAdapter-ClassRunnerGuard"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Rejects additional class-level runner entry points.
+
+## Public Instance Methods
+### `run(*args)` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter/ContextLifecycle.md

@@ -0,0 +1,14 @@
+# Module Branchproof::RSpecAdapter::ContextLifecycle <a id="module-Branchproof-RSpecAdapter-ContextLifecycle"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Keeps group-level hooks outside individual example ownership.
+
+## Public Instance Methods
+### `run_after_context_hooks(*args)` <a id="method-i-run_after_context_hooks"></a> <a id="run_after_context_hooks-instance_method"></a>
+Not documented.
+
+### `run_before_context_hooks(*args)` <a id="method-i-run_before_context_hooks"></a> <a id="run_before_context_hooks-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter/DefaultDiscovery.md

@@ -0,0 +1,11 @@
+# Module Branchproof::RSpecAdapter::DefaultDiscovery <a id="module-Branchproof-RSpecAdapter-DefaultDiscovery"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Restores CLI directory discovery when RSpec runs inside the worker.
+
+## Public Instance Methods
+### `configure(configuration)` <a id="method-i-configure"></a> <a id="configure-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter/ExampleLifecycle.md

@@ -0,0 +1,11 @@
+# Module Branchproof::RSpecAdapter::ExampleLifecycle <a id="module-Branchproof-RSpecAdapter-ExampleLifecycle"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Assigns observation phases while the reporter owns test registration.
+
+## Public Instance Methods
+### `run(*args)` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter/RunnerGuard.md

@@ -0,0 +1,11 @@
+# Module Branchproof::RSpecAdapter::RunnerGuard <a id="module-Branchproof-RSpecAdapter-RunnerGuard"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Allows only the worker-owned native runner instance.
+
+## Public Instance Methods
+### `run(*args)` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter/UnsupportedRunner.md

@@ -0,0 +1,12 @@
+# Class Branchproof::RSpecAdapter::UnsupportedRunner <a id="class-Branchproof-RSpecAdapter-UnsupportedRunner"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | ArgumentError |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Identifies runner capabilities that cannot produce supported evidence.
+
+## Public Instance Methods
+### `diagnostic_code()` <a id="method-i-diagnostic_code"></a> <a id="diagnostic_code-instance_method"></a>
+Not documented.

data/doc/Branchproof/RSpecAdapter.md

@@ -0,0 +1,47 @@
+# Class Branchproof::RSpecAdapter <a id="class-Branchproof-RSpecAdapter"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/rspec_adapter.rb |
+
+Bridges one serial RSpec run to Runtime lifecycle ownership.
+
+## Constants
+### `FORBIDDEN_OPTIONS` <a id="constant-FORBIDDEN_OPTIONS"></a> <a id="FORBIDDEN_OPTIONS-constant"></a>
+Not documented.
+
+## Attributes
+### `active_adapter` [RW] <a id="attribute-c-active_adapter"></a> <a id="active_adapter-class_method"></a>
+Returns the value of attribute active_adapter.
+
+### `runner_adapter` [RW] <a id="attribute-c-runner_adapter"></a> <a id="runner_adapter-class_method"></a>
+Returns the value of attribute runner_adapter.
+
+### `late_execution_error` [R] <a id="attribute-i-late_execution_error"></a> <a id="late_execution_error-instance_method"></a>
+Returns the value of attribute late_execution_error.
+
+### `tests` [R] <a id="attribute-i-tests"></a> <a id="tests-instance_method"></a>
+Returns the value of attribute tests.
+
+## Public Instance Methods
+### `enter_runner!(runner)` <a id="method-i-enter_runner-21"></a> <a id="enter_runner!-instance_method"></a>
+Not documented.
+
+### `example_finished(notification)` <a id="method-i-example_finished"></a> <a id="example_finished-instance_method"></a>
+Not documented.
+
+### `example_started(notification)` <a id="method-i-example_started"></a> <a id="example_started-instance_method"></a>
+Not documented.
+
+### `initialize(runtime:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [RSpecAdapter] a new instance of RSpecAdapter
+
+### `reject_execution!(message)` <a id="method-i-reject_execution-21"></a> <a id="reject_execution!-instance_method"></a>
+- **@raise** [@run_error]
+
+### `run(test_files:, runner_args:, on_complete:, before_load: = nil, after_load: = nil, test_selection_explicit: = false)` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+rubocop:disable-next Metrics/ParameterLists
+
+### `validate_runner!()` <a id="method-i-validate_runner-21"></a> <a id="validate_runner!-instance_method"></a>
+Not documented.