branchproof 0.11.1 → 0.12.0

data/README.md

@@ -4,8 +4,8 @@ Branchproof measures decision, condition, modified condition/decision (MC/DC),
 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
-coverage.
+alternatives, safe navigation, conditional assignments, and value fallback
+chains such as `name || "untitled"` receive alternative coverage.
 
 The gem and primary command are named `branchproof`. The `mcdc` command and
 `MCDC` namespace remain compatibility aliases with the same behavior.
@@ -22,16 +22,77 @@ Or add it to a bundle:
 bundle add branchproof
 ```
 
-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.
+Branchproof requires CRuby 4.0 or newer and Prism 1.x at runtime.
+CI tests CRuby 4.0, including Rails 8.1.x and rspec-rails 8.x integrations.
+Newer Ruby versions are allowed by the gem requirement but are not yet tested in CI.
+The application supplies the test framework selected for analysis: Minitest
+`>= 5.25.5, < 7` or RSpec 3.13. Branchproof does not install either framework;
+projects that use both can keep both in their test bundle.
 Unsupported syntax and incomplete observations remain visible in the report
 instead of being counted as coverage.
 
+For a Minitest application, keep the runner in the application bundle:
+
+```ruby
+gem "branchproof"
+gem "minitest", ">= 5.25.5", "< 7"
+```
+
+For an RSpec application, use its existing RSpec bundle:
+
+```ruby
+gem "branchproof"
+gem "rspec", "~> 3.13.0", require: false
+```
+
+`branchproof report`, `branchproof compare`, and `branchproof collate` read saved
+JSON without loading either test framework, so reports can be used in a
+minimal deployment or offline environment.
+
+## Check a project's setup
+
+Run `branchproof doctor` from the project root to check static setup facts before
+starting an analysis:
+
+```sh
+bundle exec branchproof doctor 'lib/**/*.rb' \
+  --test 'test/**/*_test.rb' \
+  --project ruby --framework minitest
+```
+
+Doctor accepts source globs followed by `--test GLOB`, `--project
+auto|ruby|rails`, `--framework auto|minitest|rspec`, `--config PATH` or
+`--no-config`, and `--format terminal|json`. It uses the same project detection,
+configuration precedence, framework selection, test discovery, and source
+safety exclusions as `analyze`. Command-line selections override matching
+`.branchproof.json` values. Default discovery excludes helper, support, and
+fixture test files; an explicit `--test` glob selects those files when requested.
+`--help` prints usage without inspecting the project.
+
+Doctor exits 0 when its static checks pass, including warning-only results, and
+2 when setup is blocked or the command is invalid. JSON is one document with
+`schema_version: 1`, `command: "doctor"`, a `ready` or `blocked` status,
+`runtime`, resolved `project` and `configuration`, `selection`, selected
+`framework` metadata, `checks`, and `limitations`. Each check has a stable code,
+`pass`, `warning`, or `error` status, and a message. Add `--format json` to get
+this document on both successful and blocked checks, including configuration
+and argument errors.
+
+Framework availability comes from RubyGems metadata. An `activated` version is
+already in the current process; a `discoverable` version is visible in the
+current RubyGems environment but has not been activated. Doctor checks only the
+selected framework, using Minitest `>= 5.25.5, < 7` or `rspec-core ~> 3.13.0`.
+Discoverable metadata does not prove that a framework can load successfully.
+
+Doctor is a static readiness check. It does not load source, helpers, tests,
+framework code, or Rails; run a test runner; or inspect Ruby syntax. A ready
+result does not verify Rails boot, actual framework test discovery, runner
+compatibility, instrumentation, coverage, or whether a selected file contains
+executable tests. It warns about Spring or Bootsnap only when already visible in
+loaded features. Configured coverage minima are shown but not evaluated. As with
+other Branchproof commands, Branchproof itself must load successfully, including
+its supported Ruby runtime and core dependencies.
+
 ## Analyze a test run
 
 Run `branchproof analyze` with the source files or globs to inspect, followed by
@@ -90,7 +151,7 @@ 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
+rspec-rails 8.x on CRuby 4.0. 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.
 
@@ -158,6 +219,11 @@ 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 separate policy on changed decisions, use `--changed-since REF` with
+repeatable `--minimum-changed criterion=threshold` options. The configuration
+equivalent is `"minimum_changed": { "mcdc": 80 }`; CLI values override matching
+entries. See [Changed-decision coverage and gates](#changed-decision-coverage-and-gates).
+
 For a Minitest project, a focused configuration can select the library and
 test trees directly:
 
@@ -186,8 +252,9 @@ is unchanged. The Rails metadata in the report identifies the selected
 project and Rails version.
 
 `--output` writes the report through an atomic replacement. Without it, the
-report is written to standard output. `--format` accepts `terminal` (the
-default) or `json`. JSON includes source identities, criterion and schema
+report is written to standard output. `analyze` accepts `terminal` (the
+default), `json`, and `github`; `compare` accepts `terminal` and `json`.
+`report` also accepts `html` for a portable offline page. JSON includes source identities, criterion and schema
 versions, baseline status, diagnostics, completeness, observations, and
 analysis fields.
 
@@ -486,7 +553,7 @@ Decision tables fully covered: 13/18 decisions
 
 ### Find missing cases
 
-Use `--missing-only` to focus the terminal report on conditions that still
+Use `--missing-only` to focus terminal and HTML reports on conditions that still
 lack independence evidence:
 
 ```sh
@@ -511,11 +578,15 @@ making the decision false. The missing condition is presented as:
 
 ```text
   Condition 1: Instruction.installed?(content)
-    NOT_PROVEN — missing observation
-      Need an observation where:
-        content is truthy
-        Instruction.installed?(content) is falsey
-        Expected decision: false [TF]
+    NOT_PROVEN — Missing evidence for: Instruction.installed?(content)
+      Observed decision expression: content && Instruction.installed?(content)
+      Find two executions where:
+        Instruction.installed?(content) changes between true and false
+        content remains true
+        decision outcome changes between true and false
+      Observed: content = true; Instruction.installed?(content) = true; decision = true
+      Missing counterpart: content = true; Instruction.installed?(content) = false; decision = false (candidate; not observed)
+      Boolean requirement; application-level feasibility unknown
 ```
 
 An existing file without the instruction block
@@ -524,6 +595,13 @@ describes required truth values, not application inputs or guaranteed
 reachable paths. In Ruby, only `false` and `nil` are falsey; an empty string
 is truthy.
 
+This wording is generated from recorded expressions and analyzer candidates.
+Boolean values describe truthiness, not the original Ruby objects. Short-circuited
+conditions are marked as not evaluated. Unary negation remains in the full
+decision expression: for `user.paid? && !user.suspended?`, the atomic condition is
+`user.suspended?`, so its observed value is `false` and the missing counterpart
+requires `true`. No domain wording or application inputs are inferred.
+
 `NOT_PROVEN` means analysis ran but did not find the required pair of
 observations. `NOT CALCULATED` means analysis was not available or was not
 requested; check the test status and diagnostics before adding tests.
@@ -576,9 +654,9 @@ 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
+Terminal and HTML 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
+`analyze` and `report`; for HTML they apply only to offline `report`. 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.
@@ -590,7 +668,8 @@ 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:
+rows by risk or coverage. Only `--view summary` ranks rows (see
+[Summary view](#summary-view-where-to-start)). For example:
 
 ```sh
 bundle exec branchproof analyze 'lib/**/*.rb' --focus lib/access.rb:12 --top 5
@@ -604,6 +683,77 @@ 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.
 
+### Summary view: where to start
+
+Use `--view summary` to see the largest gaps first. It is accepted by
+`analyze` and `report` and is terminal-only.
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --view summary --top 10
+bundle exec branchproof report .branchproof/current.json --view summary
+```
+
+The view has two ranked lists:
+
+* **Files**: one row per source file, with counts and explicit denominators.
+* **Where to start**: one row per supported decision that still has a gap,
+  with its location, the missing cases, and the tests that already reach it.
+
+Both lists use the same deterministic order:
+
+1. Unexecuted decisions (or files with more of them) come first.
+2. Then more missing obligations: decision-table rules, unproven MC/DC
+   conditions, and missing alternatives.
+3. Ties break by project-relative path, line, column, and decision ID.
+
+The order counts missing obligations. It is not a risk estimate.
+
+```text
+Files:
+  1. lib/access.rb: 3/3 decisions with gaps; 1 unexecuted; DT 8/11 rules missing; MC/DC 7/8 conditions unproven
+  2. lib/pricing.rb: 2/2 decisions with gaps; DT 2/3 rules missing; MC/DC 2/2 conditions unproven; 2/3 alternatives missing
+
+Where to start:
+  1. lib/access.rb:15  a && (b || c)
+     unexecuted; DT 4/4 rules missing; MC/DC 3/3 conditions unproven
+     Cases to test: 4
+     R1 [F--]: a falsey; expected decision false
+     R2 [TT-]: a truthy, b truthy; expected decision true
+     R3 [TFT]: a truthy, b falsey, c truthy; expected decision true
+     R4 [TFF]: a truthy, b falsey, c falsey; expected decision false
+     Tests reaching this decision: none recorded
+
+  2. lib/access.rb:7  user.owner?(doc) || (user.editor? && !doc.locked?)
+     DT 3/4 rules missing; MC/DC 3/3 conditions unproven
+     Cases to test: 3
+     ...
+     Tests reaching this decision:
+       AccessTest#test_owner (test/access_test.rb:19)
+```
+
+`Cases to test` counts the new observations the decision needs. When the
+decision table was calculated, each missing rule is one case, and one
+observation can cover at most one rule. When the table was not calculated,
+or no rule is missing but a condition is still unproven (for example, when
+its pair needs a statically impossible rule), the view lists the unproven
+conditions instead. For decisions with
+alternative coverage, such as `case`/`when` or `case`/`in`, it lists the
+missing alternatives. A case describes truth values, not application inputs.
+
+The level controls detail per row:
+
+* Level 1 shows ranked rows and counts only.
+* Level 2 adds the missing cases.
+* Level 3 (the default) also names up to three tests that already reach the
+  decision, with RSpec rerun commands when recorded. These tests are good
+  places to add the new case.
+
+`--top N` keeps the first `N` rows of each list and reports how many were
+hidden. `--focus PATH[:LINE]` ranks only the matching decisions.
+`--missing-only` hides fully covered files. Unsupported decisions are counted
+but not ranked. As with the other views, the coverage ladder, policy gates,
+diagnostics, and exit status are always global.
+
 ### Saved reports and offline comparison
 
 Reports are saved only when requested. Create a local artifact directory and
@@ -615,6 +765,8 @@ bundle exec branchproof analyze 'lib/**/*.rb' --format json \
   --output .branchproof/baseline.json
 bundle exec branchproof report .branchproof/baseline.json --view conditions
 bundle exec branchproof report .branchproof/baseline.json --view tests
+bundle exec branchproof report .branchproof/baseline.json --format html \
+  --output .branchproof/coverage.html
 ```
 
 The output's parent directory must already exist. Replacing a baseline is an
@@ -630,12 +782,28 @@ saved policy entries for that rendering without changing the snapshot file;
 other saved thresholds remain inherited. Offline rendering never consults the
 current `.branchproof.json`.
 
+HTML is a single self-contained document with inline CSS, no JavaScript, external
+assets, source reads, or network requests. It can be written to a file with
+`--output` or streamed to stdout. The page keeps whole-run coverage and policy
+global even when `--focus`, `--top`, or `--missing-only` filters displayed
+decisions. Its status and exit code still reflect the saved run and its policy.
+HTML is available from `report` and `collate`; `analyze` and `compare` reject it. The
+integrated HTML layout does not accept `--view`. At level 1 it shows the summary
+and decision inventory; level 2 adds missing scenarios; level 3 also adds
+contributing tests. Legacy snapshots without analysis support only level 1,
+and HTML reports failed or incomplete runs with their existing exit status.
+
 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.
+counts rather than trusting a persisted percentage. Reports created with
+`--changed-since` use schema `1.5` and add the captured changed scope and its
+informational coverage. A changed policy adds `changed_coverage_policy` and uses
+schema `1.6`. Collated reports use schema `1.7` and record their contributing
+shards and collection completeness. Readers accept schemas `1.0` through `1.7`.
+A whole-run policy overlay preserves the input schema; adding a changed policy to a `1.5` snapshot
+upgrades the output to `1.6` without changing the input file.
+Policy overlays on collated reports preserve schema `1.7` and its provenance.
 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.
@@ -644,6 +812,119 @@ 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.
 
+### Combine serial test shards
+
+When CI splits tests into separate jobs, save a JSON report from each serial
+run and combine their observations offline:
+
+```sh
+bundle exec branchproof collate unit.json integration.json \
+  --manifest shards.json --output combined.json
+bundle exec branchproof report combined.json --format html --output coverage.html
+```
+
+Collation recalculates coverage, supporting sets, missing evidence, and gates.
+For example, a true decision in one shard and a matching false decision in
+another can together prove a condition's effect. Shard coverage percentages
+are never averaged. No application code or tests run during collation, and the
+original checkout does not need to exist.
+
+Declare the expected artifacts in `shards.json`:
+
+```json
+{
+  "shards": [
+    { "id": "unit", "report": "unit.json" },
+    { "id": "integration", "report": "integration.json" }
+  ]
+}
+```
+
+Manifest paths are relative to the manifest file. Pass the artifacts actually
+received as command arguments; omitted entries stay missing even if their
+files happen to exist. Unknown inputs and duplicate manifest IDs or paths are
+rejected. One artifact cannot satisfy two different shard IDs.
+
+The manifest is optional. Without it, collation displays the supplied evidence
+but marks collection completeness unknown and exits **2**. Missing declared
+shards also produce an incomplete report and exit 2. A complete manifest proves
+only that every declared artifact arrived; it does not prove those artifacts
+selected every test in the application. Failed or incomplete input runs cannot
+become a passing collection.
+
+Inputs must be raw schema `1.4`–`1.6` reports from the current Branchproof and
+Ruby runtime, with matching report schema, source inventory/digests, framework,
+limits, reachability settings, analysis level, and coverage thresholds. Captured
+changed scope and changed thresholds must also match. Different test selections,
+seeds, and checkout roots are allowed; per-shard metadata and relative test
+locations are retained. Missing reconstruction metadata is an error. Collated
+reports cannot themselves be collated in this first version.
+
+An identical report supplied twice is counted once. Conflicting or partially
+overlapping run IDs are rejected. A test executed in different runs contributes
+each execution to baseline counts and phase counts, while retaining its existing
+test identity; any failure takes precedence over a later pass.
+
+Collate defaults to JSON and supports `--format terminal|json|github|html`.
+Use `report` for views, display filters, or threshold overrides on the saved
+result. Output is written atomically and cannot replace input reports, declared
+artifacts, or the manifest. Combined evidence exceeding storage limits is
+rejected; bounded analysis that cannot finish remains incomplete. Schema `1.7`
+requires an updated reader. Collation does not enable threaded or forked runners.
+
+### Changed-decision coverage and gates
+
+The analyze-only `--changed-since REF` option resolves `REF` to a commit and compares that
+commit directly with the current tracked worktree, including staged and
+unstaged edits. It does not infer a merge base. Untracked files are excluded.
+The option adds informational coverage for current decisions mapped to changed
+source lines; it does not select or skip tests. Additions and renames include
+all current decisions in their files, deletions have no current decision
+obligation, and comment or spacing changes with no semantic decision change
+produce an empty scope. Invalid refs, non-Git projects, and observed source or
+Git drift fail with usage status 2 before tests start. Capture checks for drift
+but does not lock the checkout atomically.
+
+The full inventory, analysis, run metrics, and `--minimum` gates remain
+whole-run. A whole-run minimum can fail even when changed coverage is complete.
+Add `--minimum-changed` to enforce an independent changed-decision threshold:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --changed-since main \
+  --minimum-changed mcdc=80
+```
+
+The changed gate uses exact counts for the captured changed decisions and the
+same five criteria as `--minimum`. For example, 1 of 2 conditions proven means
+50% MC/DC: an 80% gate fails even when every test passes. Add the missing
+independence evidence and 2 of 2 conditions passes. Both policies must pass when
+both are configured. A changed minimum requires `--changed-since` during
+analysis; missing scope is rejected before tests run.
+
+A valid empty changed scope is `not_applicable`, with no coverage percentage.
+It does not fail the run or waive failed tests, incomplete evidence, or whole-run
+gates. A nonempty scope with only unsupported decisions, or a requested criterion
+with no applicable denominator, is unavailable. As with whole-run gates, a failed
+test run makes a requested changed gate unavailable. Below-threshold gates exit
+1; unavailable gates exit 2.
+
+Terminal focus and top filters intersect the changed decision IDs for display;
+they do not change either coverage denominator. JSON accepts the scope option,
+while its existing focus and top restrictions remain. Saved reports retain the
+captured scope for offline rendering without Git access. Their validation
+checks the scope's internal consistency, not the historical Git diff or
+cross-revision coverage.
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --changed-since main
+bundle exec branchproof report .branchproof/current.json --minimum-changed mcdc=80
+```
+
+Offline reports inherit saved changed thresholds and allow matching overrides.
+They use the captured scope without consulting Git or project configuration.
+Terminal, GitHub, and HTML output show changed gate results separately from
+whole-run gates.
+
 To compare two explicitly saved runs:
 
 ```sh
@@ -699,6 +980,71 @@ with `if: always()` so failed gates and failed test runs leave an artifact:
     if-no-files-found: warn
 ```
 
+To attach a portable HTML report as well, render it from the saved JSON and
+upload both files. The report step is offline and does not run tests again:
+
+```yaml
+- name: Render Branchproof HTML
+  if: always() && hashFiles('.branchproof/coverage.json') != ''
+  run: >-
+    bundle exec branchproof report .branchproof/coverage.json --format html
+    --output .branchproof/coverage.html
+
+- name: Upload Branchproof reports
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: branchproof-coverage
+    path: .branchproof/coverage.*
+    if-no-files-found: warn
+```
+
+### GitHub Actions annotations and job summary
+
+`--format github` prints GitHub Actions workflow commands instead of the
+terminal report. `analyze` and `report` accept it; `compare` does not.
+
+* One `::warning` per decision with a gap, in [summary view](#summary-view-where-to-start)
+  order, placed on the decision's file and line. At level 2 or 3 the message
+  lists the cases to test.
+* An `::error` if the test run did not pass or is incomplete, and one per
+  policy gate that did not pass (failed or unavailable, with its reason).
+  Every non-zero exit status has at least one error.
+* A final `::notice` with the coverage ladder and the number of decisions with
+  gaps.
+
+When `GITHUB_STEP_SUMMARY` is set, as it is inside Actions, Branchproof also
+appends a Markdown summary to that file: the ladder, the policy gates, and a
+ranked "Where to start" table. The table shows `--top N` rows, or 20 rows
+when `--top` is not given.
+
+Render both from the saved report, so the tests run only once:
+
+```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: Branchproof annotations
+  if: always() && hashFiles('.branchproof/coverage.json') != ''
+  run: bundle exec branchproof report .branchproof/coverage.json --format github --top 10
+```
+
+GitHub shows a limited number of annotations per step (currently 10
+warnings), so `--top 10` keeps the output to the ones that are displayed.
+Annotation paths must be relative to the repository. When the project is in
+a subdirectory (a step with `working-directory: gems/tool`), Branchproof
+prefixes each path with the current directory's location inside
+`GITHUB_WORKSPACE`. Run `report` from the same directory as `analyze`.
+
+`--focus` also applies. `--view` and `--missing-only` are rejected because
+the output always uses the summary ranking of gaps. The exit status is the
+same as for the terminal format, so the report step inherits the saved
+policy and fails with the same gates.
+
 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
@@ -809,8 +1155,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.4`; saved schema `1.0`, `1.1`, `1.2`, and `1.3`
-reports remain readable. Comparison distinguishes decision-table coverage movement
+New live reports use schema `1.4`; `--changed-since` reports use schema `1.5`.
+Saved schema `1.0` through `1.5` 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
@@ -845,6 +1191,17 @@ the serial Minitest runner. This is useful for seeds and name filters:
 branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
+Minitest 5 and 6 both accept `-n`/`--name`. Minitest 6 also accepts
+`-i`/`--include`. Minitest 6 plugins must be loaded explicitly by the application;
+Branchproof preserves the framework's plugin-loading behavior. Bisect and server
+modes are unsupported because they do not execute one serial local test run.
+
+Plain Ruby compatibility is tested with Minitest 5.26.2, 5.27.0, 6.0.0, and
+6.0.6. Rails integration continues to be tested with Minitest 5; Minitest 6
+support does not extend the verified Rails compatibility matrix.
+Minitest's own Ruby requirements also apply: Minitest 5.25.5 excludes Ruby 4,
+so it cannot be selected in Branchproof's Ruby 4 bundle.
+
 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
@@ -854,6 +1211,54 @@ Rails system/browser tests, custom Rails test commands, generated tests, and
 reloading configurations are explicitly unsupported and produce diagnostics
 rather than a passing analysis.
 
+### Rake task
+
+`require "branchproof/rake_task"` in a Rakefile defines a task that runs
+`branchproof analyze` in a subprocess. The gem does not depend on Rake at
+runtime, so the file is not loaded by `require "branchproof"`. Only options
+set in the Rakefile are passed to the CLI; everything else keeps the CLI and
+`.branchproof.json` defaults.
+
+A Minitest project:
+
+```ruby
+require "branchproof/rake_task"
+
+Branchproof::RakeTask.new(:branchproof) do |t|
+  t.sources = ["lib/**/*.rb"]
+  t.tests = ["test/**/*_test.rb"]
+end
+```
+
+An RSpec project in a Rails application:
+
+```ruby
+Branchproof::RakeTask.new(:branchproof) do |t|
+  t.sources = ["app/**/*.rb"]
+  t.project = "rails"
+  t.framework = "rspec"
+  t.runner_args = ["--seed", "1234"]
+end
+```
+
+Then run `bundle exec rake branchproof`. The task accepts `sources`, `tests`,
+`project`, `framework`, `view`, `level`, `missing_only`, `minimum`, `format`,
+`output`, `runner_args`, and `description`. `RakeTask#argv` returns the CLI
+arguments the task will pass, which is useful for checking a Rakefile without
+running the analysis.
+
+In CI, the task exits with the CLI status, so a failed test run, a coverage
+gate failure, or a usage error fails the job:
+
+```ruby
+Branchproof::RakeTask.new(:branchproof) do |t|
+  t.sources = ["lib/**/*.rb"]
+  t.format = "json"
+  t.output = ".branchproof/coverage.json"
+  t.minimum = ["mcdc=80", "decision_table=75"]
+end
+```
+
 ## Library entry points
 
 ```ruby
@@ -899,9 +1304,15 @@ the core suite does not require Rails. Bootsnap is disabled for the child
 Rails process so its compilation cache cannot own the load path during an
 analysis.
 
-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.
+Run the commands with CRuby 4.0 or newer and the declared Prism 1.x dependency.
+The default development bundle keeps Minitest 5 for the full suite. CI runs eight
+jobs on CRuby 4.0: the core suite, Minitest 5.26.2/6.0.0/6.0.6 consumer
+compatibility, RSpec Core 3.13.0/3.13.6 compatibility, Rails 8.1 integration, and
+rspec-rails integration. The Minitest compatibility jobs select an exact version
+with `BRANCHPROOF_MINITEST_VERSION` and run adapter, CLI, lifecycle, doctor,
+collation, and packaged-consumer checks. They do not require the mock library removed from
+Minitest 6.
+Lint runs once in the core job. Pull requests and pushes to main trigger CI.
 
 The repeatable native-versus-instrumented adapter benchmark and its captured
 Ruby 3.4.7 result are in

data/doc/Branchproof/CLI.md

@@ -15,5 +15,5 @@ Not documented.
 ### `call(argv)` <a id="method-i-call"></a> <a id="call-instance_method"></a>
 Not documented.
 
-### `initialize(stdout:, stderr:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+### `initialize(stdout:, stderr:, env: = ENV)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
 - **@return** [CLI] a new instance of CLI

data/doc/Branchproof/ChangedCoverage.md

@@ -0,0 +1,19 @@
+# Module Branchproof::ChangedCoverage <a id="module-Branchproof-ChangedCoverage"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/changed_coverage.rb |
+
+Computes informational coverage for the current decisions captured by a
+changed scope.
+
+## Constants
+### `COMPLETENESS_FIELDS` <a id="constant-COMPLETENESS_FIELDS"></a> <a id="COMPLETENESS_FIELDS-constant"></a>
+Not documented.
+
+### `CRITERIA` <a id="constant-CRITERIA"></a> <a id="CRITERIA-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `call(document:, scope:)` <a id="method-c-call"></a> <a id="call-class_method"></a>
+Not documented.

data/doc/Branchproof/ChangedCoveragePolicy.md

@@ -0,0 +1,24 @@
+# Class Branchproof::ChangedCoveragePolicy <a id="class-Branchproof-ChangedCoveragePolicy"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/coverage_policy.rb |
+
+Evaluates gates against the captured changed-scope summary independently from
+whole-run coverage policy.
+
+## Constants
+### `COMPLETENESS_FIELDS` <a id="constant-COMPLETENESS_FIELDS"></a> <a id="COMPLETENESS_FIELDS-constant"></a>
+Not documented.
+
+### `CRITERIA` <a id="constant-CRITERIA"></a> <a id="CRITERIA-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `call(document:, scope:)` <a id="method-i-call"></a> <a id="call-instance_method"></a>
+Not documented.
+
+### `initialize(minimum_changed:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [ChangedCoveragePolicy] a new instance of ChangedCoveragePolicy