branchproof 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5027104f6aeb6181f75ccc463ef93d6cf78489ba28e8c6824308d13546a5586
-  data.tar.gz: 442f07bf0dc87e1f3ed5bcc371d130da1612afd91f69837f8869b81fdf7c95f6
+  metadata.gz: a76f20e6504affb4e614eeca901b0ef515f8bbb0785a641cf437263cac2df418
+  data.tar.gz: 87373206990831eeba3c1a2317049a4679343b4e4770015fb3e322710c7035e9
 SHA512:
-  metadata.gz: 707ca0fff8681d36f7a0e635513c3914ed403ddaf0e96c1ddec646574abee54daf50e60f05c16a79d2b522a7f568a09ee99da3807161dd471646291442f80323
-  data.tar.gz: 3c446a3c71dd5a89cc0f12fa77ef61ef96a339a81bffd744dad86db4d2d7044f28c34a294342b29868b2ed848be1892892d8e28eff29f4e55f9b72a4ee57be62
+  metadata.gz: 97b1aca56ec2e2ed60f683e7647ce91ec85f3b8a2bbe457cf6844b0bd7db9b6117a126bce8ec74f04e4805dc147beef6b58fa003f74d73bd6e18884973115833
+  data.tar.gz: 1aac59c7cc767f9ef805cdcfecbe8e5e6628e25ea09cc8d862b32b0518f9aad89f6f8204b69d4183c75af1938e94a61e3ba980f6fa396bbff542b464bf371896

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [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.
+- Explain missing observations with required truth values and comparison tests.
+- Fix incorrect `INFEASIBLE_IN_MODEL` results caused by missing source identifiers.
+
 ## [0.2.0] - 2026-09-09
 
 - Prepared the initial public-release candidate.

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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.2.0
+Branchproof 0.4.0
 Tests: PASSED (3 tests, 0 failed, 0 skipped)
 MC/DC: 100.0% (2/2 conditions proven)
 Analysis: COMPLETE
@@ -126,6 +126,53 @@ Additional tests outside this MC/DC evidence set may improve coverage.
 The test execution still runs once for the selected level. Use `--format
 json` when a consumer needs the complete identifiers and versioned schema.
 
+### Find missing cases
+
+Use `--missing-only` to focus the terminal report on conditions that still
+lack independence evidence:
+
+```sh
+bundle exec branchproof analyze 'lib/**/*.rb' --missing-only
+```
+
+This keeps the overall summary and diagnostics, hides proven conditions and
+supporting-set lists, and shows missing scenarios using the source expressions.
+It works with levels 2 and 3 (the default). JSON remains the complete report;
+`--missing-only` cannot be combined with `--format json` or `--level 1`.
+
+For example, given this decision:
+
+```ruby
+content && Instruction.installed?(content)
+```
+
+Observing `[TT]` and `[F-]` proves the effect of `content`, but does not prove
+the effect of `Instruction.installed?(content)`. The missing case is `[TF]`:
+`content` must be truthy and `Instruction.installed?(content)` must be falsey,
+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]
+```
+
+An existing file without the instruction block
+may produce this case; the test must reach the reported line. The report
+describes required truth values, not application inputs or guaranteed
+reachable paths. In Ruby, only `false` and `nil` are falsey; an empty string
+is truthy.
+
+`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.
+`Analysis: COMPLETE` means the analysis finished, not that every condition
+was proven. Missing conditions may require new tests or changes to existing
+test inputs; they do not by themselves prove a bug in the application.
+
 The levels select how much of the one-run result is displayed:
 
 * Level 1 reports observed vectors grouped by their raw decision outcomes.
@@ -138,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 `&&`/`||`
@@ -183,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,18 @@ 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.
+
 ### `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)` <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,23 @@
 ## [Unreleased]
 
+## [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.
+- Explain missing observations with required truth values and comparison tests.
+- Fix incorrect `INFEASIBLE_IN_MODEL` results caused by missing source identifiers.
+
 ## [0.2.0] - 2026-09-09
 
 - Prepared the initial public-release candidate.