specproof 0.1.0

data/docs/rbs-implementation-status.md

@@ -0,0 +1,115 @@
+# RBS scalar integration results
+
+This page records the RBS scalar integration as delivered on 2026-10-02. Its
+implementation slices, verification counts, pilots, and limitations below are
+historical evidence for that change. The method-target extension delivered on
+2026-10-06 supersedes the target-form limitations described in the historical
+sections; those earlier artifacts are retained as originally recorded.
+
+The approved [plan](superpowers/plans/2026-10-02-rbs-scalar-integration.md), commit `49a233a`, is implemented on `implement/rbs-scalar-integration` in the isolated `tmp/worktrees/rbs-scalar-integration` worktree. The original checkout remains on `implement/first-usable-release`. No push, publication, or merge is included.
+
+## Delivered behavior
+
+An optional RBS 4.2.0 reader imports explicitly selected, directly declared public class-instance input signatures. Scalar type facts compose with existing DSL domains; checking, planning, and collection consume the source-neutral IR. Finite inputs work without duplicate declarations; unrestricted integers require behavioral refinements. Unsupported selected types fail atomically with named limitations.
+
+Refinements may narrow imported types, but incompatible admitted values remain visible. Checking reports a concrete witness and both declaration sources; planning rejects conflicts. Integer compatibility checks scan declared members rather than enumerating ranges, including integers beyond machine width. Equivalent compiled contracts retain existing obligation IDs, criterion, and behavioral digest.
+
+Public loading, repeatable CLI `--rbs`/`--target` options, and Minitest installation accept the same source selection. Reports distinguish canonical supplied declarations from all resulting runtime targets. Preparation failures preserve original tests and mark analysis incomplete. Collection observes effective bound values; argument omission and output behavior are not measured.
+
+For a target selected from RBS, extra DSL input names raise
+`rbs_input_mismatch` before planning, with both declaration locations. This
+adapter-level check preserves generic composition of partial type facts.
+Unselected DSL targets and correctly named partial refinements remain valid.
+
+The core gem retains **zero runtime dependencies**. The default Gemfile and lockfile are unchanged. RBS lives in the opt-in `Gemfile.rbs`; core checks/plans and skill export work without it.
+
+## Implementation slices
+
+| Task | Result |
+| --- | --- |
+| 1 | `765db3e`: immutable scalar constraints/facts, provenance, nonenumerating interval checks |
+| 2 | `c4dd0e3`: composition, duplicate rejection, conflict checking, shared planning |
+| 3 | `ae121b2`: real-parser reader and private projector with explicit supported shapes |
+| 4 | `b465d5c`: public API/CLI, RBS-only and mixed loading, API signatures |
+| 5 | `53b379d`: Minitest source integration, declaration scope, preserved failure lifecycle |
+| Review fix | `c0d32ad`: reject absent selected-RBS input bindings before offline planning |
+| 6 | `fbe97f6`: Registration example, updated packaged skills, package isolation, six fresh Luna evaluations |
+| 7 | Separate CI lane, three-Ruby matrix, unchanged-RBS project pilot, manifests and final audit |
+
+Code slices received independent Luna specification and quality reviews. Scalar constraints live with their operations in `type_constraints.rb`; input facts and generic provenance remain in `model.rb`. A private projector separates AST conversion from reader orchestration. These are file-placement adjustments. No generic adapter registry, nominal domain system, solver, generated DSL, or default evaluator was introduced.
+
+Changed core files are `lib/specproof.rb` and
+`lib/specproof/{model,type_constraints,composer,checker,planner,report,loader}.rb`.
+Integration files are `lib/specproof/sources/{rbs,rbs_projector}.rb`,
+`lib/specproof/{cli,minitest}.rb`, `sig/specproof.rbs`, `Gemfile.rbs`, its lockfile,
+and `.github/workflows/main.yml`. Regression coverage is in the scalar/composer
+tests, `test/rbs/`, and `test/packaging_test.rb`. Packaged workflows and evidence
+live in `skills/`, `examples/rbs_registration/`, and the linked documentation.
+
+## Verification
+
+| Check | Actual result |
+| --- | --- |
+| Default Ruby 4.0.1 `bundle exec rake` | 156 tests, 786 assertions; zero failures/errors/skips; 95 files linted, no offenses |
+| `ruby bin/check` | Syntax, skill/package checks and real gem build passed; focused 2 tests, 76 assertions |
+| Focused runtime regression | 47 tests, 376 assertions; zero failures/errors/skips |
+| CRuby 3.3.6 / 3.4.7 / 4.0.1 | Each core 156 tests/786 assertions; optional RBS 39 tests/396 assertions; zero failures/errors/skips |
+| API declarations | Optional-bundle `rbs -I sig validate` passed |
+| Package and skills | Real installed gem outside checkout; parser-free core CLI, idempotent export and conflict preservation passed |
+| Guided Luna tasks | Six observed outcomes matched supplied requirements; exact exported skills and 17 installed library files audited |
+
+[Compatibility and pilot evidence](pilots/rbs-v0.1/README.md) retains exact commands, raw matrix logs, isolated environments, package versions/paths, and published package hashes. [Agent evaluation evidence](evaluations/rbs-agent-skills-v0.1.md) retains rules, reports, actions, edited files, and archive manifests. Newly added prose-matching tests were removed during review; existing structural skill checks, package checks, and actual behavioral evaluations provide verification.
+
+## Distinct demonstrations
+
+**Shipped example.** [Registration](../examples/rbs_registration/README.md) imports integer age and nullable boolean consent, declaring only age bounds/partitions. Its independent rule requires age at least 18 and true consent. Baseline tests pass with 8/9 marginal obligations; the added boundary assertion fails against `age > 18` while 9/9 inputs are hit; the corrected implementation passes with a fresh 9/9 report. Checkpoints retain identical IDs/digest and distinct UUIDs. Nine marginal values do not mean nine combinations or output conformance proof.
+
+**Guided agent tasks.** Six fresh Luna actors used installed-gem exported skills for finite RBS-only authoring, partial refinement, conflicts, unsupported unions, stale evidence, and a justified boundary fix. The boundary actor's RED assertion stopped its remaining examples, giving 5/9 before a final passing 9/9 run. The stale actor rejected an old passing 9/9 report despite matching input identity, then reported the actual fresh age-18 failure and 5/9 evidence. These differ from the shipped example's separate-test RED run. Explicit selectors and a command helper were supplied; this is not a client-discovery or general reliability claim.
+
+**Existing RBS adoption.** BranchProof commit `85611af97461d1714bffffff42a4719952b9cbc4` supplies the unchanged `Branchproof::ComparisonReport#exit_code` signature. RBS-only planning yields two boolean obligations; the unchanged focused test passes 2 tests/8 assertions and exercises both. All 59 snapshot files match original source hashes. No test or gap was manufactured, and no full BranchProof suite result is claimed. Rejected candidates from the seven-location survey are documented separately.
+
+## Historical remaining limits at RBS integration
+
+Only verified RBS 4.2.0 is supported. Inputs are booleans, nil, supported primitive literals (including finite string literals), supported unions/optionals, and resolved built-in Integer with explicit refinement where needed. Unrestricted `String`, nominal objects, aliases, generics, collections, overloads, inherited/singleton/generated methods, rest/block/unnamed forms, and zero-input targets remain excluded. A selected union containing an unsupported member fails atomically. RBS return types are ignored and provide no expected-result oracle. Full RBS arity/order/subtyping conformance, omission coverage, nullable interval domains, automatic discovery, Sorbet, state analysis, and SMT reasoning remain separate work.
+
+## Current method target forms
+
+The method-target extension supports canonical string and Ruby method-object
+targets for DSL declarations, including directly defined public instance
+methods on named classes and singleton methods on named classes or modules.
+Equivalent string and object forms normalize to the same target identity,
+digest, and obligation IDs. String declarations stay offline and do not
+autoload owners. Method-object declarations require loaded code and use Ruby
+reflection without invoking the target. RBS selection continues to use
+explicit canonical string selectors and now supports `def self.method` on
+named classes and modules, subject to the existing RBS shape limitations.
+
+Method objects are validated at declaration time against the current direct
+definition. Aliases, inherited singleton methods, anonymous owners, and bound
+methods on arbitrary instances remain unsupported. Collection resolves
+canonical names afresh at start and retains the runtime method identity,
+constant binding, redefinition, and duplicate-binding guards. Reports continue
+to use canonical string targets. Navigation from these names remains dependent
+on language-server support.
+
+These target-form additions do not change the historical RBS pilot outputs or
+claims. The RBS return type still supplies no expected-result oracle; behavior
+assertions must come from independent requirements.
+
+### Finite RBS strings
+
+The finite-string extension accepts RBS string literals, their supported finite
+unions, and optional forms. These reuse the exact finite-string input domain:
+strings remain distinct from same-spelling symbols, and no text normalization
+is performed. An unrestricted `String` input is still outside the adapter's
+finite scenario model. Return types remain ignored, so expected results must
+come from an independent requirement. See the [compact DeliveryOptions example](../examples/rbs_string_literals/README.md).
+
+Matching digests establish equivalent normalized behavioral input contracts, not current implementation text or correctness. Obtain fresh runtime evidence after any source change. Historical evaluation and pilot artifacts remain unchanged; their original hashes are audited separately. Final independent specification/quality review and evidence audit are recorded in the concluding commits.
+
+The [independent final audit](pilots/rbs-v0.1/independent-final-audit.json)
+verified archive/member hashes, all 17 installed library files, four skill
+assets, fresh report identity/scope, three-Ruby logs, published package hashes,
+and 59 unchanged pilot source files. All [125 historical artifact hashes](pilots/rbs-v0.1/historical-original-sha-map.json)
+remain unchanged. Final specification and quality reviews approved the
+input-binding correction and remaining scope; no known blocker remains.

data/docs/rbs-string-literals-results.md

@@ -0,0 +1,58 @@
+# RBS string-literal inputs
+
+RBS 4.2.0 string literals now supply exact finite input domains to the existing
+checker, planner, Minitest collector and suggestion command. A combinations-only
+DSL declaration can use those imported values without repeating them. Optional
+literal types, supported mixed unions, String/Symbol distinctions, source
+provenance and DSL subset refinements retain the existing domain semantics.
+
+The implementation reuses `Domains.supported_string?` and the existing immutable
+type constraints. It adds no dependency, criterion or report schema. Reading
+RBS files explicitly as UTF-8 matches RBS's own environment loader and prevents
+locale-dependent interpretation of Unicode literals. Unrestricted `String`,
+aliases, collections and other unsupported selected union members remain
+rejected. Invalid UTF-8 files return `rbs_parse_error` with their path. Return
+types remain outside analysis.
+
+## Demonstrated workflow
+
+The [DeliveryOptions example](../examples/rbs_string_literals/README.md) imports
+`country: ("ro" | "de")` and `expedited: bool` from its signature. Three passing
+calls exercise 3/4 pairs. The suggestion identifies `country="de",
+expedited=true`; a separate assertion justified by the written delivery rule
+produces a fresh 4/4 report. This demonstrates a coverage improvement without
+claiming that full pair coverage proves behavior.
+
+## Agent guidance
+
+A Luna baseline actor read the previous main-branch skills at `53b621d` and
+correctly reported that the literal-union workflow was unsupported. This is
+a coordinator-retained summary, not a benchmark or model attestation.
+
+A fresh Luna actor used the built gem's exported skills and the example's
+independent requirement to run check, plan, coverage and suggestions. Its
+baseline had one missing pair; the completed run had none. Separate unrestricted
+`String` and literal-plus-`Object` probes failed atomically. The coordinator
+replayed the workflow against the final installed library and checked its
+library and skill hashes against source. Evidence is retained under
+`evaluations/artifacts/rbs-string-literals/`.
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| Core suite on Ruby 3.3.6, 3.4.7 and 4.0.1 | 250 tests / 1,297 assertions per runtime |
+| Optional RBS suite on those runtimes | 53 tests / 490 assertions per runtime |
+| RBS signature validation on those runtimes | Passed |
+| Default locked development bundle | Core suite passed; 130 files linted without offenses |
+| `bin/check` | Syntax checks, 2 packaging tests / 76 assertions, and build passed |
+| Final installed-gem example | Passing baseline 3/4; suggested missing pair; passing completion 4/4 |
+| Unsupported-type probes | `String` and literal-plus-`Object` rejected with exit 2 |
+
+[Matrix commands and environments](evaluations/artifacts/rbs-string-literals/verification/commands.json),
+[installed workflow evidence](evaluations/artifacts/rbs-string-literals/agent/command-evidence.json),
+and [installed library/skill hashes](evaluations/artifacts/rbs-string-literals/installed-sha256.json)
+are retained. Historical Ruby snapshots use `.rb.txt` so they do not join the
+active tests or lint scope. Existing method-redefinition fixture warnings and
+the gemspec's missing-homepage warning remain; no dependency or lockfile change
+is part of this feature.

data/docs/real-project-pilot.md

@@ -0,0 +1,84 @@
+# Real-project pilot: configuration lookup and adoption limits
+
+The first pilot demonstrated a useful test gap on an existing method, and exposed two concrete adoption limits. It did **not** produce three successful coverage integrations: one target was supported, and two representative targets were rejected. Luna agents performed discovery, used the exported skills, and independently reviewed the evidence. Original repositories were left unchanged.
+
+This records the implementation cut at commit `405883e`. The later [optional-argument continuation](optional-arguments-results.md) repeats the PStoreLogger candidate with a new collector and exported skills; the original rejected probe remains historical evidence.
+
+## Installation
+
+The development bundle now selects the correctly labeled published Minitest 5.26.2 release. The adapter supports `>= 5.26.2` and `< 5.28.0`, while continuing to reject package/runtime minor-version mismatches. See [package checksums and compatibility evidence](minitest-compatibility.md).
+
+The pilot used standard Bundler `vendor/bundle` installation, with the verified official package in `vendor/cache`. Sandbox restrictions prevented writing a global executable wrapper, and Bundler could not reach its index host; a normal `bundle install --local` from that package cache succeeded. No dependency source, runtime version constant, or global gem installation was changed. Core development checks use the existing published 5.26.2 installation; Ruby 3.3/3.4 verification used local bundles with ambient Ruby 4 gem paths cleared.
+
+Bundler loaded SpecProof from its cached path dependency. Every cached library file matched the pilot implementation by SHA-256; those hashes are in the pilot manifest. The retained archive excludes that generated cache and recreates it from `SPECPROOF_ROOT` during installation.
+
+## Three candidate methods
+
+| Existing method | Result | Consequence |
+| --- | --- | --- |
+| `QualityGate::Config#fetch(key)` | Supported. Eight shipped symbol keys form an explicitly scoped finite input domain. | Measure and close a gap in its existing configuration tests. |
+| `PStoreLogger#save(data, file_id: nil)` | Collector rejects the optional keyword with `unsupported_parameters`. | No coverage claim. The scalar signature-probe declaration is only a candidate subset of the broader PStore data domain. |
+| `Agent::SessionContext::SemanticCategories.lookup(identifier)` | Declaration rejects class-method syntax with `invalid_target`. | No coverage claim. Do not invent an instance-method wrapper to make the pilot pass. |
+
+The [rejected-candidate archive](pilots/2026-10-02/rejected/workspace.tar.gz) retains exact source files, source commits/hashes, original test references, the binding probe, command logs, and errors. The PStore probe used Ruby 3.4.7's standard library because `pstore` is no longer a default gem under Ruby 4; no new dependency was installed. The supported pilot used Ruby 4.0.1 throughout.
+
+Discovery also examined SimpleResult, the Minitest reporter, BranchProof, Agent Sessions, Agent Session Context, Agent ACL, and Guardrails for Rails. Many methods require optional parameters, class-method targets, strings, or structured objects outside the first release's supported subset. This was a bounded local survey, not proof that no suitable three-method project exists elsewhere.
+
+## QualityGate result
+
+Source revision: `8af0893de378cfd8076392d39b874f44987d818c`. All **143 copied project files** retain their original hashes. The pilot runs the unchanged `test/quality_gate/config_test.rb` file, not the whole QualityGate suite or its Rails/external-tool gates. The minimal pilot bundle loads this focused library/test slice without installing QualityGate's broader development dependencies.
+
+The domain includes all eight shipped `Config.defaults` keys. It excludes arbitrary hash keys and invalid configuration keys; 100% here means exercise of those eight scoped inputs only.
+
+| Run | Tests / assertions | Input obligations exercised |
+| --- | --- | --- |
+| Existing configuration tests | 45 / 342 | 7 / 8; `:files` unobserved |
+| Existing tests plus one added test | 46 / 350 | 8 / 8 |
+
+The added test compares `fetch` results with the exact shipped defaults. Its oracle is grounded in the existing test that asserts a default-loaded configuration's `to_h` equals `Config.defaults`. It makes eight assertions and includes obligation IDs and the original assertion location in failure messages. No production behavior was changed or defect invented; these assertions pass against the existing implementation.
+
+The fresh final report has a distinct run UUID, unchanged domain/digest and obligation IDs, positive hits for all eight values, and no unknown evidence or integrity errors. Read the [agent's detailed result](pilots/2026-10-02/quality_gate/RESULT.md), [specification](pilots/2026-10-02/quality_gate/config_fetch_spec.rb.txt), [added test](pilots/2026-10-02/quality_gate/config_fetch_added_test.rb.txt), [baseline report](pilots/2026-10-02/quality_gate/baseline-coverage.json), and [final report](pilots/2026-10-02/quality_gate/final-coverage.json).
+
+## Timing
+
+Five paired subprocess runs executed the **same original 45 tests and 342 assertions**, with no added tests, fixed seed 12345, and the adapter enabled only in the instrumented mode. Every instrumented report retained the same plan, exactly the original `:files` gap, completed integrity, and 27 observed selected-method calls. [Raw timings](pilots/2026-10-02/quality_gate/timings.json) and per-run logs/reports are retained.
+
+| Mode | Wall times, seconds | Median |
+| --- | --- | --- |
+| Baseline | 0.307118, 0.300959, 0.298459, 0.300013, 0.318318 | 0.300959 |
+| Instrumented | 0.326725, 0.338711, 0.328865, 0.353294, 0.341357 | 0.338711 |
+
+The median difference was about **38 ms (12.5%)** for this focused subprocess workload. Timings include Ruby/Bundler startup, requiring the adapter, collection, and report I/O. Baseline always ran first; five pairs do not establish a general overhead rate or isolate collector cost. They provide a reproducible comparison for this particular suite.
+
+## Reproduce
+
+The [supported workspace archive](pilots/2026-10-02/quality_gate/workspace.tar.gz) includes unchanged library/tests, license, Gemfile/lock, verified package cache, exported skills, added test, specification, runner, reports, and source hashes. It excludes the installed dependency directory. Unpack it into an empty directory, then use Ruby 3.3 or newer:
+
+```sh
+export SPECPROOF_ROOT=/absolute/path/to/gems/specproof
+bundle config set --local path vendor/bundle
+bundle install --local
+export MT_NO_PLUGINS=1
+export PILOT_PROJECT_ROOT="$PWD/project"
+export PILOT_SPECIFICATION="$PWD/config_fetch_spec.rb"
+export PILOT_REPORT="$PWD/fresh-coverage.json"
+PILOT_ADAPTER=1 PILOT_ADDED=1 bundle exec ruby pilot_runner.rb
+```
+
+From the SpecProof gem checkout, compare unchanged original tests with:
+
+```sh
+ruby script/benchmark_project_pilot.rb /absolute/path/to/unpacked/pilot 5
+```
+
+[The manifest](pilots/2026-10-02/manifest.json) records archive/file hashes and the exact updated skill bytes. The earlier twelve-scenario evaluations remain historical evidence for their original assets; this pilot is a separate fresh application of the updated instructions.
+
+The retained archive was also unpacked into a second empty directory and installed using `bundle install --local`. A fresh run there passed 46 tests and 350 assertions with 8/8 obligations exercised, confirming that reproduction works independently of the original pilot's installed dependency directory.
+
+## Next implementation slice
+
+Support **optional scalar positional and keyword parameters** next, while preserving the current directly owned instance-method scope. Define observations as effective bound argument values after Ruby applies defaults. Do not evaluate defaults statically, replay calls, or infer that an observed default value proves the argument was omitted.
+
+Before implementing, add TracePoint fixtures proving default evaluation timing, omitted versus explicit equal values, exceptions in default expressions, and unsupported non-primitive effective values. Preserve whole-tuple validation, shared IDs, and unknown evidence. Then rerun the PStoreLogger pilot on an explicitly declared primitive-data scenario subset with independent persistence assertions.
+
+Class-method targets, finite string domains, and richer object domains remain separate later decisions. This slice addresses an observed adoption barrier without taking on all of them at once.

data/docs/report-format.md

@@ -0,0 +1,244 @@
+# Report format
+
+Offline commands accept `--format json` and write one JSON document to standard output. Diagnostics and any output printed while evaluating the trusted specification file go to standard error. Human output is the default.
+
+Every document includes `schema_version` (`1`), `specproof_version`, `kind`, and `errors`. A check or plan configuration, usage, or I/O error keeps its requested `kind` and puts a stable `code`, explanatory `message`, and optional `path` and `source` in `errors`. An invalid command with no supported command kind uses `kind: "error"`. Every source object requires a file `path` and one-based `line`; schema 1 permits additional fields, and consumers must tolerate unknown source fields. The additive `kind` field identifies source provenance (for example, `dsl` or `rbs`) without changing existing fields or obligation identity.
+
+DSL targets may be canonical strings or supported Ruby method objects. Instance
+targets use `Owner#method`; class and module singleton targets use
+`Owner.method`. A directly defined public instance method can be selected with
+`Owner.instance_method(:method)`, and a directly defined public singleton
+method with `Owner.method(:method)`. Equivalent forms normalize to the same
+string target, contract digest, and obligation IDs. String targets remain
+unresolved during offline check and plan, so they do not load or autoload the
+owner. Method objects require the owner code to be loaded and are inspected
+through Ruby reflection without calling the target. They must still represent
+the current direct definition when declared. Aliases, inherited singleton
+methods, anonymous owners, and bound methods on arbitrary instances are
+unsupported; an unbound instance method identifies its defining class.
+Collection resolves each canonical name afresh when it starts and applies its
+existing method-identity and constant-binding guards. Reports retain the
+canonical string target. Navigation to source locations depends on editor and
+language-server support; the report makes no navigation guarantee.
+
+Check and plan results include `contract_digest`, a SHA-256 digest of normalized declarations, behavioral input domains, partition policies, and sorted explicitly excluded input names. Exclusion reason, source location, and declaration order do not change the digest. With no exclusions, existing digests and criterion/obligation IDs remain unchanged. Source locations are excluded from this digest. For composed DSL/RBS declarations, the digest fingerprints the resulting behavioral input domains: broader type constraints, provenance, RBS text, parser version, and implementation behavior do not change it. Obtain a fresh runtime report after changing a source or implementation; matching digests establish the same analyzed input obligations and excluded names, not that a particular implementation is correct. Check results include `findings`, each with a semantic `code`, target and input names, a concrete `witness`, and source locations. Findings never appear in `errors`.
+
+The DSL options `allow_gaps` and `allow_overlaps` default to `true`; `false`
+requires coverage of the whole input domain or prevents partition overlaps,
+respectively. Legacy `exhaustive` and `disjoint` spellings remain accepted with
+inverted booleans. Equivalent spellings normalize to the same policies and
+preserve digests and obligation IDs; no report schema change is required.
+Supplying both spellings of one policy is a `duplicate_partition_policy`
+configuration error, even when their values express the same requirement.
+
+Successful check, plan, and runtime coverage documents share a `scope` object
+with `completeness_scope: "analyzed_inputs"` and `input_scope`. Each input
+scope entry identifies one target, its `analyzed_inputs` names, and its
+`excluded_inputs`, each containing a parameter `name`, a human-readable
+`reason`, and declaration `source` (`path`, one-based `line`, and `kind`). An
+excluded name is part of the contract identity; its reason and source are
+reported for review but do not change identity. Default scope is strict: every
+named runtime parameter must be analyzed or explicitly excluded, and at least
+one must be analyzed. Check/plan scope describes the requested declaration;
+it does not attest runtime binding or test execution.
+
+Plan results default to `criterion: "input-basics-v1"` and include `obligations`. Each scalar obligation has a stable `id`, target, input, typed value, merged reasons, and source locations. Values have a `kind`: integer values are decimal strings, symbols are names, booleans are JSON booleans, nil has a JSON null value, and finite strings use `{ "kind": "string", "value": "..." }`. String values are exact text snapshots. This is an additive value kind under schema version 1; consumers must handle it explicitly and tolerate it wherever typed primitive values occur, including witnesses and coverage rows. Strings and same-spelling symbols have distinct identities. Finite string values are deduplicated and ordered deterministically after existing scalar types. Existing nonstring IDs and digests remain unchanged. Existing partition membership, gap, and overlap checks apply to the explicitly enumerated string scenario. Scalar candidates are marginal inputs and do not specify expected method results or form a complete test suite.
+
+## Pairwise finite criterion
+
+Pairwise planning is opt-in. The Ruby API accepts
+`SpecProof.plan(..., criterion: "pairwise-finite-v1")`; the CLI accepts
+`specproof plan PATH --criterion pairwise-finite-v1`; the Minitest adapter
+accepts `criterion: "pairwise-finite-v1"`. The default remains
+`input-basics-v1`. `check` is criterion-independent and rejects `--criterion`.
+A pairwise plan requires a valid `combinations` group for every supplied target;
+it never skips a target that lacks a group.
+
+Each target has at most one group over at least two distinct analyzed finite
+inputs. Select either `all_allowed: true` with no block, or a nonempty block of
+explicit `forbid` assignments. `all_allowed: true` declares that every tuple
+is allowed; it is not evidence that inputs have independent effects. A
+`forbid` clause must be justified by a stated requirement. Clauses are
+conjunctive within a tuple and a tuple is forbidden if any clause matches.
+Partial clauses restrict every completion. They are declarative data and do
+not execute predicates. A forbidden tuple can still contain individually
+feasible pairs when a third input differs; pair feasibility is determined by
+whether the pair has an allowed full group completion.
+
+Pairwise plan and runtime rows share `id`, `target`, `reasons`, `sources`,
+`status`, and `hits`, and serialize their two assignments in `inputs` as a
+name-to-typed-value object. Pair names are sorted canonically, while value
+types remain significant; strings and same-spelling symbols are distinct.
+Pairs excluded because no allowed full assignment completes them appear in
+`excluded_pairs`, with `target`, typed `inputs`,
+`reason: "no_allowed_completion"`, and relevant constraint sources. Excluded
+pairs are not denominator rows. Do not remove a missing required pair by
+adding a forbidden rule: the rule must come from an independent requirement.
+
+Pairwise planning bounds each target to 10,000 full group assignments and
+10,000 possible pair rows, and bounds all planned pair obligations to 10,000.
+Oversized spaces fail with `combination_limit_exceeded`; SpecProof does not
+sample or truncate. A valid declaration whose restrictions leave no allowed
+full assignment produces the semantic finding `unsatisfiable_combinations`
+and no plan. Malformed declarations are configuration errors. Pairwise
+coverage counts only fully valid analyzed tuples; a forbidden runtime tuple
+fulfills no pair obligations and is reported in the existing outside-domain
+evidence with the added `outside_combinations` evidence. Selected inputs must
+all be valid even when the combination group covers only a subset. Excluded
+runtime inputs remain outside the claim, including any behavior involving
+their values.
+
+## Pairwise partition criterion
+
+`pairwise-partitions-v1` is a separate explicit criterion. It requires a
+`combinations` group for every target. Each grouped integer input must have a
+bounded range declared `allow_gaps: false` and `allow_overlaps: false`, with
+explicit partitions. Other grouped inputs use finite values as singleton
+categories. A group may declare `all_allowed: true`, or give a nonempty block
+of requirement-backed `forbid` assignments. The default scalar criterion and
+`pairwise-finite-v1` keep their existing behavior.
+
+For a restricted group, `in_partition(:name)` selects an entire declared
+integer partition. Exact finite values select singleton categories. A clause
+is a partial assignment: it forbids each matching full assignment, and a tuple
+is forbidden when any clause matches. Integer restrictions cannot name raw
+integer values or partial ranges; selectors must refer to known partitions.
+The selector is distinct from a literal symbol and from a bounded
+`PartitionLevel`. Finite-valued inputs continue to require exact values.
+Clauses are requirement data, never executable predicates.
+
+Plan and runtime pair rows use the same `inputs` structure as finite pairwise
+rows. Integer categories serialize as
+`{ "kind": "partition", "name": "minor", "lower": "0", "upper": "17" }`;
+the reported bounds are inclusive. Finite values retain their ordinary typed
+form. Pair IDs include the criterion and category identity and bounds. Coverage
+counts a call when its integer value belongs to the planned category in the
+same fully valid tuple. It does not count as exact-value or boundary coverage,
+and it does not claim equivalent behavior within a category.
+
+In a constrained plan, `excluded_pairs` contains category pairs with no
+allowed full completion and `reason: "no_allowed_completion"`. Check all group
+inputs when interpreting feasibility: a restriction on a third input can
+make a pair impossible even when no single clause names both pair members.
+Excluded pairs are outside the required denominator. At runtime, a call that
+matches a forbidden assignment contributes no pair coverage, including pairs
+that would otherwise be valid in some other full assignment. The normalized
+constraint value used for the contract digest encodes a typed restriction
+selector as
+`{ "kind": "partition_reference", "name": "minor" }`; this is separate
+from the existing `{ "kind": "partition", ... }` obligation encoding.
+
+CLI `suggest` infers this criterion from a valid, checked coverage report; its
+command continues to reject `--criterion`. Suggested category assignments
+replace each partition object with a concrete integer at that partition's
+lower endpoint. That value is a representative call input only. The output
+uses `strategy: "greedy-partition-pairwise-v1"`; it supplies no expected
+result or behavior rule.
+
+Finite string support is feature-specific, not guaranteed by a `0.1.x` version number. Check a fresh plan from the installed build for typed string obligations before relying on the kind. A finite string declaration enumerates scenario values and does not represent the full String domain. Only exact String instances with valid UTF-8 or US-ASCII encoding are supported; US-ASCII is canonicalized to UTF-8. Empty strings, whitespace, Unicode, and embedded NUL are valid text. Invalid byte sequences, other encodings, and String subclasses are rejected. No trimming, case folding, or Unicode normalization is applied. Declaration values and observed values are copied into frozen SpecProof-owned snapshots. The entry snapshot is used for matching even if the method mutates its argument, and direct Coverage observation also owns retained strings. A bounded outside-domain witness count does not bound witness bytes: a retained string witness is the full immutable string.
+
+For a target also selected from RBS, DSL refinements must name parameters in
+that selected signature. An extra DSL input produces configuration error
+`rbs_input_mismatch`, with its DSL source and the RBS location in the message;
+check/plan exit 2 without a successful partial plan. Unselected DSL-only targets
+remain valid. RBS string literals, finite unions of supported string literals,
+and optional string-literal forms import exact finite string scenarios without
+duplicate DSL inputs. Same-spelling strings and symbols remain distinct.
+Unrestricted `String` and selected unions with unsupported members fail
+atomically. RBS return types are ignored; this checks input declaration names,
+not Ruby arity/order or output conformance.
+
+Finding witnesses use the same tagged primitive values, including the string kind above. Integer gap and containment witnesses are an array of two tagged integers denoting inclusive lower and upper bounds. Overlap witnesses are one tagged primitive. An empty-domain witness is either an empty finite array or the normalized, inverted integer bounds. For example, a gap from 65 through 120 is `[{"kind":"integer","value":"65"},{"kind":"integer","value":"120"}]`. Human reports quote and escape string values; other values retain ordinary Ruby notation.
+
+`specproof skills export --to DIRECTORY --format json` results use `kind: "skills_export"` and add the expanded `destination` plus sorted `exported` and `unchanged` path arrays. The exporter requires an explicit destination and does not modify client or global configuration. A conflict is reported under `errors` before new files are copied.
+
+Exit status is `0` for a successful command, `1` for semantic findings, and `2` for malformed configuration, unsupported options, usage errors, or I/O failures. A plan with semantic findings contains no obligations and returns status `1`.
+
+## Minitest coverage
+
+The optional adapter writes a JSON file with `kind: "coverage"` and prints a summary containing the same `run_id`. A successful report is evidence for that run only. Its contract digest does not fingerprint the implementation or tests; obtain a new run after either changes.
+
+| Field | Meaning |
+| --- | --- |
+| `contract_digest`, `criterion` | Current normalized specification and selected input criterion (`input-basics-v1`, `pairwise-finite-v1`, or `pairwise-partitions-v1`); compare with a current plan |
+| `scope.completeness_scope`, `scope.input_scope` | Declared input scope: analyzed parameter names plus explicitly excluded names and their reasons/sources |
+| `run_id` | Fresh UUID for the invocation, also printed in its summary |
+| `completion` | `running`, `completed`, or `incomplete` |
+| `integrity` | Whether collection and reporting completed without a known integrity failure |
+| `tests_passed` | Original Minitest result; `null` before a result or when the runner aborts |
+| `obligations` | Planned obligations plus `status` and integer `hits` counters |
+| `missing`, `exercised` | Projections of the corresponding obligation rows |
+| `exercised_count`, `missing_count`, `unknown_count`, `not_observed_count`, `obligation_count` | Counts over the fixed planned denominator |
+| `completion_percent` | Percentage of exercised obligations for an intact observed run, including partial coverage; `null` when collection is incomplete or no target call was observed |
+| `outside_domain` | Per-target count and at most one typed primitive tuple witness (including string values), or an `invalid_tuple` marker; these calls fulfill no valid-input obligations |
+| `outside_combinations`, `excluded_pairs` | Jointly forbidden runtime tuple evidence and plan pairs with no allowed full completion; excluded pairs are outside the denominator |
+| `incomplete_reasons`, `errors` | Bounded diagnostics explaining missing integrity or unsupported collection |
+| `evidence_mode`, `replay` | `obligation_hits` and `false`; no full event trace is retained |
+
+An obligation is `exercised` when a valid analyzed-input tuple supplied its candidate value or category; `not_observed` when collection was intact but no such tuple was seen; or `unknown` when an integrity limitation prevents concluding absence. For partition rows, an observed integer exercises a category when it falls within the category's inclusive bounds. Positive hits remain positive after an integrity failure, but unhit affected obligations become unknown. The `missing` array contains only `not_observed` rows. Every analyzed input in a call must satisfy its domain before any candidate from that call counts. Explicitly excluded values are outside the tuple and are never read by the collector; their values and behavior are not covered. An analyzed non-primitive value still makes collection incomplete. The collector does not silently drop undeclared parameter fields to make a tuple count: declaration names must account for the selected target's complete named runtime signature, split only between analyzed and explicitly excluded inputs.
+
+Runtime `scope.targets` lists every target in the composed contract, and runtime `scope.declaration_sources` records the supplied declaration inputs as `{ "specifications": [...], "rbs": [...], "targets": [...] }`: canonical DSL and RBS paths, plus explicitly selected RBS targets. These runtime-only invocation fields do not attest that expected test files were loaded. Runtime scope also includes the shared `completeness_scope` and `input_scope` fields described above, plus the Ruby engine, process ID, run thread identity, run arguments, recognized inclusion `filter` and `exclude` patterns, `window: "minitest_run"`, and `method_identity: "direct_owner_definition"`. It records `input_semantics: "effective_bound_values"` and `argument_presence: "not_observed"`. Inspect the original arguments as well as the pattern summaries before treating the invocation as the intended full suite; patterns do not attest which test files the caller loaded. Reports apply to the current process, selected thread, and Minitest run window. They do not merge child-process or child-thread activity or identify individual tests.
+
+`SpecProof::Minitest.install!` accepts the same optional `rbs:` and `targets:` inputs as `SpecProof.load`. A RBS-only setup may pass `specifications: []` when it supplies both a non-empty RBS path list and selected targets. File, parser, and type validation happens during run preparation so failures produce an incomplete report while the original Minitest result remains available in `tests_passed`. Empty RBS options preserve DSL-only behavior.
+
+Named required and optional positional/keyword parameters are supported when every parameter is either an analyzed `input` declaration or an explicit `exclude_input` with a reason, and at least one parameter remains analyzed. Entry observations contain effective analyzed values after Ruby applies defaults. Omitted and explicitly supplied equal values exercise the same obligation; neither a hit nor its count establishes argument omission. The collector does not evaluate defaults, retain call-site argument presence, or add omission-specific obligations. Defaults that raise before entry yield no target entry evidence and preserve Ruby's exception. Defaults calling another selected method can contribute that other method's own entry observations within scope. A non-primitive analyzed value makes collection incomplete; primitive analyzed values outside a declared domain invalidate the entire analyzed tuple. Excluded values are not read. Rest, keyword-rest, forwarding, and explicit block parameters remain unsupported.
+
+Method identity is the selected owner's directly defined public Ruby instance or singleton method, resolved by canonical name before observation begins. Calls through aliases of that same definition count. A subclass override contributes to an instance target only when it executes the selected definition through `super`; a distinct override does not count merely because its method name matches. Aliased or inherited target declarations, unsupported signatures, and unresolved/autoloaded target owners fail binding. Two target names resolving to the same owner and method fail with `duplicate_binding`. Observed redefinition invalidates collection. Removing, rebinding, or replacing the selected constant path with an autoload at the end of collection produces `target_binding_changed`; previously observed hits remain, and unobserved obligations become unknown. Constant bindings must remain stable during the run; transient changes restored before final inspection are outside this guarantee. Supported runtime compatibility is CRuby 3.3, 3.4, and 4.0 with Minitest >= 5.26.2 and < 5.28.0, requiring matching package/runtime major and minor versions.
+
+Before collection, the adapter atomically replaces any previous report with a marker for the new run, `completion: "running"`, `integrity: false`, and `tests_passed: null`. Finalization replaces it with the new run's final report. An interrupted run cannot leave an old successful report presented as current evidence. A report-write failure fails the adapter run and prints a diagnostic; a leftover running marker remains insufficient evidence.
+
+Missing input obligations are informational by default. Strict missing mode can make the process fail even when `tests_passed` is true, because that field preserves the original assertion result. Assertion failures remain failures in either mode; collector/configuration integrity failures also fail the invocation. Input hits and assertion results are separate evidence: 100% input coverage does not establish behavioral correctness.
+
+## Pairwise suggestions
+
+`specproof suggest PATH --report FILE --format json` reads exactly one
+completed coverage report and infers its criterion from that checked report.
+It uses `greedy-pairwise-v1` for `pairwise-finite-v1` and
+`greedy-partition-pairwise-v1` for `pairwise-partitions-v1`. It accepts the same optional `--rbs FILE` and
+`--target TARGET` selectors as the other declaration commands. `--criterion`
+is rejected because suggestions are defined only for pairwise reports.
+Suggestions replan the supplied current declarations and validate the report
+against the current contract digest, exact typed obligation denominator,
+declared input scope, and consistent counters and projections. The source
+report must have schema 1, kind `coverage`, completed and intact collection,
+empty errors and incomplete reasons, zero unknown observations, and a Boolean
+`tests_passed`. A false `tests_passed` value is accepted and preserved; it
+records the original Minitest assertion result independently of coverage.
+Filtered reports are accepted for their recorded scope. The output preserves
+`source_run_id`, `source_tests_passed`, and `source_scope`; this does not make a
+filtered run a full-suite claim.
+
+The JSON suggestion document has schema 1, kind `suggestions`, no errors,
+and records the criterion and strategy selected from its source report, plus
+`assignment_scope: "combination_group"` and
+`minimality: "not_guaranteed"`. It includes the current `contract_digest`,
+source provenance and scope, and `missing_obligation_count`,
+`covered_obligation_count`, and `suggestion_count`. Each suggestion row has a
+stable `id`, `target`, a full typed `inputs` assignment for its combination
+group, `covers` containing only newly covered missing obligation IDs,
+`unassigned_inputs`, and source locations. The union of `covers` is exactly
+the source report's missing set. Inputs outside a combination group and
+explicitly excluded inputs appear in `unassigned_inputs`; the caller must
+supply them. Every analyzed runtime input, including those names, must still
+be valid for a call to count.
+
+For partition rows, source obligations contain the typed category name and
+inclusive bounds; suggestion `inputs` instead contain the lower-endpoint
+integer representative. Do not interpret a category hit as a boundary test or
+as evidence that all values in the category share behavior.
+
+Suggestions are unexecuted test inputs and contain no expected outputs. Use an
+independent requirement as the assertion oracle, and never derive expected
+values from the implementation or the suggestions. Do not copy a candidate
+into a test without adding a meaningful assertion. A passing pairwise report
+or a union of suggested pairs is evidence only for the declared pair or
+category obligations and assertions; it is not exhaustive full-tuple coverage.
+The contract digest does not fingerprint
+implementation or test bytes, so rerun the intended test suite in a fresh
+process after either changes and inspect its new run ID and test result.
+
+Suggestion generation is deterministic but greedy; it does not promise a
+minimum number of assignments. It rejects work exceeding 10,000 cumulative
+full assignments, 10,000 cumulative possible pair rows, 1,000,000 candidate
+to missing-pair memberships, or a 32 MiB coverage report. It does not sample,
+truncate, or emit partial results. CLI report reads are bounded to that size.

data/examples/age_policy/README.md

@@ -0,0 +1,39 @@
+# An input gap that hides a boundary defect
+
+For this demonstration the accepted domain is integer ages `0..120`, and the
+intended rule is that an age of **18 or greater is adult**. That independent
+rule supplies the assertion oracle. The input specification partitions ages
+into minor (`0...18`) and adult (`18..120`); it does not declare return values.
+
+Run these commands from the gem root with its development bundle and a
+supported Minitest installation (the development bundle selects 5.26.2):
+
+```sh
+bundle exec specproof check examples/age_policy/specification.rb --format json
+bundle exec specproof plan examples/age_policy/specification.rb --format json
+bundle exec ruby examples/age_policy/run.rb missing
+bundle exec ruby examples/age_policy/run.rb regression
+bundle exec ruby examples/age_policy/run.rb correct
+```
+
+The plan proposes `0`, `1`, `17`, `18`, `119`, and `120`. The `missing` mode
+runs the existing five non-boundary assertions against the faulty `age > 18`
+implementation. The tests pass; the report identifies age 18 as unobserved.
+
+The `regression` mode adds the explicit intended assertion for age 18. This
+command intentionally exits unsuccessfully: its assertion fails against the
+same faulty implementation. Age 18 is now exercised even though the behavior
+is wrong, illustrating why input coverage and correctness are separate.
+
+The `correct` mode runs all six assertions against `age >= 18`. The tests
+pass and all six obligations are exercised. These are separate subprocesses,
+so their alternative `AgePolicy` definitions never coexist in one run.
+
+Each mode writes a fresh report to `tmp/age-policy-MODE.json`. An optional
+second argument selects another report path. Match its `run_id` with the
+printed summary and compare its contract digest with the current plan.
+`SPECPROOF_STRICT=1` enables missing-obligation failure for this example;
+it leaves the underlying assertion result visible in `tests_passed`.
+
+The deterministic acceptance tests in `test/workflow_test.rb` execute this
+same runner, including the intentionally failing mode, as subprocesses.

data/examples/age_policy/faulty/lib/age_policy.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Deliberately faulty implementation for the missing-boundary example.
+class AgePolicy
+  # Deliberately wrong: the declared adult partition begins at 18.
+  def adult?(age)
+    age > 18
+  end
+end

data/examples/age_policy/faulty/test/age_policy_examples_test.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../lib/age_policy"
+
+# Shows the faulty policy passing its non-boundary examples.
+class AgePolicyExamplesTest < Minitest::Test
+  def test_adult_examples_without_the_boundary
+    policy = AgePolicy.new
+
+    refute policy.adult?(0)
+    refute policy.adult?(1)
+    refute policy.adult?(17)
+    assert policy.adult?(119)
+    assert policy.adult?(120)
+  end
+end

data/examples/age_policy/faulty/test/age_policy_test.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "../lib/age_policy"
+
+# Demonstrates how the explicit age boundary assertion catches the defect.
+class AgePolicyTest < Minitest::Test
+  def test_adult_examples_without_the_boundary
+    policy = AgePolicy.new
+
+    refute policy.adult?(0)
+    refute policy.adult?(1)
+    refute policy.adult?(17)
+    assert policy.adult?(119)
+    assert policy.adult?(120)
+  end
+
+  def test_explicit_boundary_requirement
+    assert AgePolicy.new.adult?(18)
+  end
+end

data/examples/age_policy/lib/age_policy.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Example age policy whose adult boundary begins at 18.
+class AgePolicy
+  def adult?(age)
+    age >= 18
+  end
+end