branchproof 0.9.0 → 0.11.0

data/doc/Branchproof/RailsSupport.md

@@ -6,16 +6,31 @@
 
 Boots the selected Rails application after Branchproof's load hook is active.
 
+## Constants
+### `SUPPORTED_CAPYBARA_DRIVER` <a id="constant-SUPPORTED_CAPYBARA_DRIVER"></a> <a id="SUPPORTED_CAPYBARA_DRIVER-constant"></a>
+Not documented.
+
+### `SUPPORTED_RAILS` <a id="constant-SUPPORTED_RAILS"></a> <a id="SUPPORTED_RAILS-constant"></a>
+Not documented.
+
+### `SUPPORTED_RSPEC_RAILS_MAJOR` <a id="constant-SUPPORTED_RSPEC_RAILS_MAJOR"></a> <a id="SUPPORTED_RSPEC_RAILS_MAJOR-constant"></a>
+Not documented.
+
 ## Public Class Methods
 ### `boot(project:)` <a id="method-c-boot"></a> <a id="boot-class_method"></a>
-Not documented.
+Boot the Rails application for the native Minitest adapter.
 
 ### `boot_environment(environment)` <a id="method-c-boot_environment"></a> <a id="boot_environment-class_method"></a>
-Not documented.
+Require the application and validate the process-wide Rails policy. This
+method is public so adapter-specific helpers can own the remaining test
+framework setup while sharing the exact same Rails boot checks.
 
 ### `environment_path(project)` <a id="method-c-environment_path"></a> <a id="environment_path-class_method"></a>
 Not documented.
 
+### `install_rspec_driver_guard!()` <a id="method-c-install_rspec_driver_guard-21"></a> <a id="install_rspec_driver_guard!-class_method"></a>
+Not documented.
+
 ### `metadata()` <a id="method-c-metadata"></a> <a id="metadata-class_method"></a>
 Not documented.
 
@@ -25,8 +40,26 @@ Not documented.
 ### `reloading_enabled?(config)` <a id="method-c-reloading_enabled-3F"></a> <a id="reloading_enabled?-class_method"></a>
 - **@return** [Boolean]
 
+### `rspec_rails_version()` <a id="method-c-rspec_rails_version"></a> <a id="rspec_rails_version-class_method"></a>
+Not documented.
+
 ### `validate_application!()` <a id="method-c-validate_application-21"></a> <a id="validate_application!-class_method"></a>
 - **@raise** [Error]
 
+### `validate_rspec!(project:)` <a id="method-c-validate_rspec-21"></a> <a id="validate_rspec!-class_method"></a>
+Validate the seam after an RSpec Rails helper has loaded. RSpec owns requiring
+rspec/rails and configuring its example groups; this method only checks that
+that setup is attached to the same, already-validated Rails application.
+- **@raise** [Error]
+
+### `validate_rspec_driver!(example_metadata)` <a id="method-c-validate_rspec_driver-21"></a> <a id="validate_rspec_driver!-class_method"></a>
+RSpec Rails invokes this at example execution time, before the example can ask
+Capybara to launch a browser. The adapter converts this explicit rejection
+into an incomplete/error execution result.
+- **@raise** [Error]
+
 ### `validate_test_environment()` <a id="method-c-validate_test_environment"></a> <a id="validate_test_environment-class_method"></a>
 - **@raise** [Error]
+
+### `validate_version_tuple!(rails_metadata)` <a id="method-c-validate_version_tuple-21"></a> <a id="validate_version_tuple!-class_method"></a>
+- **@raise** [Error]

data/doc/Branchproof/Report.md

@@ -24,7 +24,7 @@ Not documented.
 Not documented.
 
 ## Public Class Methods
-### `from_document(document:, level: = nil, view: = :decisions, missing_only: = false)` <a id="method-c-from_document"></a> <a id="from_document-class_method"></a>
+### `from_document(document:, level: = nil, view: = :decisions, missing_only: = false, focus: = nil, top: = nil, minimum: = nil)` <a id="method-c-from_document"></a> <a id="from_document-class_method"></a>
 Not documented.
 
 ## Public Instance Methods
@@ -38,6 +38,12 @@ Shares the existing missing-case wording with focused terminal views.
 ### `coverage_ladder_lines()` <a id="method-i-coverage_ladder_lines"></a> <a id="coverage_ladder_lines-instance_method"></a>
 Render the shared ladder in every terminal view.
 
+### `coverage_policy()` <a id="method-i-coverage_policy"></a> <a id="coverage_policy-instance_method"></a>
+Not documented.
+
+### `coverage_policy_lines()` <a id="method-i-coverage_policy_lines"></a> <a id="coverage_policy_lines-instance_method"></a>
+Not documented.
+
 ### `coverage_status_label(status)` <a id="method-i-coverage_status_label"></a> <a id="coverage_status_label-instance_method"></a>
 Not documented.
 
@@ -56,9 +62,12 @@ Formats source context consistently in live and saved terminal views.
 ### `exit_code()` <a id="method-i-exit_code"></a> <a id="exit_code-instance_method"></a>
 Not documented.
 
-### `initialize(inventory:, evidence:, analysis:, minima:, baseline:, diagnostics:, level: = 3, missing_only: = false, view: = :decisions, run_metadata: = {}, saved_document: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+### `initialize(inventory:, evidence:, analysis:, minima:, baseline:, diagnostics:, level: = 3, missing_only: = false, view: = :decisions, run_metadata: = {}, saved_document: = nil, focus: = nil, top: = nil, minimum: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
 - **@raise** [ArgumentError]
 - **@return** [Report] a new instance of Report
 
+### `rerun_command(test_id)` <a id="method-i-rerun_command"></a> <a id="rerun_command-instance_method"></a>
+Not documented.
+
 ### `write(io:, format:)` <a id="method-i-write"></a> <a id="write-instance_method"></a>
 - **@raise** [ArgumentError]

data/doc/Branchproof/ReportSelection.md

@@ -0,0 +1,42 @@
+# Class Branchproof::ReportSelection <a id="class-Branchproof-ReportSelection"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/report_selection.rb |
+
+Validates and applies terminal-only report display filters. rubocop:disable
+Metrics/ClassLength, Metrics/AbcSize, Metrics/CyclomaticComplexity,
+Metrics/MethodLength, Metrics/PerceivedComplexity
+
+## Attributes
+### `focus` [R] <a id="attribute-i-focus"></a> <a id="focus-instance_method"></a>
+Returns the value of attribute focus.
+
+### `top` [R] <a id="attribute-i-top"></a> <a id="top-instance_method"></a>
+Returns the value of attribute top.
+
+## Public Instance Methods
+### `active?()` <a id="method-i-active-3F"></a> <a id="active?-instance_method"></a>
+- **@return** [Boolean]
+
+### `filter_decisions(decisions, inventory: = {})` <a id="method-i-filter_decisions"></a> <a id="filter_decisions-instance_method"></a>
+Not documented.
+
+### `focus_active?()` <a id="method-i-focus_active-3F"></a> <a id="focus_active?-instance_method"></a>
+- **@return** [Boolean]
+
+### `focus_label()` <a id="method-i-focus_label"></a> <a id="focus_label-instance_method"></a>
+Not documented.
+
+### `initialize(focus: = nil, top: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [ReportSelection] a new instance of ReportSelection
+
+### `limit(items)` <a id="method-i-limit"></a> <a id="limit-instance_method"></a>
+Not documented.
+
+### `matching_decision_ids(document)` <a id="method-i-matching_decision_ids"></a> <a id="matching_decision_ids-instance_method"></a>
+Not documented.
+
+### `sort_key(decision, inventory: = {})` <a id="method-i-sort_key"></a> <a id="sort_key-instance_method"></a>
+Not documented.

data/doc/Branchproof/Runtime.md

@@ -108,6 +108,9 @@ Metrics/PerceivedComplexity
 ### `snapshot()` <a id="method-c-snapshot"></a> <a id="snapshot-class_method"></a>
 Not documented.
 
+### `test_phase_counts()` <a id="method-c-test_phase_counts"></a> <a id="test_phase_counts-class_method"></a>
+Not documented.
+
 ### `value_path(decision_id, value, domain)` <a id="method-c-value_path"></a> <a id="value_path-class_method"></a>
 rubocop:disable-next Metrics/MethodLength -- trace state branches are
 explicit. rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity,

data/doc/Branchproof/Worker.md

@@ -4,9 +4,12 @@
 | --- | --- |
 | **Defined in** | lib/branchproof/worker.rb |
 
-Runs one isolated Minitest worker and atomically exports its result.
+Runs one isolated test worker and atomically exports its result.
 
 ## Public Class Methods
+### `adapter_for(project, runtime)` <a id="method-c-adapter_for"></a> <a id="adapter_for-class_method"></a>
+Not documented.
+
 ### `boot_project(project)` <a id="method-c-boot_project"></a> <a id="boot_project-class_method"></a>
 Not documented.
 
@@ -17,6 +20,10 @@ Not documented.
 This result boundary intentionally carries the complete worker payload.
 rubocop:disable-next Metrics/ParameterLists
 
+### `guard_late_rspec_execution(adapter, payload)` <a id="method-c-guard_late_rspec_execution"></a> <a id="guard_late_rspec_execution-class_method"></a>
+Installed before application hooks, so this runs after their at_exit work. A
+rescued second runner must still invalidate the already-exported result.
+
 ### `incomplete_evidence(evidence, diagnostics)` <a id="method-c-incomplete_evidence"></a> <a id="incomplete_evidence-class_method"></a>
 Not documented.
 

data/doc/Branchproof.md

@@ -2,7 +2,7 @@
 
 |  |  |
 | --- | --- |
-| **Defined in** | lib/branchproof.rb, lib/branchproof/cli.rb, lib/branchproof/limits.rb, lib/branchproof/loader.rb, lib/branchproof/report.rb, lib/branchproof/source.rb, lib/branchproof/worker.rb, lib/branchproof/project.rb, lib/branchproof/records.rb, lib/branchproof/runtime.rb, lib/branchproof/version.rb, lib/branchproof/analyzer.rb, lib/branchproof/evidence.rb, lib/branchproof/minimizer.rb, lib/branchproof/comparison.rb, lib/branchproof/constraints.rb, lib/branchproof/instrumenter.rb, lib/branchproof/runtime_flow.rb, lib/branchproof/saved_report.rb, lib/branchproof/value_syntax.rb, lib/branchproof/rails_support.rb, lib/branchproof/value_runtime.rb, lib/branchproof/coverage_index.rb, lib/branchproof/decision_table.rb, lib/branchproof/default_syntax.rb, lib/branchproof/focused_report.rb, lib/branchproof/decision_syntax.rb, lib/branchproof/default_runtime.rb, lib/branchproof/exception_syntax.rb, lib/branchproof/iteration_syntax.rb, lib/branchproof/minitest_adapter.rb, lib/branchproof/comparison_report.rb, lib/branchproof/exception_runtime.rb, lib/branchproof/iteration_runtime.rb, lib/branchproof/flow_instrumentation.rb, lib/branchproof/value_instrumentation.rb, lib/branchproof/default_instrumentation.rb, lib/branchproof/exception_instrumentation.rb, lib/branchproof/iteration_instrumentation.rb, lib/branchproof/extended_alternative_runtime.rb |
+| **Defined in** | lib/branchproof.rb, lib/branchproof/cli.rb, lib/branchproof/limits.rb, lib/branchproof/loader.rb, lib/branchproof/report.rb, lib/branchproof/source.rb, lib/branchproof/worker.rb, lib/branchproof/project.rb, lib/branchproof/records.rb, lib/branchproof/runtime.rb, lib/branchproof/version.rb, lib/branchproof/analyzer.rb, lib/branchproof/evidence.rb, lib/branchproof/minimizer.rb, lib/branchproof/comparison.rb, lib/branchproof/constraints.rb, lib/branchproof/instrumenter.rb, lib/branchproof/runtime_flow.rb, lib/branchproof/saved_report.rb, lib/branchproof/value_syntax.rb, lib/branchproof/configuration.rb, lib/branchproof/rails_support.rb, lib/branchproof/rspec_adapter.rb, lib/branchproof/value_runtime.rb, lib/branchproof/coverage_index.rb, lib/branchproof/decision_table.rb, lib/branchproof/default_syntax.rb, lib/branchproof/focused_report.rb, lib/branchproof/coverage_policy.rb, lib/branchproof/decision_syntax.rb, lib/branchproof/default_runtime.rb, lib/branchproof/exception_syntax.rb, lib/branchproof/iteration_syntax.rb, lib/branchproof/minitest_adapter.rb, lib/branchproof/report_selection.rb, lib/branchproof/comparison_report.rb, lib/branchproof/exception_runtime.rb, lib/branchproof/iteration_runtime.rb, lib/branchproof/flow_instrumentation.rb, lib/branchproof/value_instrumentation.rb, lib/branchproof/default_instrumentation.rb, lib/branchproof/exception_instrumentation.rb, lib/branchproof/iteration_instrumentation.rb, lib/branchproof/extended_alternative_runtime.rb |
 
 Keep source-boundary and parameter-binding rules together for auditing.
 rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity,
@@ -18,9 +18,11 @@ Not documented.
 - [Branchproof/CLI.md](Branchproof/CLI.md)
 - [Branchproof/Comparison.md](Branchproof/Comparison.md)
 - [Branchproof/ComparisonReport.md](Branchproof/ComparisonReport.md)
+- [Branchproof/Configuration.md](Branchproof/Configuration.md)
 - [Branchproof/Constraints/Solver.md](Branchproof/Constraints/Solver.md)
 - [Branchproof/Constraints.md](Branchproof/Constraints.md)
 - [Branchproof/CoverageIndex.md](Branchproof/CoverageIndex.md)
+- [Branchproof/CoveragePolicy.md](Branchproof/CoveragePolicy.md)
 - [Branchproof/DecisionSyntax.md](Branchproof/DecisionSyntax.md)
 - [Branchproof/DecisionTable.md](Branchproof/DecisionTable.md)
 - [Branchproof/DefaultInstrumentation.md](Branchproof/DefaultInstrumentation.md)
@@ -43,10 +45,18 @@ Not documented.
 - [Branchproof/Minimizer.md](Branchproof/Minimizer.md)
 - [Branchproof/MinitestAdapter.md](Branchproof/MinitestAdapter.md)
 - [Branchproof/Project.md](Branchproof/Project.md)
+- [Branchproof/RSpecAdapter/ClassRunnerGuard.md](Branchproof/RSpecAdapter/ClassRunnerGuard.md)
+- [Branchproof/RSpecAdapter/ContextLifecycle.md](Branchproof/RSpecAdapter/ContextLifecycle.md)
+- [Branchproof/RSpecAdapter/DefaultDiscovery.md](Branchproof/RSpecAdapter/DefaultDiscovery.md)
+- [Branchproof/RSpecAdapter/ExampleLifecycle.md](Branchproof/RSpecAdapter/ExampleLifecycle.md)
+- [Branchproof/RSpecAdapter/RunnerGuard.md](Branchproof/RSpecAdapter/RunnerGuard.md)
+- [Branchproof/RSpecAdapter/UnsupportedRunner.md](Branchproof/RSpecAdapter/UnsupportedRunner.md)
+- [Branchproof/RSpecAdapter.md](Branchproof/RSpecAdapter.md)
 - [Branchproof/RailsSupport/Error.md](Branchproof/RailsSupport/Error.md)
 - [Branchproof/RailsSupport.md](Branchproof/RailsSupport.md)
 - [Branchproof/Records.md](Branchproof/Records.md)
 - [Branchproof/Report.md](Branchproof/Report.md)
+- [Branchproof/ReportSelection.md](Branchproof/ReportSelection.md)
 - [Branchproof/Runtime.md](Branchproof/Runtime.md)
 - [Branchproof/RuntimeFlow.md](Branchproof/RuntimeFlow.md)
 - [Branchproof/SavedReport.md](Branchproof/SavedReport.md)

data/doc/CHANGELOG.md

@@ -1,5 +1,47 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-25
+
+- Add validated coverage policies for Decision, Condition, Condition/Decision,
+  MC/DC, and Decision Table criteria. Repeatable `--minimum criterion=threshold`
+  options override matching project or saved-report policy entries, compare
+  exact counts, and distinguish failed gates from unavailable or incomplete
+  evidence in exit status and JSON.
+- Persist policy decisions in live schema `1.4` reports while keeping saved
+  schemas `1.0` through `1.3` readable; offline policy overrides do not load
+  project configuration or mutate snapshots.
+- Add terminal-only `--focus PATH[:LINE]` and `--top N` selection for analyze
+  and report views. Selection uses captured source spans and deterministic source
+  order while leaving global summaries, gates, diagnostics, and exit status
+  unchanged.
+- Document a GitHub Actions artifact workflow that creates the output directory
+  and uploads reports after gate failures.
+- Preserve setup, body, and teardown phase totals when independent evidence runs
+  are merged, keeping phase attribution complete in combined snapshots.
+- Add declarative `.branchproof.json` project configuration with CLI precedence,
+  source exclusions, and comparison metadata for repeatable coverage runs.
+- Add a pipeline benchmark harness that exposes timing dimensions for future
+  measurements of coverage feedback costs.
+
+## [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

data/doc/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,126 @@ 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`,
+Project defaults can be checked into `.branchproof.json` at the project root:
+
+```json
+{
+  "schema_version": 1,
+  "project": "rails",
+  "framework": "minitest",
+  "sources": ["app/**/*.rb"],
+  "tests": ["test/**/*_test.rb"],
+  "exclude": ["app/generated/**/*.rb"],
+  "minimum": { "mcdc": 80 }
+}
+```
+
+`project` accepts `auto`, `ruby`, or `rails`; `framework` accepts `auto`,
+`minitest`, or `rspec`. `sources` and `tests` replace their corresponding
+defaults, while `exclude` removes matching source files before inventory. A
+configuration file may live elsewhere when passed with `--config PATH`; its
+patterns are still resolved from the project root. Use `--no-config` to disable
+the default file. Command-line project, framework, source, and test selections
+take precedence over the file. Configured `exclude` patterns are applied
+before source inventory and are recorded in run metadata for comparison.
+`--config` and `--no-config` cannot be used together. RSpec configuration
+selectors continue to conflict with an explicit test selection, including one
+supplied by this file.
+
+The `minimum` values are validated percentages from 0 through 100 for the five
+supported criteria: `decision`, `condition`, `condition_decision`, `mcdc`, and
+`decision_table`. A policy is evaluated against the exact numerator and
+denominator counts in the report, so a value such as `66.67` is not rounded
+before it is compared. The policy is recorded in JSON under
+`coverage_policy`.
+
+The command line can add or replace individual policy entries with repeatable
+`--minimum` options. Use `criterion=threshold`, for example:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --minimum mcdc=80 \
+  --minimum decision_table=75
+```
+
+CLI values take precedence over matching `minimum` keys from `.branchproof.json`.
+Specifying the same criterion more than once on the command line is an error.
+The five criteria are evaluated independently. A threshold met exactly passes;
+a result below it fails. A requested gate with a zero denominator, unavailable
+coverage, or incomplete observations or analysis is `unavailable`, and exits
+with status 2. A below-threshold gate exits 1. A failed test run makes
+requested policy gates unavailable and exits 2; without a policy, a failed test
+run retains the existing exit status 1. With no policy, the existing report
+exit behavior remains unchanged.
+
+For a Minitest project, a focused configuration can select the library and
+test trees directly:
+
+```json
+{ "schema_version": 1, "framework": "minitest",
+  "sources": ["lib/**/*.rb"], "tests": ["test/**/*_test.rb"] }
+```
+
+For an RSpec project, use its spec patterns instead:
+
+```json
+{ "schema_version": 1, "framework": "rspec",
+  "sources": ["app/**/*.rb"], "tests": ["spec/**/*_spec.rb"] }
+```
+
+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 +200,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:
@@ -156,6 +274,15 @@ that did evaluate count toward Condition Coverage even when their value was
 masked by another condition. Here, the two observations prove independence
 for `logged_in?`; `admin?` still needs `[TF] => F`.
 
+This is also a compact test-design walkthrough. A test that records
+`[F-] => F` proves the false branch of `logged_in?`; a test that records
+`[TT] => T` proves the true branch and establishes the current positive path.
+Adding a test that records `[TF] => F` evaluates `admin?` false while
+`logged_in?` stays true, so it supplies the missing independence witness and
+improves the condition, Condition/Decision, MC/DC, and applicable decision-table
+results. The report names the missing vector and its owning test when it is
+observed.
+
 Decision and Condition Coverage are calculated independently from the captured
 evidence. Condition/Decision requires both; MC/DC adds independence evidence.
 Decision Table Coverage is calculated independently of all of them: MC/DC asks
@@ -449,6 +576,34 @@ execution. JSON output always contains the complete evidence document, so an
 explicit view cannot be combined with `--format json`. The `mcdc` executable
 accepts the same arguments for existing scripts.
 
+Terminal reports can be narrowed with `--focus PATH[:LINE]` and bounded with
+`--top N`, where `N` is a positive integer. These options are accepted by
+`analyze` and `report`, and are terminal-only. Focus matches the source spans
+captured in the report; rendering does not reopen or need the original source
+file. `--focus` and `--top` affect displayed detail only: the coverage summary,
+policy gates, diagnostics, exit status, and global counts remain unchanged.
+
+The default view limits decisions. In `--view decision-tables`, the units are
+decision tables; in `--view conditions`, condition and alternative rows; and
+in `--view tests`, test rows. Rows are ordered deterministically by project-
+relative path and source line, with deterministic tie-breakers for each view:
+decisions use column and stable ID; decision tables use decision ID; conditions
+and alternatives use column, decision ID, and condition or alternative index;
+tests use test name and ID. `--top` follows that source order; it does not rank
+rows by risk or coverage. For example:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --focus lib/access.rb:12 --top 5
+bundle exec branchproof report .branchproof/current.json --view conditions \
+  --focus lib/access.rb --top 10
+```
+
+Focus and top selections never create a new test run or alter policy scope.
+They also do not generate tests. RSpec rerun labels remain the existing
+recorded selectors and commands. The main finding rows respect the selection;
+supplemental unexecuted, unattributed, and unsupported sections retain their
+run-wide counts rather than expanding into all detail rows.
+
 ### Saved reports and offline comparison
 
 Reports are saved only when requested. Create a local artifact directory and
@@ -466,13 +621,26 @@ The output's parent directory must already exist. Replacing a baseline is an
 explicit `analyze --format json --output` operation; keep CI snapshots as
 artifacts when you need to retain multiple runs.
 
-The `report` command reads the saved document without loading the application
-or running tests. It uses locations and metadata captured in the report, so
-rendering remains useful after the original checkout has moved or been
-removed. New snapshots retain the ladder at every level. Legacy snapshots
-without analysis can still be rendered at Level 1; levels 2 and 3 require
-analysis in the saved report. The repository ignores `.branchproof/`; choose a
-different path and CI artifact policy when a project needs to retain reports.
+The `report` command reads the saved document without loading the application,
+project configuration, or running tests. It uses locations and metadata
+captured in the report, so rendering remains useful after the original
+checkout has moved or been removed. A saved report's policy is inherited by
+default. Repeatable `--minimum criterion=threshold` options override matching
+saved policy entries for that rendering without changing the snapshot file;
+other saved thresholds remain inherited. Offline rendering never consults the
+current `.branchproof.json`.
+
+New live JSON reports use schema `1.4` and include the required
+`coverage_policy` object with the normalized requested minima and recomputed
+gate results. The report validates those results from its exact coverage
+counts rather than trusting a persisted percentage. Readers continue to accept
+schemas `1.0` through `1.3`; an offline policy overlay is optional and
+preserves the input snapshot's schema version, including for legacy reports.
+New snapshots retain the ladder at every level. Legacy snapshots without
+analysis can still be rendered at Level 1; levels 2 and 3 require analysis in
+the saved report.
+The repository ignores `.branchproof/`; choose a different path and CI artifact
+policy when a project needs to retain reports.
 Saved JSON includes existing raw metadata such as test names and expressions;
 relative terminal labels do not mean every legacy JSON field is sanitized.
 
@@ -508,6 +676,29 @@ Invalid input or an incomplete comparison exits 2, which takes
 precedence. Reports are explicit snapshots: comparison never creates history,
 promotes a baseline, or overwrites either input.
 
+### GitHub Actions artifacts
+
+A coverage policy can fail a job while still preserving the report for review.
+Create the output directory before invoking Branchproof and upload the report
+with `if: always()` so failed gates and failed test runs leave an artifact:
+
+```yaml
+- name: Branchproof coverage
+  run: |
+    mkdir -p .branchproof
+    bundle exec branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
+      --format json --output .branchproof/coverage.json \
+      --minimum mcdc=80 --minimum decision_table=75
+
+- name: Upload Branchproof report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: branchproof-coverage
+    path: .branchproof/coverage.json
+    if-no-files-found: warn
+```
+
 MC/DC has two related questions. Evaluation asks whether a condition was
 observed with a value, including short-circuiting. Independent proof asks
 whether the analyzer found a pair of observations where that condition changes
@@ -618,8 +809,8 @@ Ruby-defined custom `!` methods keep their runtime behavior;
 evidence that contradicts Boolean negation is rejected instead of proving
 coverage with an invalid logical model.
 
-New reports use schema `1.3`; saved schema `1.0`, `1.1`, and `1.2` reports
-remain readable. Comparison distinguishes decision-table coverage movement
+New reports use schema `1.4`; saved schema `1.0`, `1.1`, `1.2`, and `1.3`
+reports remain readable. Comparison distinguishes decision-table coverage movement
 (`rule coverage gained`, `rule coverage lost`) from analysis movement
 (`rule reachability changed`), and treats a structurally changed decision as a
 changed decision-table context instead of guessing which old rule a new rule
@@ -654,12 +845,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
 
@@ -672,10 +865,15 @@ 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.
+for adapters and integrations. `Branchproof::CoveragePolicy#call` evaluates a
+normalized `minimum` hash against a report document. `Report#coverage_policy`
+returns the recomputed policy record, and `Report#coverage_policy_lines`
+returns its terminal lines; both are available to integrations that need the
+same gate result as the CLI.
 
 ## Development
 
@@ -705,6 +903,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).