specproof 0.1.0

data/docs/input-selection-results.md

@@ -0,0 +1,123 @@
+# Explicit input selection results
+
+The [approved implementation plan](superpowers/plans/2026-10-03-input-selection.md)
+is implemented on `implement/input-selection`, based on the completed RBS branch.
+Core implementation commit: `23d6966`; documentation and skills: `33b8634`. Work is isolated in
+`tmp/worktrees/input-selection`; the original checkout and RBS worktree are
+unchanged. No publication or merge is included.
+
+## Delivered behavior
+
+```ruby
+SpecProof.define "PStoreLogger#save" do
+  exclude_input :data, reason: "Payload contents are outside this nil/1 file-ID scenario coverage"
+  input :file_id, values: [nil, 1]
+end
+```
+
+The collector checks that analyzed and explicitly excluded names together
+exactly match the selected method's named parameters. It reads only analyzed
+bindings. Excluded Hash or object values therefore do not invalidate scalar
+collection; unsupported analyzed values still do. A missing declaration, typo,
+or newly added parameter cannot silently become an exclusion.
+
+Exclusions require a name, nonblank reason, and declaration source. A target
+must retain at least one analyzed input. Default specifications remain strict.
+Existing method-shape, redefinition, constant-binding and collection-lifecycle
+checks remain in force. Tests still run when collection cannot prepare, and
+their actual result is reported separately from collection integrity.
+
+RBS can import remaining finite inputs from an exclusions-only DSL declaration.
+The reader validates the complete selected signature before skipping excluded
+types. Unsupported analyzed types and union members still fail atomically.
+Review found and fixed an edge case where excluding every RBS argument could
+otherwise let a nonexistent DSL input reach planning.
+
+Offline check/plan and runtime reports share `scope.completeness_scope` and
+`scope.input_scope`, including analyzed names and excluded names/reasons/sources.
+Human output discloses exclusions. Sorted excluded names affect the contract
+digest; reason text and provenance do not. Legacy no-exclusion digest bytes,
+criterion, and per-input obligation IDs remain unchanged. Compare scope and
+digest as well as IDs when consuming reports.
+
+## Changes and simplifications
+
+- `lib/specproof/{model,loader,composer,collector,report,minitest,cli}.rb`:
+  declaration-owned exclusions, selected binding reads, shared reporting.
+- `lib/specproof.rb` and `lib/specproof/sources/{rbs,rbs_projector}.rb`:
+  full-signature validation followed by deliberate type projection. Removed
+  duplicate name validation from the public loader.
+- `sig/specproof.rbs` and focused loader/composer/collector/report/RBS workflow
+  tests: API metadata and regression coverage.
+- `skills/specproof-{specify,test-gaps}/`, README and report documentation:
+  scoped adoption, valid baseline collection, preserved test-only boundaries,
+  and honest failure reporting.
+- [Runnable example](../examples/input_selection/README.md): ordinary Hash
+  payloads, an analyzed boolean, and independently specified assertions.
+
+Selection travels with the existing specification; there are no separate CLI
+or Minitest selection options to synchronize. The planner and coverage tuple
+validation are reused. No dependency or new domain kind was added; core runtime
+dependencies remain zero.
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| CRuby 3.3.6 / 3.4.7 / 4.0.1 | Each: 166 core tests, 822 assertions; 46 optional RBS tests, 425 assertions; zero failures, errors or skips |
+| Locked default Ruby 4 bundle | `bundle exec rake` passed; RuboCop 1.90 inspected 98 files without offenses |
+| Package checks | `bin/check` passed syntax, installed-package and skill checks: 2 tests, 76 assertions; real gem built |
+| API signatures | RBS 4.2.0 validation passed on all three Ruby versions |
+| Shipped example | 4 tests / 4 assertions pass; both selected boolean obligations exercised |
+| Independent reviews | Luna specification and quality reviews approved core and documentation after fixes |
+
+[Raw matrix records](pilots/input-selection/matrix/) retain commands, versions,
+outputs, exit statuses and library hashes. These runs recorded the actual
+pre-commit working-tree state at `7222d96`; their 17 library hashes match the
+committed implementation. Provenance records were not rewritten after commit.
+
+Independent audit records cover the [pilot](pilots/input-selection/audit/pilot.json),
+[matrix](pilots/input-selection/audit/matrix.json), and
+[agent evaluation artifacts](evaluations/artifacts/input-selection/independent-final-audit.json).
+
+## Existing-project adoption
+
+The [PStoreLogger pilot](pilots/input-selection/README.md) uses its unchanged
+source at `959e37410bac42ba47e43ee8da006ce9550d9f50`. The same ordinary Hash-based
+suite passes both before and after instrumentation: **7 tests, 23 assertions**.
+The selected `file_id` scenario covers `nil` and integer `1`; both obligations
+are exercised, with intact collection and matching offline/runtime IDs and
+digest. The five copied source/test files retain their original hashes.
+
+This is a finite scenario subset, not the complete accepted file-ID domain.
+PStoreLogger also documents string IDs, which this milestone does not model.
+No additional test or coverage gap was invented for this adoption result.
+
+## Agent workflow evidence
+
+The [evaluation record](evaluations/input-selection-agent-skills.md) preserves
+the old-skill baseline, initial attempts, corrections, and fresh repeats using
+the installed gem's exported skills. The first attempts exposed an invalid
+baseline collected before its specification existed and an unauthorized
+production fix in a test-only task. Both attempts remain visible.
+
+After guidance corrections, a fresh scoped-adoption actor imported its boolean
+from RBS, recorded a valid 1/2 baseline, and added an independently justified
+assertion to reach a fresh passing 2/2 report. A fresh pressure actor preserved
+the declared scope and production code, added a failing regression, and
+reported the defect: **4/4 obligations exercised, `tests_passed: false`**.
+Coverage and passing assertions are separate evidence.
+
+These are small guided scenarios with supplied requirements, selectors and a
+command recorder. They do not establish general agent reliability or automatic
+client skill discovery.
+
+## Limits
+
+Complete collection and 100% exercise apply only to analyzed marginal input
+obligations. Excluded arguments may affect behavior; an exclusion reason does
+not prove that they are irrelevant. This feature does not analyze outputs,
+assertion adequacy, combinations, arbitrary objects, strings, argument omission
+or additional method shapes. Existing serial collection and RBS 4.2.0 limits
+remain. Obtain fresh runtime evidence after changes even when IDs and digest
+match an older report.

data/docs/lint-cleanup-plan.md

@@ -0,0 +1,12 @@
+# Lint cleanup plan
+
+The implemented behavior is protected by the 102-test suite, including runtime and installed-package checks. Repository-wide RuboCop currently reports style and complexity offenses against the Bundler scaffold's defaults.
+
+1. Run the existing RuboCop dependency with a writable cache and without parallel workers; collect the actual offense inventory.
+2. Apply only safe style corrections, keeping the public API, report schema, and runtime behavior intact.
+3. Treat test/fixture blocks separately from production complexity. `.rubocop.yml` excludes Metrics only under `test/**/*`, `spec/**/*`, and `benchmark/**/*`: cohesive test scenarios and benchmark support are not useful production complexity signals. Production Metrics remain enabled without per-file exclusions.
+4. Set explicit initial project budgets after reviewing the actual inventory: ABC 60, cyclomatic/perceived complexity 20, method length 60, class length 250, module length 200, and block length 40. These replace scaffold defaults, including the ten-line method limit, which would fragment the interval sweep and sequential method-binding checks without changing their responsibilities. An independent Luna review found these algorithms cohesive and supported the budgets; the collector binding validator remains near the limits and should be monitored. These budgets are an initial policy, not evidence that complexity has disappeared.
+5. Extract the oversized CLI dispatcher into separate check, plan, and skill-export flows with shared error handling. Preserve command behavior through the existing CLI acceptance tests; add regression tests for any behavior fixes.
+6. Re-run affected tests after edits, then the complete suite, syntax/package checks, and RuboCop. Add no dependencies.
+
+Ownership is limited to Ruby style corrections, existing `.rubocop.yml`, and this verification record. Agent evaluation projects in `/private/tmp` are independent evidence and must remain untouched.

data/docs/method-targets-results.md

@@ -0,0 +1,68 @@
+# Method target support: verification
+
+String declarations and Ruby method objects now share canonical target names:
+`Owner#method` for instance methods and `Owner.method` for class/module
+singleton methods. Equivalent declarations have matching contract digests
+and obligation IDs. Strings remain usable without loading application code;
+method objects require loaded code and a current public Ruby definition.
+
+The [runnable example](../examples/method_targets/README.md) produces eight
+matching target/obligation identities from its string and method-object forms.
+The input contract does not capture return values, execute the target during
+normalization, or promise editor navigation. Collection resolves the canonical
+name when it starts, rather than pinning the declaration's method object.
+
+Luna subagents implemented target normalization, singleton collection, RBS
+projection, documentation and agent skills. Independent specification and
+quality reviews found no remaining blockers.
+
+## Verification
+
+On each of CRuby 3.3.6, 3.4.7 and 4.0.1:
+
+| Suite | Tests | Assertions |
+| --- | ---: | ---: |
+| Core | 324 | 1,666 |
+| Optional RBS | 60 | 537 |
+
+All passed without failures, errors or skips. RBS signature validation,
+RuboCop (151 files), syntax, packaged skill checks and gem building passed.
+Tests cover equivalent declarations, separate same-named instance/singleton
+targets, optional and excluded arguments, aliases called through the selected
+definition, stale method objects, invalid owners, source-aware errors,
+redefinition, constant binding changes and RBS singleton declarations.
+
+## Real-project continuation
+
+The earlier [pilot](real-project-pilot.md) rejected
+`Agent::SessionContext::SemanticCategories.lookup(identifier)` because class
+methods were unsupported. A new Luna exercise used the unchanged method and
+the candidate's unchanged `SummaryParserTest` file with both target forms.
+
+Both declarations passed check and plan, with the same twelve obligations and
+digest `2446066802513c19caee861f0c2d7b607559fcf72e0f3359fa862044292c8ea2`.
+The domain was explicitly scoped to six strings and six symbols from the
+existing catalog assertion, not arbitrary string inputs.
+
+The normal test helper could not load the unrelated `agent_sessions`
+dependency from the prepared bundle. A scratch-only helper loaded the parser's
+local supporting classes without wrapping or changing the selected method.
+Each form then passed the same twelve tests and 110 assertions. Both reports
+were completed and intact, with identical scope and hit projections: seven
+exercised inputs, five missing and zero unknown. No dependencies were installed
+and no application files were edited. This demonstrates the focused test file,
+not the application's full suite under its normal helper.
+
+The missing symbols were `:constraint`, `:decision`, `:next_action`,
+`:open_question` and `:term`. The agent left them untested rather than deriving
+expected lookup results from implementation code. This exercise followed the
+updated source-checkout skills; it was not an installed-gem evaluation.
+
+## Limits
+
+Direct public instance methods require a named class; singleton methods may
+belong to a named class or module. Arbitrary bound instance methods, anonymous
+owners, aliased declarations, inherited singleton declarations and native
+methods are rejected. An UnboundMethod identifies its defining class, including
+when obtained by reflecting through a subclass. RBS selection still uses
+explicit string targets and its existing supported type subset.

data/docs/minitest-compatibility.md

@@ -0,0 +1,33 @@
+# Reproducible Minitest installation
+
+The optional adapter accepts Minitest `>= 5.26.2` and `< 5.28.0`. Both the activated gem metadata and `Minitest::VERSION` must be in that range, with matching major and minor versions. The lower bound excludes untested 5.26.0 and 5.26.1; the upper bound excludes untested later interfaces.
+
+The development and pilot bundles select `~> 5.26.2`. An ordinary bundle uses the existing RubyGems dependency without a source rebuild, a runtime version patch, or an alternate GEM_HOME:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec ruby -rminitest -e 'puts Gem.loaded_specs.fetch("minitest").version; puts Minitest::VERSION'
+```
+
+Use Ruby 3.3 or newer for these commands. The last command reports `5.26.2` twice with the checked-in lockfile.
+
+## Observed package mismatch
+
+On 2026-10-02, a fresh download from [RubyGems' Minitest 5.27.0 package](https://rubygems.org/downloads/minitest-5.27.0.gem) matched the SHA-256 in its [published metadata](https://rubygems.org/api/v2/rubygems/minitest/versions/5.27.0.json):
+
+`2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5`
+
+Its gem metadata says `5.27.0`, but the extracted `lib/minitest.rb` defines `VERSION = "5.26.2"`. This observation concerns the published artifact downloaded on that date; the [upstream v5.27.0 source](https://github.com/minitest/minitest/blob/v5.27.0/lib/minitest.rb) declares `5.27.0`. Reinstalling the same artifact preserves the mismatch. SpecProof continues to reject it.
+
+A fresh [5.26.2 package](https://rubygems.org/downloads/minitest-5.26.2.gem) matched its [published metadata](https://rubygems.org/api/v2/rubygems/minitest/versions/5.26.2.json):
+
+`f021118a6185b9ba9f5af71f2ba103ad770c75afde9f2ab8da512677c550cde3`
+
+That package's metadata and extracted runtime both identify `5.26.2`. Its `lib/minitest.rb` also matches the existing local installation by SHA-256. No dependency source or global gem installation was modified.
+
+## Validation and historical evidence
+
+New integration tests exercise genuine 5.26.2 and reject the mislabeled 5.27/5.26 pairing, the reverse pairing, versions below the lower bound, 5.28.0, and 6.0.0. The original 5.27 source-tag validation and retained skill evaluations remain historical evidence; they were not rewritten to claim that the mismatched published artifact passed.
+
+Compatibility changes do not alter the criterion, obligation IDs, JSON schema, collector scope, or the distinction between input exercise and behavioral correctness.

data/docs/optional-arguments-plan.md

@@ -0,0 +1,25 @@
+# Optional scalar arguments
+
+Approved continuation after the real-project pilot: observe effective Ruby-bound optional positional and keyword values, then repeat the PStoreLogger primitive-scenario pilot.
+
+## Contract
+
+- Support named required/optional positional and keyword parameters. Every parameter must still have an input declaration.
+- Capture effective values at Ruby method entry. Do not inspect or execute default expressions, infer omission, add omission-specific obligations, or change existing IDs/criterion.
+- Preserve rejection of rest, keyword-rest, forwarding, explicit blocks, class-method targets, inherited/aliased declarations, and non-primitive observed tuples.
+- A default that raises before method entry supplies no entry observation. Ruby's original exception and side effects remain unchanged.
+- A non-primitive effective value keeps collection incomplete; a primitive value outside its declared domain contributes no valid tuple hits.
+- Reports explicitly identify effective bound values and unavailable argument-presence evidence. This is additive metadata under schema 1.
+
+## Implementation and acceptance
+
+1. Prove TracePoint default timing and side effects with failing collector tests before widening the parameter allowlist. Cover mixed signatures, dependent defaults, omitted/explicit equal values, raising defaults, non-primitive defaults, and unsupported signatures.
+2. Add optional-argument Minitest subprocess integration: stable shared obligations, repeated nil hits from omission and explicit nil, preserved failure semantics, whole-tuple validation, and incomplete evidence on observation failure. Document semantics in the report contract, README, and agent reference.
+3. Run all required checks on Ruby 3.3/3.4/4.0 with published Minitest 5.26.2 and independent specification/quality review.
+4. Repeat PStoreLogger on a copied source snapshot using Ruby 3.4's standard-library PStore. Preserve existing tests and production source, export skills, and ground added persistence assertions in project and PStore contracts.
+
+The existing PStoreLogger tests pass Hash payloads. Such calls remain unsupported by scalar collection and must not be silently discarded. Retain an instrumented full-suite run showing that limitation, plus a clearly filtered fresh primitive-scenario run if the declared subset can be exercised completely. A full uninstrumented suite must still pass after adding tests; filtered coverage is never whole-suite coverage.
+
+## Deferred
+
+No structured-object domains, strings, arbitrary argument serialization, default-expression static analysis, omission coverage, class-method collection, or replay in this slice.

data/docs/optional-arguments-results.md

@@ -0,0 +1,45 @@
+# Optional scalar arguments
+
+This implements the [approved continuation](optional-arguments-plan.md) after the first real-project pilot rejected `PStoreLogger#save(data, file_id: nil)`. Named optional positional and keyword parameters now work alongside required parameters. Every parameter must still be declared, and observed values must remain within the supported scalar representation.
+
+The production change widens the collector's parameter-kind allowlist; Ruby still evaluates and binds arguments. The adapter adds two scope fields under report schema 1: `input_semantics: "effective_bound_values"` and `argument_presence: "not_observed"`. The planner, criterion, contract digest semantics, and obligation IDs are unchanged.
+
+## Meaning of the evidence
+
+Omitting an argument whose default is `nil` and explicitly passing `nil` exercise the same value obligation. This does not establish omission coverage. Defaults execute once through normal Ruby execution, including side effects and dependent defaults. A default that raises before method entry yields no entry observation for that target and preserves the original exception. Another selected method called during default evaluation can still contribute its own entry observation.
+
+A primitive value outside a declared domain invalidates the whole tuple. A non-primitive effective value, including a default, makes selected-target collection incomplete. Existing positive hits remain evidence, while unhit obligations become unknown. Rest parameters, keyword-rest, forwarding, explicit blocks, class-method targets, and structured objects remain outside this release.
+
+## Adoption boundary
+
+The PStoreLogger continuation declares an explicit primitive scenario subset: `data` in `[nil, false, true, 0, :event]` and `file_id` in `[nil, 1]`. Those yield seven marginal value obligations, not Cartesian combinations or the complete domain of marshalable objects.
+
+The original project tests save Hash payloads. Their ordinary execution must keep passing; instrumenting the full suite must honestly report incomplete collection on those object-valued inputs. A fresh filtered run of separate scalar persistence tests can establish exercise of the declared subset only.
+
+Assertions are grounded in the project's documented storage layout and filename behavior, and in Ruby's [PStore contract](https://ruby-doc.org/3.4.1/stdlibs/pstore/PStore.html). PStore stores marshalable Ruby values through transactions. Added tests read the persisted payload, distinguish stored `nil` from a missing key, preserve `false`, check timestamps, and check explicit-ID collision behavior. No production behavior change is needed for that scenario.
+
+| Run | Minitest outcome | Collection outcome |
+| --- | --- | --- |
+| Original suite | 7 tests, 23 assertions pass | Uninstrumented baseline |
+| Original suite with adapter | 7 tests, 23 assertions pass | Incomplete, seven unknown obligations, `non_primitive_argument`; invocation fails |
+| Expanded suite | 13 tests, 63 assertions pass | Uninstrumented regression check |
+| Expanded suite with adapter | 13 tests, 63 assertions pass | Incomplete on Hash payloads; invocation fails regardless of positive hits |
+| Explicit scalar filter | 6 tests, 40 assertions pass | Complete, seven of seven marginal obligations exercised; invocation succeeds |
+
+Luna used the newly exported skills in an isolated copy of PStoreLogger at source commit `959e37410bac42ba47e43ee8da006ce9550d9f50`. Source hashes, exact skills, assertions, commands, reports, and a relocatable workspace are retained in the [pilot artifacts](pilots/2026-10-02-optional/pstore_logger/results.md) and [archive](pilots/2026-10-02-optional/pstore_logger/workspace.tar.gz). The expanded instrumented run's positive hit count can depend on test order before a Hash disables the target; completeness remains false in every case. All report IDs are fresh and their seven obligation IDs and contract digest agree with the offline plan.
+
+The archive was extracted into a fresh temporary directory, installed through ordinary `bundle install --local` with the checksum-verified Minitest package, and rerun successfully. [Reproduction evidence](pilots/2026-10-02-optional/pstore_logger/reproduction.json) retains the new report IDs, command exits, and filtered results. Loaded library paths and hashes are separately captured in the runtime probe. The archive excludes installed dependencies; its cached official Minitest package is retained for offline installation. The local reproduction uses CRuby 3.4.7 so PStore comes from its standard library, with unrelated ambient gem and Bundler variables cleared.
+
+To repeat locally, extract the archive into an empty directory, set `SPECPROOF_ROOT` to this gem checkout, install with Ruby 3.4's `bundle install --local`, and invoke `ruby run_pilot.rb`. The retained runner records this machine's Ruby path; adjust `RUBY_BIN` and its environment `PATH` for another machine. The driver exits successfully only when expected child outcomes match: full instrumented children fail on integrity, while the filtered scalar child succeeds. Its success does not relabel the incomplete child reports.
+
+The earlier [pilot](real-project-pilot.md) and agent evaluation archives retain their original skill bytes and implementation context. This continuation records newly exported skills separately; it does not reinterpret earlier rejected probes as successful runs.
+
+## Verification
+
+- Full suites pass separately on CRuby 3.3.6, 3.4.7, and 4.0.1 with published Minitest 5.26.2: **131 runs, 663 assertions**, no failures, errors, or skips.
+- The Ruby 4.0.1 default Rake task passes tests and RuboCop: **83 files**, no offenses. Its deliberate method-redefinition fixtures emit expected Ruby warnings.
+- `bin/check` passes syntax checks, packaging and skill checks (**2 runs, 66 assertions**), and gem build. Existing RBS declarations validate; that does not type-check the implementation or import RBS specifications.
+- Collector tests cover optional positional and keyword bindings, mixed signatures, dependent defaults, side effects, raising defaults, nested selected calls, and preserved unsupported forms. Subprocess tests verify omitted/explicit `nil` hits, offline-plan IDs and digest equality, whole-tuple domain validation, and incomplete evidence on non-primitive defaults.
+- Luna specification and quality reviews passed after adding the two missing acceptance cases. Independent pilot review and source/hash/report checks passed, including actual loaded runtime paths and reproduced child exit statuses.
+
+No runtime dependency was added, no external project's source was modified, and no gem or branch was published. Remote CI execution and arbitrary-object collection remain unverified or deferred.

data/docs/pairwise-partitions-results.md

@@ -0,0 +1,53 @@
+# Pairwise partition coverage results
+
+This records the initial unrestricted implementation. Whole-partition
+restrictions have since been added; see the [constrained example](../examples/constrained_partition_pairs/README.md)
+and the current [report contract](report-format.md).
+
+`pairwise-partitions-v1` plans category pairs from explicit complete, disjoint
+integer partitions crossed with finite inputs. The scalar
+`input-basics-v1` and finite-value `pairwise-finite-v1` criteria retain their
+existing behavior. At the time of this evaluation, the criterion supported
+only `all_allowed: true`; forbidden assignments and explicit partitions on
+finite-valued inputs were rejected.
+
+The runnable [age-by-country example](../examples/pairwise_partitions/README.md)
+uses age `0..120`, partitioned into minor `0...18` and adult `18..120`, crossed
+with countries `"ro"` and `"de"`. The plan contains four category pairs. A
+partition obligation serializes its inclusive category bounds, for example
+`{ "kind": "partition", "name": "minor", "lower": "0", "upper": "17" }`.
+
+On CRuby 4.0.1 with the prepared partition bundle, the initial example process
+passed 1 test and 3 assertions, exercising 3/4 pairs. The missing pair was
+minor/`"de"`. `specproof suggest` inferred `pairwise-partitions-v1` from the
+checked report and returned the concrete call input `age: 0, country: "de"`
+with strategy `greedy-partition-pairwise-v1`. The separate complete process
+passed 2 tests and 4 assertions, exercising 4/4 pairs. Both processes completed
+with intact reports and `tests_passed: true`.
+
+The category report and suggested input establish only category membership for
+the declared values. The lower endpoint is a concrete representative; it does
+not establish boundary-value coverage or equivalent behavior throughout a
+category. The requirement file supplies the expected result for the added
+under-18 assertion. No output or behavioral rule is inferred from the plan or
+suggestion.
+
+## Verification
+
+The complete core suite passed on CRuby 3.3.6, 3.4.7, and 4.0.1: 284 tests
+and 1,440 assertions on each version. The optional RBS suite passed on each:
+54 tests and 499 assertions. RBS signature validation also passed on all three.
+No failures, errors, or skips occurred. Dependencies were reused from prepared
+local bundles; the feature adds no dependencies.
+
+Regression coverage at that revision included category membership within one valid call,
+independent exact-value scalar obligations, canonical category identities,
+huge integer endpoints, invalid partition geometry and policies, unsupported
+forbidden assignments and finite partitions, multi-pair suggestions, bounded
+enumeration, and rejection of altered category identities in coverage reports.
+RuboCop passed for 140 files. Syntax, packaged skill assets, and gem build
+checks also passed (2 packaging/asset tests, 76 assertions).
+
+The [installed agent exercise](evaluations/pairwise-partitions-skills.md)
+records old-guidance and updated-guidance runs, unchanged fixture checks,
+report tampering rejection, and hashes of the tested packaged library/skills.

data/docs/pairwise-results.md

@@ -0,0 +1,77 @@
+# Finite pairwise coverage
+
+The opt-in `pairwise-finite-v1` criterion derives obligations from explicit
+finite input domains and a declared combinations group. `all_allowed: true`
+admits the full Cartesian product; partial `forbid` assignments remove matching
+full tuples. A pair is required only when an allowed full assignment contains
+it. No implementation behavior is used to invent restrictions or expected
+results.
+
+The existing collector supplies whole calls. Calls cannot combine their
+individual values to manufacture a pair hit. Every analyzed input must be in
+its domain, including inputs outside the selected pairwise group. A forbidden
+call earns no hits under either criterion and is recorded as outside the joint
+domain. This does not make a deliberate negative test fail.
+
+The scalar criterion remains the default. Scalar IDs and contract digests
+without combinations metadata retain their previous representation. Typed
+pair IDs distinguish strings from symbols, and equivalent declaration/rule
+orders keep identity stable. Rule provenance survives duplicate declarations.
+
+## Demonstrated value
+
+The runnable [delivery example](../examples/pairwise/README.md) starts with
+passing assertions for `00`, `01`, and `10`. Both values of each input appear,
+but pair coverage is only 3/4. The missing `11` assertion, derived from the
+separate requirements, exposes the faulty notification result. Coverage then
+reaches 4/4 while `tests_passed` remains false. A separate corrected
+implementation passes all four assertions.
+
+The constrained declaration requires three pairs and explains the excluded
+fourth. The three-input example covers all 12 pair rows with four calls; it
+does not cover all eight full assignments. The [agent workflow exercise](evaluations/pairwise-skills.md)
+records how the exported skills guide a fresh actor through a missing-pair
+test without narrowing the contract to hide the defect.
+
+## Review and limits
+
+Independent Luna specification review found that the global obligation limit
+was checked after retaining every target's pair space. Planning now checks the
+running count before retaining each space and stops on the first crossing.
+A regression verifies that later targets are not planned after that error.
+Quality review found no functional defect in the reviewed implementation.
+
+Enumeration is limited to 10,000 complete assignments and 10,000 possible pair
+rows per target, with at most 10,000 required pair obligations in a plan.
+These are explicit configuration errors, not sampling. Excluded-pair metadata
+is bounded per target, but not globally: many heavily constrained targets can
+still produce a large combined report. This remains a resource limitation for
+large projects.
+
+This release supports one finite combinations group per target. It does not
+generate test suites, infer business constraints, solve arbitrary Ruby
+predicates, measure higher-order interactions, or prove assertion adequacy.
+RBS can supply finite inputs to a combinations-only declaration; its existing
+supported type subset is unchanged.
+
+## Verification
+
+The final implementation passed the following local checks:
+
+| Check | Result |
+| --- | --- |
+| Core suite on Ruby 3.3.6, 3.4.7, 4.0.1 | 207 tests, 1,044 assertions per runtime |
+| Optional RBS suite on those runtimes | 47 tests, 436 assertions per runtime |
+| `rbs -I sig validate` on those runtimes | Passed |
+| Default locked development bundle, `bundle exec rake` | Core suite passed; 115 files linted without offenses |
+| `bin/check` | Syntax checks, 2 packaging tests / 76 assertions, and gem build passed |
+| Fresh example processes | Initial 3/4 passing; gap 4/4 failing assertion; corrected 4/4 passing; three-input 12/12 passing |
+| Constrained CLI plan | 3 required pairs, 1 explained exclusion |
+
+CI's optional suite command now includes every `test/rbs/*_test.rb` file.
+Existing method-redefinition fixture warnings and the gemspec's missing-homepage
+warning remain; neither is a new failure. No dependency was added.
+
+To keep the existing complexity budgets, option parsing, coverage projections,
+and report formatting use small helpers. The full regression suite covers the
+preserved scalar behavior and adapter lifecycle; no lint threshold was raised.

data/docs/pairwise-suggestions-results.md

@@ -0,0 +1,104 @@
+# Pairwise suggestion results
+
+SpecProof can turn a completed pairwise coverage report into deterministic
+allowed assignments for its missing pairs. The Ruby API is
+`SpecProof.suggest(specifications, report: parsed_json)`; the CLI is
+`specproof suggest SPEC.rb --report coverage.json [--rbs FILE --target TARGET]
+--format json`. Suggestions always use `pairwise-finite-v1` and
+`greedy-pairwise-v1`.
+
+Before selecting assignments, SpecProof replans the supplied declarations and
+checks the report's schema, kind, criterion, digest, exact typed obligation
+denominator, declared scope, counters, statuses, and projections. The source
+run must be completed and intact, with no errors or unknown observations.
+Either Boolean `tests_passed` value is accepted and retained, and filtered
+reports remain limited to their recorded scope. The result preserves the
+source run ID and scope so callers can review what evidence it used.
+
+Each suggestion is a full assignment for a declared combination group. Its
+`covers` list names only newly covered missing pair IDs; the union of those
+lists is the missing set. `unassigned_inputs` lists analyzed method parameters
+outside the group and explicitly excluded parameters. The caller must supply
+those values, and all analyzed values must still be valid for runtime evidence.
+Suggestions are not executed and provide no expected outputs. They are not a
+minimum-size covering set: the deterministic greedy strategy chooses the
+largest current gain and breaks ties by canonical typed assignment order.
+
+Use a separate requirement as the oracle for every assertion. A contract
+digest covers normalized input declarations, not implementation or test bytes,
+so rerun the intended suite after code or test changes. Suggestion work is
+bounded to 10,000 cumulative full assignments, 10,000 cumulative possible pair
+rows, 1,000,000 candidate-to-missing-pair memberships, and a 32 MiB input
+report. Oversized work is rejected without sampling, truncation, or partial
+results.
+
+## AllInRuby pilot
+
+The real-project pilot used `AllInRuby::Installer#install` in a scratch copy of
+the project. Its pairwise group contains the finite `scope`, `dry_run`, and
+`backup` inputs. `agents` is explicitly excluded because it is a collection
+parameter that each test must supply separately. The project README documents
+the individual scope and option behavior used to justify the group; no
+implementation-derived restriction was added.
+
+The captured baseline passed its existing suite and observed 9 of 12 pair
+obligations. The three missing pairs all fit in the allowed assignment
+`scope: "global", dry_run: true, backup: false`. SpecProof returned that one
+candidate and listed `agents` as unassigned. The follow-up test in the scratch
+copy checks the documented dry-run preview, absence of a backup, and unchanged
+file contents. The original 32 tests and 104 assertions passed; adding one test
+produced 33 passing tests and 114 assertions, with 12/12 pairs exercised. The
+fresh report then produced no suggestions. This is a coverage improvement,
+not a discovered production defect.
+
+The copy came from clean HEAD `bbe9921470cbf80ae01ae4fbb2de50a62187ba9e`;
+the source checkout's pre-existing edits were preserved. The group is an
+explicit pilot declaration based on documented independent options, not an
+inferred business rule. [Retained pilot evidence](evaluations/artifacts/pairwise-suggestions/pilot/pilot-notes.md)
+includes requirement citations, original tests, the added assertion, commands,
+reports, and source hashes.
+
+## Installed-skill exercise
+
+The installed `specproof-test-gaps` exercise used a fresh Luna actor. Its baseline
+and pairwise plan describe `ToggleSummary#count` with three Boolean group
+inputs and caller-supplied `context`. The current suggestion output proposes
+`a: true, b: true, c: true` for the three missing pairs and lists `context` in
+`unassigned_inputs`. The added assertion expects three from the separate
+requirement to count true flags. It exposes the seeded defect (actual result
+two): coverage reaches 12/12 while `tests_passed` stays false. Suggestion output
+preserves that failed result and reports zero missing pairs. An altered
+incomplete report is rejected with exit 2. The actor also refused to hide the
+defect by forbidding a combination the requirements explicitly allow.
+
+See the [skill evaluation](evaluations/pairwise-suggestions-skills.md) for the
+old-guidance comparison and executable evidence.
+
+## Review
+
+Independent Luna specification and quality reviews checked the evidence gate,
+deterministic selection, and CLI. Review moved cumulative checks ahead of
+enumeration and replaced quadratic preflight pair counting with an incremental
+sum that stops at the limit. Full assignments are cached only when requested,
+so ordinary coverage does not retain them. Typed report encodings are validated
+explicitly; no dependency or lint threshold was added.
+
+## Verification
+
+| Check | Status |
+| --- | --- |
+| Core suite on Ruby 3.3.6, 3.4.7, 4.0.1 | 250 tests / 1,297 assertions per runtime |
+| Optional RBS suite on those runtimes | 47 tests / 436 assertions per runtime |
+| RBS signature validation on those runtimes | Passed |
+| Default locked development bundle, `rake` | Passed; 126 files linted without offenses |
+| `bin/check` | Syntax, 2 packaging tests / 76 assertions, and gem build passed |
+| AllInRuby installed-gem pilot | 9/12 to 12/12, assertions passing |
+| Installed-skill exercise | 9/12 to 12/12, requirements-backed failure preserved |
+
+Existing method-redefinition fixture warnings and the missing-homepage gemspec
+warning remain. [Matrix evidence](evaluations/artifacts/pairwise-suggestions/verification/commands.json)
+records exact commands and environments; the installed library and skill hashes
+match the reviewed source.
+
+For a runnable, self-contained demonstration of the API and report boundaries,
+see the [pairwise suggestions example](../examples/pairwise_suggestions/README.md).