branchproof 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54d2cbd08336e8e70fa291f82e821043d06572485a57c0aa500656b29500688f
-  data.tar.gz: 805857b4b676e3d3cef1627890a2ab62fb7e7cda404b43907e9b2b1db2bbedca
+  metadata.gz: c5b31682254d1c9db4be1d61e11743be038c65f859c730be05d1acae138e673c
+  data.tar.gz: 59a6f30a1586c0783283f32e16d1ed5626f702f3ec152ec15dfe271cfbc0c0b1
 SHA512:
-  metadata.gz: 44aed1ac067e6d1f0d2a5858b1b3ba14f102805f0b16c3b63cfdb9a605fb2df26bc113a1d70c53236ce1023aa991b05ae1c600439b89cb35297134883a0b5b86
-  data.tar.gz: d003e7b90e2413d20b788f9717f6df5512611bfbd4e3b1e8a0695b55bc9d62fbbbb3c10097905653f03119c2eb30a47d098051e5e0579a58ef51c0ce5b9dbcba
+  metadata.gz: 061d18741787eaeb57f5f1ec90a5e68d658fa8d9344fee52ecfa54fd70a69fcc909affe4890785031403a46379c90e11ac8a63c01766bd8477e2d7963ca14172
+  data.tar.gz: 144e5b02c3a380133015402e9ad2b47b52bc3a4d624c2f13728015159cd7ec6287fe7b3d1f167fb2ce745b3d953d5f271628a740c0912ae36af3fa7f72e13fb9

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-10
+
+- Show source filenames beside diagnostics in decision, condition, and test
+  views, including reports rendered from saved JSON.
+- Explain when a selected file has no supported conditions to instrument and
+  include unsupported syntax reasons when its decisions cannot be instrumented.
+
+## [0.4.0] - 2026-09-10
+
+- Added `branchproof` as the primary CLI command while retaining `mcdc` as a
+  compatibility alias.
+- Added condition-focused and test-focused terminal views, including relative
+  source locations, evaluated and short-circuited observations, and analyzer
+  witness ownership.
+- Added opt-in saved JSON reports, offline rendering, and exact-condition
+  comparisons with gained/lost proof and changed-source context.
+- Added `--fail-on-regression` comparison status handling and documented the
+  local `.branchproof/` artifact directory and explicit baseline workflow.
+
 ## [0.3.0] - 2026-09-10
 
 - Add `--missing-only` to focus terminal reports on unproven conditions.

data/README.md

@@ -6,8 +6,8 @@ modifier, and ordinary ternary (`?:`) decisions, records observed vectors,
 and reports independence evidence, missing counterpart constraints, and
 smaller supporting test sets.
 
-The gem is named `branchproof`; its command and compatibility namespace are
-`mcdc` and `MCDC`.
+The gem and primary command are named `branchproof`. The `mcdc` command and
+`MCDC` namespace remain compatibility aliases with the same behavior.
 
 ## Installation
 
@@ -30,12 +30,12 @@ instead of being counted as coverage.
 
 ## Analyze a test run
 
-Run `mcdc analyze` with the source files or globs to inspect, followed by
+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:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
+branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
   --level 3 \
   --format terminal \
   --output tmp/branchproof.txt \
@@ -47,14 +47,14 @@ For a plain Ruby application, select the project policy explicitly when
 running from the application root:
 
 ```sh
-bundle exec mcdc analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
 ```
 
 For a Rails application, run the same command from the application root so
 the application's bundle and Rails version remain in effect:
 
 ```sh
-bundle exec mcdc analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
 ```
 
 For a project rooted at the current directory, `--project auto` is the
@@ -97,7 +97,7 @@ For example, running the contents of the small `decision.rb` /
 with the terminal format produces a summary like this:
 
 ```text
-Branchproof 0.3.0
+Branchproof 0.5.0
 Tests: PASSED (3 tests, 0 failed, 0 skipped)
 MC/DC: 100.0% (2/2 conditions proven)
 Analysis: COMPLETE
@@ -132,7 +132,7 @@ Use `--missing-only` to focus the terminal report on conditions that still
 lack independence evidence:
 
 ```sh
-bundle exec mcdc analyze 'lib/**/*.rb' --missing-only
+bundle exec branchproof analyze 'lib/**/*.rb' --missing-only
 ```
 
 This keeps the overall summary and diagnostics, hides proven conditions and
@@ -185,6 +185,95 @@ test suite. A failed, unsupported, or incomplete run is reported with its
 status and diagnostics and cannot become a successful coverage result by
 changing the display level.
 
+### Focused condition and test views
+
+Use `--view conditions` to group the report by condition. Each condition shows
+its expression, decision, and project-relative source location with the
+condition's own 1-based start line. The view separates tests that evaluated
+the condition true or false from tests where it was short-circuited. Level 3
+also shows the canonical witness observations selected by the analyzer and
+their owning tests.
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions --missing-only
+```
+
+Use `--view tests` to group the same evidence by test. Rows include each
+exercised condition, its relative source location, observed values, and the
+recorded `setup`, `body`, or `teardown` phases. Tests with no completed
+condition observation remain visible, as do unattributed and unexecuted
+conditions. A test that evaluates both Boolean values is evidence of execution;
+it is a proof contributor only when the analyzer's independent witness pair
+uses its observations.
+
+`--view` changes terminal grouping and does not change instrumentation or test
+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.
+
+### Saved reports and offline comparison
+
+Reports are saved only when requested. Create a local artifact directory and
+write a complete JSON baseline with the existing atomic `--output` option:
+
+```sh
+mkdir -p .branchproof
+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
+```
+
+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. Level 1 reports observations; levels 2 and 3 require corresponding
+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.
+
+To compare two explicitly saved runs:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --format json \
+  --output .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json --fail-on-regression
+```
+
+Comparison matches exact condition identities from unchanged source files.
+Changed source files, changed selection or runtime context, incomplete runs,
+and legacy reports missing comparison metadata are reported as partial or
+incomplete context rather than guessed regressions. The output distinguishes
+gained proof, lost proof, changed sources, newly selected files, and files no
+longer present in a report. Previous witness values and owner names are shown
+for lost proof; an absent owner is described as `not observed in current run`,
+not as a deleted test. A different test population under unchanged discovery
+patterns is valid comparison context, and seed differences are disclosed.
+
+`compare` exits 0 for a complete comparison, including one with coverage
+changes; `--fail-on-regression` exits 1 when a complete comparable run loses
+proof. 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.
+
+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
+the decision outcome under the masking criterion. Other conditions may be
+short-circuited or masked rather than fixed to the same observed values. For example,
+`left && right` observed as `[TT]` and `[F-]` evaluates `right` once and
+short-circuits it once, but does not prove `right`; `[TF]` is also required.
+The condition and test views preserve that distinction.
+
 ### Supported conditional forms
 
 Ordinary Ruby ternaries use the same predicate instrumentation and `&&`/`||`
@@ -230,7 +319,7 @@ Everything after the argument separator is passed as individual arguments to
 the serial Minitest runner. This is useful for seeds and name filters:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
+branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
 The 0.2 release supports serial Minitest execution in plain Ruby projects and

data/doc/Branchproof/Comparison.md

@@ -0,0 +1,26 @@
+# Class Branchproof::Comparison <a id="class-Branchproof-Comparison"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/comparison.rb |
+
+Compares two complete report documents without loading or executing the
+project.
+
+## Constants
+### `CRITERION_VERSION` <a id="constant-CRITERION_VERSION"></a> <a id="CRITERION_VERSION-constant"></a>
+Not documented.
+
+### `SCHEMA_VERSION` <a id="constant-SCHEMA_VERSION"></a> <a id="SCHEMA_VERSION-constant"></a>
+Not documented.
+
+### `SUPPORTED_REPORT_SCHEMAS` <a id="constant-SUPPORTED_REPORT_SCHEMAS"></a> <a id="SUPPORTED_REPORT_SCHEMAS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `call()` <a id="method-i-call"></a> <a id="call-instance_method"></a>
+Not documented.
+
+### `initialize(before:, after:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Comparison] a new instance of Comparison

data/doc/Branchproof/ComparisonReport.md

@@ -0,0 +1,19 @@
+# Class Branchproof::ComparisonReport <a id="class-Branchproof-ComparisonReport"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/comparison_report.rb |
+
+Renders the offline document returned by Comparison.
+
+## Public Instance Methods
+### `exit_code(fail_on_regression: = false)` <a id="method-i-exit_code"></a> <a id="exit_code-instance_method"></a>
+Not documented.
+
+### `initialize(document:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [ComparisonReport] a new instance of ComparisonReport
+
+### `write(io:, format:)` <a id="method-i-write"></a> <a id="write-instance_method"></a>
+- **@raise** [ArgumentError]

data/doc/Branchproof/CoverageIndex.md

@@ -0,0 +1,19 @@
+# Class Branchproof::CoverageIndex <a id="class-Branchproof-CoverageIndex"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/coverage_index.rb |
+
+Derives condition- and test-oriented rows from one report document.
+
+## Attributes
+### `conditions` [R] <a id="attribute-i-conditions"></a> <a id="conditions-instance_method"></a>
+Returns the value of attribute conditions.
+
+### `tests` [R] <a id="attribute-i-tests"></a> <a id="tests-instance_method"></a>
+Returns the value of attribute tests.
+
+## Public Instance Methods
+### `initialize(document:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [CoverageIndex] a new instance of CoverageIndex

data/doc/Branchproof/FocusedReport.md

@@ -0,0 +1,16 @@
+# Class Branchproof::FocusedReport <a id="class-Branchproof-FocusedReport"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/focused_report.rb |
+
+Terminal renderings grouped around conditions or tests.
+
+## Public Instance Methods
+### `initialize(document:, view:, level:, missing_only: = false)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [FocusedReport] a new instance of FocusedReport
+
+### `render()` <a id="method-i-render"></a> <a id="render-instance_method"></a>
+Not documented.

data/doc/Branchproof/Report.md

@@ -14,11 +14,21 @@ Not documented.
 ### `SCHEMA_VERSION` <a id="constant-SCHEMA_VERSION"></a> <a id="SCHEMA_VERSION-constant"></a>
 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>
+Not documented.
+
 ## Public Instance Methods
+### `condition_explanation(decision_id:, condition_id:)` <a id="method-i-condition_explanation"></a> <a id="condition_explanation-instance_method"></a>
+Shares the existing missing-case wording with focused terminal views.
+
+### `diagnostic_message(diagnostic)` <a id="method-i-diagnostic_message"></a> <a id="diagnostic_message-instance_method"></a>
+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)` <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)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
 - **@raise** [ArgumentError]
 - **@return** [Report] a new instance of Report
 

data/doc/Branchproof/SavedReport.md

@@ -0,0 +1,32 @@
+# Class Branchproof::SavedReport <a id="class-Branchproof-SavedReport"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/saved_report.rb |
+
+Reads and validates a persisted JSON report without loading the project.
+
+## Constants
+### `COMPLETENESS_FIELDS` <a id="constant-COMPLETENESS_FIELDS"></a> <a id="COMPLETENESS_FIELDS-constant"></a>
+Not documented.
+
+### `CRITERION_VERSION` <a id="constant-CRITERION_VERSION"></a> <a id="CRITERION_VERSION-constant"></a>
+Not documented.
+
+### `REQUIRED_FIELDS` <a id="constant-REQUIRED_FIELDS"></a> <a id="REQUIRED_FIELDS-constant"></a>
+Not documented.
+
+### `SUPPORTED_SCHEMAS` <a id="constant-SUPPORTED_SCHEMAS"></a> <a id="SUPPORTED_SCHEMAS-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `read(path)` <a id="method-c-read"></a> <a id="read-class_method"></a>
+Not documented.
+
+## Public Instance Methods
+### `initialize(document)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [SavedReport] a new instance of SavedReport
+
+### `validate!()` <a id="method-i-validate-21"></a> <a id="validate!-instance_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/instrumenter.rb, lib/branchproof/rails_support.rb, lib/branchproof/minitest_adapter.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/instrumenter.rb, lib/branchproof/saved_report.rb, lib/branchproof/rails_support.rb, lib/branchproof/coverage_index.rb, lib/branchproof/focused_report.rb, lib/branchproof/minitest_adapter.rb, lib/branchproof/comparison_report.rb |
 
 Public namespace for source inventory and one-run MC/DC reporting.
 
@@ -14,8 +14,12 @@ Not documented.
 
 - [Branchproof/Analyzer.md](Branchproof/Analyzer.md)
 - [Branchproof/CLI.md](Branchproof/CLI.md)
+- [Branchproof/Comparison.md](Branchproof/Comparison.md)
+- [Branchproof/ComparisonReport.md](Branchproof/ComparisonReport.md)
+- [Branchproof/CoverageIndex.md](Branchproof/CoverageIndex.md)
 - [Branchproof/Error.md](Branchproof/Error.md)
 - [Branchproof/Evidence.md](Branchproof/Evidence.md)
+- [Branchproof/FocusedReport.md](Branchproof/FocusedReport.md)
 - [Branchproof/Instrumenter.md](Branchproof/Instrumenter.md)
 - [Branchproof/Limits.md](Branchproof/Limits.md)
 - [Branchproof/Loader.md](Branchproof/Loader.md)
@@ -27,6 +31,7 @@ Not documented.
 - [Branchproof/Records.md](Branchproof/Records.md)
 - [Branchproof/Report.md](Branchproof/Report.md)
 - [Branchproof/Runtime.md](Branchproof/Runtime.md)
+- [Branchproof/SavedReport.md](Branchproof/SavedReport.md)
 - [Branchproof/Source.md](Branchproof/Source.md)
 - [Branchproof/Worker.md](Branchproof/Worker.md)
 - [CHANGELOG.md](CHANGELOG.md)

data/doc/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-10
+
+- Show source filenames beside diagnostics in decision, condition, and test
+  views, including reports rendered from saved JSON.
+- Explain when a selected file has no supported conditions to instrument and
+  include unsupported syntax reasons when its decisions cannot be instrumented.
+
+## [0.4.0] - 2026-09-10
+
+- Added `branchproof` as the primary CLI command while retaining `mcdc` as a
+  compatibility alias.
+- Added condition-focused and test-focused terminal views, including relative
+  source locations, evaluated and short-circuited observations, and analyzer
+  witness ownership.
+- Added opt-in saved JSON reports, offline rendering, and exact-condition
+  comparisons with gained/lost proof and changed-source context.
+- Added `--fail-on-regression` comparison status handling and documented the
+  local `.branchproof/` artifact directory and explicit baseline workflow.
+
 ## [0.3.0] - 2026-09-10
 
 - Add `--missing-only` to focus terminal reports on unproven conditions.

data/doc/README.md

@@ -6,8 +6,8 @@ modifier, and ordinary ternary (`?:`) decisions, records observed vectors,
 and reports independence evidence, missing counterpart constraints, and
 smaller supporting test sets.
 
-The gem is named `branchproof`; its command and compatibility namespace are
-`mcdc` and `MCDC`.
+The gem and primary command are named `branchproof`. The `mcdc` command and
+`MCDC` namespace remain compatibility aliases with the same behavior.
 
 ## Installation
 
@@ -30,12 +30,12 @@ instead of being counted as coverage.
 
 ## Analyze a test run
 
-Run `mcdc analyze` with the source files or globs to inspect, followed by
+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:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
+branchproof analyze 'lib/**/*.rb' --test 'test/**/*_test.rb' \
   --level 3 \
   --format terminal \
   --output tmp/branchproof.txt \
@@ -47,14 +47,14 @@ For a plain Ruby application, select the project policy explicitly when
 running from the application root:
 
 ```sh
-bundle exec mcdc analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'lib/**/*.rb' --project ruby --test 'test/**/*_test.rb'
 ```
 
 For a Rails application, run the same command from the application root so
 the application's bundle and Rails version remain in effect:
 
 ```sh
-bundle exec mcdc analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
+bundle exec branchproof analyze 'app/**/*.rb' --project rails --test 'test/**/*_test.rb'
 ```
 
 For a project rooted at the current directory, `--project auto` is the
@@ -97,7 +97,7 @@ For example, running the contents of the small `decision.rb` /
 with the terminal format produces a summary like this:
 
 ```text
-Branchproof 0.3.0
+Branchproof 0.5.0
 Tests: PASSED (3 tests, 0 failed, 0 skipped)
 MC/DC: 100.0% (2/2 conditions proven)
 Analysis: COMPLETE
@@ -132,7 +132,7 @@ Use `--missing-only` to focus the terminal report on conditions that still
 lack independence evidence:
 
 ```sh
-bundle exec mcdc analyze 'lib/**/*.rb' --missing-only
+bundle exec branchproof analyze 'lib/**/*.rb' --missing-only
 ```
 
 This keeps the overall summary and diagnostics, hides proven conditions and
@@ -185,6 +185,95 @@ test suite. A failed, unsupported, or incomplete run is reported with its
 status and diagnostics and cannot become a successful coverage result by
 changing the display level.
 
+### Focused condition and test views
+
+Use `--view conditions` to group the report by condition. Each condition shows
+its expression, decision, and project-relative source location with the
+condition's own 1-based start line. The view separates tests that evaluated
+the condition true or false from tests where it was short-circuited. Level 3
+also shows the canonical witness observations selected by the analyzer and
+their owning tests.
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions
+bundle exec branchproof analyze 'lib/**/*.rb' --view conditions --missing-only
+```
+
+Use `--view tests` to group the same evidence by test. Rows include each
+exercised condition, its relative source location, observed values, and the
+recorded `setup`, `body`, or `teardown` phases. Tests with no completed
+condition observation remain visible, as do unattributed and unexecuted
+conditions. A test that evaluates both Boolean values is evidence of execution;
+it is a proof contributor only when the analyzer's independent witness pair
+uses its observations.
+
+`--view` changes terminal grouping and does not change instrumentation or test
+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.
+
+### Saved reports and offline comparison
+
+Reports are saved only when requested. Create a local artifact directory and
+write a complete JSON baseline with the existing atomic `--output` option:
+
+```sh
+mkdir -p .branchproof
+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
+```
+
+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. Level 1 reports observations; levels 2 and 3 require corresponding
+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.
+
+To compare two explicitly saved runs:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --format json \
+  --output .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json
+bundle exec branchproof compare .branchproof/baseline.json \
+  .branchproof/current.json --fail-on-regression
+```
+
+Comparison matches exact condition identities from unchanged source files.
+Changed source files, changed selection or runtime context, incomplete runs,
+and legacy reports missing comparison metadata are reported as partial or
+incomplete context rather than guessed regressions. The output distinguishes
+gained proof, lost proof, changed sources, newly selected files, and files no
+longer present in a report. Previous witness values and owner names are shown
+for lost proof; an absent owner is described as `not observed in current run`,
+not as a deleted test. A different test population under unchanged discovery
+patterns is valid comparison context, and seed differences are disclosed.
+
+`compare` exits 0 for a complete comparison, including one with coverage
+changes; `--fail-on-regression` exits 1 when a complete comparable run loses
+proof. 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.
+
+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
+the decision outcome under the masking criterion. Other conditions may be
+short-circuited or masked rather than fixed to the same observed values. For example,
+`left && right` observed as `[TT]` and `[F-]` evaluates `right` once and
+short-circuits it once, but does not prove `right`; `[TF]` is also required.
+The condition and test views preserve that distinction.
+
 ### Supported conditional forms
 
 Ordinary Ruby ternaries use the same predicate instrumentation and `&&`/`||`
@@ -230,7 +319,7 @@ Everything after the argument separator is passed as individual arguments to
 the serial Minitest runner. This is useful for seeds and name filters:
 
 ```sh
-mcdc analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
+branchproof analyze 'lib/**/*.rb' --level 1 -- --seed 9001 -n /checkout/
 ```
 
 The 0.2 release supports serial Minitest execution in plain Ruby projects and

data/exe/branchproof

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "branchproof"
+exit Branchproof::CLI.new(stdout: $stdout, stderr: $stderr).call(ARGV)