branchproof 0.2.0

data/doc/Branchproof/Minimizer.md

@@ -0,0 +1,15 @@
+# Class Branchproof::Minimizer <a id="class-Branchproof-Minimizer"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/minimizer.rb |
+
+Computes minimum vector or test covers for proven obligations.
+
+## Public Instance Methods
+### `call(objective:, decision_ids:)` <a id="method-i-call"></a> <a id="call-instance_method"></a>
+- **@raise** [ArgumentError]
+
+### `initialize(analysis:, evidence:, limits:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Minimizer] a new instance of Minimizer

data/doc/Branchproof/MinitestAdapter.md

@@ -0,0 +1,28 @@
+# Class Branchproof::MinitestAdapter <a id="class-Branchproof-MinitestAdapter"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/minitest_adapter.rb |
+
+Bridges one serial Minitest run to Runtime lifecycle ownership.
+
+## Attributes
+### `active_adapter` [RW] <a id="attribute-c-active_adapter"></a> <a id="active_adapter-class_method"></a>
+Returns the value of attribute active_adapter.
+
+### `tests` [R] <a id="attribute-i-tests"></a> <a id="tests-instance_method"></a>
+Returns the value of attribute tests.
+
+## Public Instance Methods
+### `capabilities()` <a id="method-i-capabilities"></a> <a id="capabilities-instance_method"></a>
+Not documented.
+
+### `initialize(runtime:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [MinitestAdapter] a new instance of MinitestAdapter
+
+### `run(test_files:, runner_args:, on_complete:, before_load: = nil)` <a id="method-i-run"></a> <a id="run-instance_method"></a>
+Not documented.
+
+### `validate_runner!()` <a id="method-i-validate_runner-21"></a> <a id="validate_runner!-instance_method"></a>
+- **@raise** [ArgumentError]

data/doc/Branchproof/Project.md

@@ -0,0 +1,23 @@
+# Class Branchproof::Project <a id="class-Branchproof-Project"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/project.rb |
+
+Resolves the project policy used by the isolated analysis worker.
+
+## Constants
+### `MODES` <a id="constant-MODES"></a> <a id="MODES-constant"></a>
+Not documented.
+
+### `RAILS_ENVIRONMENT` <a id="constant-RAILS_ENVIRONMENT"></a> <a id="RAILS_ENVIRONMENT-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `initialize(root:, mode: = "auto")` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [Project] a new instance of Project
+
+### `to_h()` <a id="method-i-to_h"></a> <a id="to_h-instance_method"></a>
+Not documented.

data/doc/Branchproof/RailsSupport/Error.md

@@ -0,0 +1,6 @@
+# Class Branchproof::RailsSupport::Error <a id="class-Branchproof-RailsSupport-Error"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | StandardError |
+| **Defined in** | lib/branchproof/rails_support.rb |

data/doc/Branchproof/RailsSupport.md

@@ -0,0 +1,32 @@
+# Module Branchproof::RailsSupport <a id="module-Branchproof-RailsSupport"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/rails_support.rb |
+
+Boots the selected Rails application after Branchproof's load hook is active.
+
+## Public Class Methods
+### `boot(project:)` <a id="method-c-boot"></a> <a id="boot-class_method"></a>
+Not documented.
+
+### `boot_environment(environment)` <a id="method-c-boot_environment"></a> <a id="boot_environment-class_method"></a>
+Not documented.
+
+### `environment_path(project)` <a id="method-c-environment_path"></a> <a id="environment_path-class_method"></a>
+Not documented.
+
+### `metadata()` <a id="method-c-metadata"></a> <a id="metadata-class_method"></a>
+Not documented.
+
+### `rails_application()` <a id="method-c-rails_application"></a> <a id="rails_application-class_method"></a>
+- **@raise** [Error]
+
+### `reloading_enabled?(config)` <a id="method-c-reloading_enabled-3F"></a> <a id="reloading_enabled?-class_method"></a>
+- **@return** [Boolean]
+
+### `validate_application!()` <a id="method-c-validate_application-21"></a> <a id="validate_application!-class_method"></a>
+- **@raise** [Error]
+
+### `validate_test_environment()` <a id="method-c-validate_test_environment"></a> <a id="validate_test_environment-class_method"></a>
+- **@raise** [Error]

data/doc/Branchproof/Records.md

@@ -0,0 +1,38 @@
+# Module Branchproof::Records <a id="module-Branchproof-Records"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/records.rb |
+
+Builds immutable records and stable identifiers for analysis artifacts.
+
+## Public Class Methods
+### `build(value)` <a id="method-c-build"></a> <a id="build-class_method"></a>
+Not documented.
+
+### `canonical(value)` <a id="method-c-canonical"></a> <a id="canonical-class_method"></a>
+Not documented.
+
+### `condition_id(decision_id, index)` <a id="method-c-condition_id"></a> <a id="condition_id-class_method"></a>
+Not documented.
+
+### `decision_id(source_id:, context:, byte_start:, byte_length:, tree:)` <a id="method-c-decision_id"></a> <a id="decision_id-class_method"></a>
+Not documented.
+
+### `deep_freeze(value)` <a id="method-c-deep_freeze"></a> <a id="deep_freeze-class_method"></a>
+Not documented.
+
+### `diagnostic(code:, message:, severity: = "warning", source_id: = nil, decision_id: = nil, execution_id: = nil, test_id: = nil, details: = {})` <a id="method-c-diagnostic"></a> <a id="diagnostic-class_method"></a>
+Not documented.
+
+### `id(value)` <a id="method-c-id"></a> <a id="id-class_method"></a>
+Not documented.
+
+### `normalize(value)` <a id="method-c-normalize"></a> <a id="normalize-class_method"></a>
+Not documented.
+
+### `normalize_unknown(value)` <a id="method-c-normalize_unknown"></a> <a id="normalize_unknown-class_method"></a>
+Not documented.
+
+### `source_id(relative_path:, digest:, encoding: = "UTF-8")` <a id="method-c-source_id"></a> <a id="source_id-class_method"></a>
+Not documented.

data/doc/Branchproof/Report.md

@@ -0,0 +1,26 @@
+# Class Branchproof::Report <a id="class-Branchproof-Report"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/report.rb |
+
+Renders versioned terminal and JSON analysis reports.
+
+## 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.
+
+## Public Instance Methods
+### `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>
+- **@raise** [ArgumentError]
+- **@return** [Report] a new instance of Report
+
+### `write(io:, format:)` <a id="method-i-write"></a> <a id="write-instance_method"></a>
+- **@raise** [ArgumentError]

data/doc/Branchproof/Runtime.md

@@ -0,0 +1,37 @@
+# Module Branchproof::Runtime <a id="module-Branchproof-Runtime"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/runtime.rb |
+
+Process-local execution recorder. It deliberately never coerces or stores
+application values: Ruby's conditional expression is used for truthiness.
+Captures condition evaluations while preserving application values.
+
+## Public Class Methods
+### `boot(evidence:)` <a id="method-c-boot"></a> <a id="boot-class_method"></a>
+Not documented.
+
+### `condition(decision_id, index, value)` <a id="method-c-condition"></a> <a id="condition-class_method"></a>
+Not documented.
+
+### `context(test_id:, phase:)` <a id="method-c-context"></a> <a id="context-class_method"></a>
+Not documented.
+
+### `diagnostics()` <a id="method-c-diagnostics"></a> <a id="diagnostics-class_method"></a>
+Not documented.
+
+### `enter(decision_id)` <a id="method-c-enter"></a> <a id="enter-class_method"></a>
+Not documented.
+
+### `finish(decision_id, value)` <a id="method-c-finish"></a> <a id="finish-class_method"></a>
+Not documented.
+
+### `leave(decision_id)` <a id="method-c-leave"></a> <a id="leave-class_method"></a>
+Not documented.
+
+### `register_test(test:)` <a id="method-c-register_test"></a> <a id="register_test-class_method"></a>
+Not documented.
+
+### `snapshot()` <a id="method-c-snapshot"></a> <a id="snapshot-class_method"></a>
+Not documented.

data/doc/Branchproof/Source.md

@@ -0,0 +1,23 @@
+# Class Branchproof::Source <a id="class-Branchproof-Source"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/branchproof/source.rb |
+
+Inventories supported condition and decision occurrences from Ruby files.
+
+## Attributes
+### `limits` [R] <a id="attribute-i-limits"></a> <a id="limits-instance_method"></a>
+Returns the value of attribute limits.
+
+### `root` [R] <a id="attribute-i-root"></a> <a id="root-instance_method"></a>
+Returns the value of attribute root.
+
+## Public Instance Methods
+### `initialize(root:, limits:)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@raise** [ArgumentError]
+- **@return** [Source] a new instance of Source
+
+### `inventory(paths:)` <a id="method-i-inventory"></a> <a id="inventory-instance_method"></a>
+- **@raise** [ArgumentError]

data/doc/Branchproof/Worker.md

@@ -0,0 +1,45 @@
+# Module Branchproof::Worker <a id="module-Branchproof-Worker"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/branchproof/worker.rb |
+
+Runs one isolated Minitest worker and atomically exports its result.
+
+## Public Class Methods
+### `boot_project(project)` <a id="method-c-boot_project"></a> <a id="boot_project-class_method"></a>
+Not documented.
+
+### `child_process(config_path)` <a id="method-c-child_process"></a> <a id="child_process-class_method"></a>
+Not documented.
+
+### `completion_result(baseline:, project:, rails_metadata:, evidence:, tests:, diagnostics:)` <a id="method-c-completion_result"></a> <a id="completion_result-class_method"></a>
+This result boundary intentionally carries the complete worker payload.
+rubocop:disable-next Metrics/ParameterLists
+
+### `incomplete_evidence(evidence, diagnostics)` <a id="method-c-incomplete_evidence"></a> <a id="incomplete_evidence-class_method"></a>
+Not documented.
+
+### `legacy_project()` <a id="method-c-legacy_project"></a> <a id="legacy_project-class_method"></a>
+Not documented.
+
+### `normalize(value)` <a id="method-c-normalize"></a> <a id="normalize-class_method"></a>
+Not documented.
+
+### `prepend_load_paths(project)` <a id="method-c-prepend_load_paths"></a> <a id="prepend_load_paths-class_method"></a>
+Not documented.
+
+### `project_metadata(project, rails_metadata)` <a id="method-c-project_metadata"></a> <a id="project_metadata-class_method"></a>
+Not documented.
+
+### `project_metadata_for(payload)` <a id="method-c-project_metadata_for"></a> <a id="project_metadata_for-class_method"></a>
+Not documented.
+
+### `symbolize(value)` <a id="method-c-symbolize"></a> <a id="symbolize-class_method"></a>
+Not documented.
+
+### `write_completion(payload, result)` <a id="method-c-write_completion"></a> <a id="write_completion-class_method"></a>
+Not documented.
+
+### `write_failure(payload, code, details)` <a id="method-c-write_failure"></a> <a id="write_failure-class_method"></a>
+Not documented.

data/doc/Branchproof.md

@@ -0,0 +1,33 @@
+# Module Branchproof <a id="module-Branchproof"></a>
+
+|  |  |
+| --- | --- |
+| **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 |
+
+Public namespace for source inventory and one-run MC/DC reporting.
+
+## Constants
+### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
+Not documented.
+
+# Documentation
+
+- [Branchproof/Analyzer.md](Branchproof/Analyzer.md)
+- [Branchproof/CLI.md](Branchproof/CLI.md)
+- [Branchproof/Error.md](Branchproof/Error.md)
+- [Branchproof/Evidence.md](Branchproof/Evidence.md)
+- [Branchproof/Instrumenter.md](Branchproof/Instrumenter.md)
+- [Branchproof/Limits.md](Branchproof/Limits.md)
+- [Branchproof/Loader.md](Branchproof/Loader.md)
+- [Branchproof/Minimizer.md](Branchproof/Minimizer.md)
+- [Branchproof/MinitestAdapter.md](Branchproof/MinitestAdapter.md)
+- [Branchproof/Project.md](Branchproof/Project.md)
+- [Branchproof/RailsSupport/Error.md](Branchproof/RailsSupport/Error.md)
+- [Branchproof/RailsSupport.md](Branchproof/RailsSupport.md)
+- [Branchproof/Records.md](Branchproof/Records.md)
+- [Branchproof/Report.md](Branchproof/Report.md)
+- [Branchproof/Runtime.md](Branchproof/Runtime.md)
+- [Branchproof/Source.md](Branchproof/Source.md)
+- [Branchproof/Worker.md](Branchproof/Worker.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [README.md](README.md)

data/doc/CHANGELOG.md

@@ -0,0 +1,36 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-09-09
+
+- Prepared the initial public-release candidate.
+- Embedded evidence snapshots now report the package version used to produce them.
+
+- Added the `mcdc analyze` command for one serial Minitest run.
+- Added Levels 1–3 reports for observations, supporting sets, and MC/DC
+  independence evidence in terminal and JSON formats.
+- Added bounded analysis limits and explicit diagnostics for unsupported or
+  incomplete evidence.
+- Added automatic and explicit Ruby and Rails project selection for
+  `mcdc analyze`.
+- Added deterministic Minitest discovery for both `*_test.rb` and `test_*.rb`
+  files.
+- Added isolated Rails test boot with serial, test-environment defaults and
+  Rails project metadata in reports.
+- Added support documentation for plain Ruby and Rails projects, including
+  the tested Rails 8.1 integration boundary.
+- Added support for ordinary Ruby ternary (`condition ? left : right`)
+  predicates, including existing `&&`/`||` condition trees and predicate
+  outcome semantics independent of the selected branch value.
+- Improved terminal reports with readable decision and condition labels,
+  test names, compact collision-safe IDs, witness and constraint details, and
+  named supporting-test sets while preserving the full JSON report.
+- Fixed nested predicate selection so executed ternary decisions are recorded
+  across all nested levels without instrumenting unchosen branches.
+- Changed the project license to Apache-2.0; packaged `LICENSE.txt` and
+  `NOTICE`.
+- Renamed the gem and public namespace to `branchproof` and `Branchproof`;
+  retained `mcdc` and `MCDC` as compatibility surfaces.
+
+## [0.1.0] - 2026-09-09 (unpublished internal milestone)
+
+- Initial analytical core and Minitest instrumentation milestone.

data/doc/README.md

@@ -0,0 +1,242 @@
+# Branchproof
+
+Branchproof measures modified condition/decision coverage (MC/DC) from one
+serial Minitest run. It inventories supported `if`, `unless`, `elsif`,
+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`.
+
+## Installation
+
+```sh
+gem install branchproof
+```
+
+Or add it to a bundle:
+
+```sh
+bundle add branchproof
+```
+
+Branchproof targets CRuby 3.3 and 3.4, Minitest 5.x, and Prism 1.x. The
+published core runtime matrix is the CI matrix. Rails support is optional and
+has been locally checked against Rails 8.1.3.1 on CRuby 3.4.5; Rails is
+supplied by the application and is not a runtime dependency of this gem.
+Unsupported syntax and incomplete observations remain visible in the report
+instead of being counted as coverage.
+
+## Analyze a test run
+
+Run `mcdc 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' \
+  --level 3 \
+  --format terminal \
+  --output tmp/branchproof.txt \
+  --limits branchproof-limits.json \
+  -- --seed 1234
+```
+
+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'
+```
+
+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'
+```
+
+For a project rooted at the current directory, `--project auto` is the
+default. It selects Rails only when both `config/application.rb` and
+`config/environment.rb` exist; otherwise it selects a plain Ruby project.
+Use `--project ruby` or `--project rails` to override detection. An explicit
+Rails project without both boot files is a usage error.
+
+Project defaults discover the sorted, de-duplicated union of
+`test/**/*_test.rb` and `test/**/test_*.rb`. Helper, support, and fixture files
+are excluded from that default set. `--test` remains authoritative when test
+files are selected explicitly. The worker prepends the project's `lib` and
+`test` directories to its child load path, so application `require` calls
+resolve without changing the parent process.
+
+Rails analysis boots `config/environment.rb` and `rails/test_help` inside the
+isolated worker after Branchproof's loader and Minitest hooks are installed. The
+child receives `RAILS_ENV=test`, `RACK_ENV=test`, `PARALLEL_WORKERS=1`,
+`DISABLE_BOOTSNAP=1`, and `DISABLE_SPRING=1`; the invoking process environment
+is unchanged. The Rails metadata in the report identifies the selected
+project and Rails version.
+
+`--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
+versions, baseline status, diagnostics, completeness, observations, and
+analysis fields.
+
+The terminal format is a compact reading view of the same report. It keeps
+JSON's full stable identifiers and schema unchanged, while shortening IDs to
+eight-character prefixes (extending a prefix when two IDs collide) and
+displaying known Minitest owners as `ClassName#test_method`. When test
+metadata is unavailable, the owner falls back to its short ID. Level 3 adds
+the witness pair or missing counterpart constraints beside each condition;
+Level 2 and Level 3 also list named supporting tests. Repeated supporting-set
+rows are collapsed in terminal output only.
+
+For example, running the contents of the small `decision.rb` /
+`test_decision_test.rb` fixture from a project `lib/` and `test/` directory
+with the terminal format produces a summary like this:
+
+```text
+Branchproof 0.2.0
+Tests: PASSED (3 tests, 0 failed, 0 skipped)
+MC/DC: 100.0% (2/2 conditions proven)
+Analysis: COMPLETE
+Decisions: 1 supported, 0 excluded, 0 unexecuted (1 discovered)
+Observations: 3 completed, 0 aborted, 0 unattributed
+Values: T=true, F=false, -=short-circuited
+Scope: supported decisions and conditions
+
+Decision dde7aede lib/decision.rb:7
+  Decision: left && right
+  Status: SUPPORTED
+  Condition 0: left
+    PROVEN (witness 484eab21 + 8908881e)
+  Condition 1: right
+    PROVEN (witness e5ec8058 + 8908881e)
+  Vector e5ec8058 [TF] => F owners=CliFixtureTest#test_true_false_vector
+  Vector 8908881e [TT] => T owners=CliFixtureTest#test_true_true_vector
+  Vector 484eab21 [F-] => F owners=CliFixtureTest#test_false_true_vector
+
+Supporting sets:
+  Vectors (EXACT_MINIMUM, decisions: [dde7aede]): 484eab21, 8908881e, e5ec8058
+  Tests (EXACT_MINIMUM, decisions: [dde7aede]): CliFixtureTest#test_true_true_vector, CliFixtureTest#test_false_true_vector, CliFixtureTest#test_true_false_vector
+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.
+
+The levels select how much of the one-run result is displayed:
+
+* Level 1 reports observed vectors grouped by their raw decision outcomes.
+* Level 2 includes the smallest supporting sets found for vectors and tests.
+* Level 3 (the default) includes condition independence witnesses and
+  counterpart constraints, as well as the Level 1 and 2 evidence.
+
+Level 2 and Level 3 compute from the same captured run. They do not rerun the
+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.
+
+### Supported conditional forms
+
+Ordinary Ruby ternaries use the same predicate instrumentation and `&&`/`||`
+condition trees as supported `if` decisions. For example:
+
+```ruby
+value = ready ? false : true
+```
+
+Branchproof records `ready` as the ternary predicate. The decision outcome is
+therefore the truth value of `ready`, even though the selected branch returns
+`false` or `true`; branch selection, returned values, object identity, and
+evaluation order are unchanged. Ternaries nested inside other predicates are
+also inventoried at their own level, including all executed nested levels.
+Expanding the supported syntax increases the eligible-condition denominator,
+so percentages should be compared with that changed scope in mind.
+
+The existing predicate exclusions and analysis limits still apply. Keyword
+`and`/`or` expressions, contextual syntax, unsafe or ambiguous predicates,
+and limit overflows remain diagnostics rather than eligible coverage.
+
+### Limits
+
+`--limits` accepts a JSON object containing positive integer overrides. The
+available keys are `conditions_per_decision`, `vectors_per_decision`,
+`owner_associations_per_run`, `tests_per_run`, `exact_candidates`,
+`exact_search_nodes`, and `constraint_search_states`.
+
+```json
+{
+  "vectors_per_decision": 4096,
+  "exact_search_nodes": 50000
+}
+```
+
+Unknown keys and non-positive values are usage errors. When a limit is
+reached, the report says that evidence or analysis is incomplete; it does not
+claim a complete result from truncated data.
+
+### Runner arguments
+
+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/
+```
+
+The 0.2 release supports serial Minitest execution in plain Ruby projects and
+Rails applications. Rails lazy and eager loading are supported when the
+application does not enable reloading for the test run. RSpec, parallel or
+forked runners, mutation execution, Rails system/browser tests, custom Rails
+test commands, generated tests, and reloading configurations are outside this
+release and produce diagnostics rather than a passing analysis.
+
+## Library entry points
+
+```ruby
+require "branchproof"
+
+Branchproof::Limits.default
+Branchproof::Records.id(name: "stable identity")
+```
+
+`require "mcdc"` and `MCDC` are compatibility aliases for the same public
+namespace. The CLI is the supported way to run a complete analysis;
+`Branchproof::Project` exposes project selection and child-environment policy,
+and `Branchproof::RailsSupport` is the optional Rails boot boundary. The library
+classes expose the source, runtime, evidence, analysis, and report contracts
+for adapters and integrations.
+
+## Development
+
+Use an explicit Ruby executable on systems with multiple Rubies. Clearing
+inherited gem paths prevents one Ruby installation from loading another's
+gems:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+To run the real Rails integration locally, install the optional test bundle
+and set its required flag:
+
+```sh
+BRANCHPROOF_RAILS_INTEGRATION=1 bundle install
+BRANCHPROOF_RAILS_INTEGRATION=1 bundle exec ruby -Ilib:test test/test_rails_integration.rb
+```
+
+The flag makes a missing Rails dependency a failure in the integration job;
+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.
+
+## License
+
+Branchproof is available under the [Apache License, Version 2.0](LICENSE.txt).

data/exe/mcdc

@@ -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)