specproof 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 100497f9c2832ec3daa9906c1e7f80579a134fa82bf107c4ac4b2024b8fbf345
+  data.tar.gz: 3cd2f171453545d1d423bd6df3a15d4b98bd14dd073a9cb26d04c824f67cb897
+SHA512:
+  metadata.gz: 1bdf315ba69e5ed2a55174c81d2318383b8362ec6129852285cd4798265fae31a8befdddba0ed005f37d4473600b3096b0fb0c81c1a0129fb50f79ef097540e7
+  data.tar.gz: 2b4932bf07e4bb785a39bc89a490bca27907f197cd59501d064f3b8062dfeae3691271fc3073fee12c79a55adae4ed0851910fb0ef1081a35726dc64cceea923

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+- First public proof-of-concept release. The public API, specification DSL, and report formats may change, including breaking changes.
+- Declare bounded integer and finite input domains; check partition gaps, overlaps, and incompatible constraints.
+- Plan boundary candidates and feasible pairwise combinations, with deterministic suggestions for missing pairs.
+- Observe supported method calls during Minitest runs and produce human-readable and JSON coverage reports.
+- Support string and Ruby method-object targets, including class/module methods, plus optional RBS input declarations.
+- Include agent skills for writing specifications and reviewing test gaps.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucian Ghinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,283 @@
+# SpecProof
+
+**Proof of concept:** SpecProof is experimental and under active development.
+The public API, specification DSL, and report formats may change, including
+breaking changes between releases. Pin the gem version when trying it in a project.
+
+SpecProof checks a small, explicit contract about a Ruby method's inputs. It can find gaps or overlaps in declared input partitions, propose boundary-focused example values, and report which proposed values an existing Minitest suite actually passed to a method.
+
+SpecProof is an aid for reviewing test gaps. It does not prove application behavior, generate tests, infer expected results, or claim that a passing test suite establishes correctness.
+
+Use the `SpecProof` namespace in new code. The previous `Specproof` constant remains an alias.
+
+## Install
+
+SpecProof requires Ruby 3.3 or newer and has no runtime gem dependencies. This release is tested on CRuby 3.3, 3.4, and 4.0. Add it to your application's Gemfile, pinning the version while the API is experimental:
+
+```ruby
+gem "specproof", "0.1.0"
+```
+
+Runtime Minitest collection is optional and supports Minitest `>= 5.26.2` and `< 5.28.0` with matching package/runtime major and minor versions; keep Minitest in the application's test group. The development bundle selects `~> 5.26.2` because the published 5.27.0 package contains a mismatched runtime version; see [compatibility evidence](docs/minitest-compatibility.md).
+
+For development in this checkout, run commands from the gem root with `bundle exec`. To use a development checkout in another application, use a local path dependency:
+
+```ruby
+gem "specproof", path: "/path/to/specproof/gems/specproof"
+```
+
+## Describe an input contract
+
+Create a Ruby file that declares the target method and the input values it accepts:
+
+```ruby
+require "specproof"
+
+SpecProof.define "AgePolicy#adult?" do
+  input :age, range: 0..120, allow_gaps: false, allow_overlaps: false do
+    partition :minor, range: 0...18
+    partition :adult, range: 18..120
+  end
+end
+```
+
+The declaration is executable Ruby. Use it only for trusted specification files. SpecProof does not resolve or autoload the declared application targets during offline analysis; the declaration file itself can execute any Ruby its author writes. Integer ranges are inclusive at both ends unless written with `...`; finite domains accept `nil`, booleans, integers, symbols, and explicitly listed text values.
+
+Targets can be written as canonical strings or as Ruby `Method`/`UnboundMethod`
+objects. For example, `"DeliveryOptions#build"` and
+`DeliveryOptions.instance_method(:build)` normalize to the same target. A
+class or module singleton method uses a dot, as in `"DeliveryOptions.build"`
+or `DeliveryOptions.method(:build)`. Strings are useful for offline
+specifications: normalization does not load or autoload the application owner.
+Method objects are convenient when the application code is already loaded;
+they use Ruby reflection and do not invoke the method. The declaration-time
+method must be a directly defined public method on a named class or module;
+aliases, inherited singleton methods, anonymous owners, and methods bound to
+arbitrary instances are unsupported. See the runnable
+[method targets example](examples/method_targets/README.md) and
+[verification results](docs/method-targets-results.md).
+
+Finite strings are exact values, not a general String domain. For example, `values: [nil, 1, "user_123"]` describes three scenario values; `"user_123"` is distinct from `:user_123`. Only exact `String` instances with valid UTF-8 or US-ASCII encoding are accepted, and US-ASCII is canonicalized to UTF-8. Empty strings, whitespace, Unicode, and embedded NUL are valid; invalid bytes, other encodings, and String subclasses are rejected. Text is not trimmed, case-folded, or normalized. SpecProof uses owned snapshots without changing application strings. RBS string literals and finite unions of supported literals provide exact string scenarios; unrestricted `String` remains unsupported, and a selected union containing an unsupported member fails atomically.
+
+`allow_gaps: false` requires every value in the input domain to belong to at
+least one partition. `allow_overlaps: false` requires it to belong to at most
+one. Together, every valid value belongs to exactly one partition. These rules
+check the specification's grouping; they do not require testing every value.
+Omitting either option permits that condition, equivalent to setting it to
+`true`. Partition-based pairwise coverage requires both options to be `false`.
+
+Existing specifications can still use `exhaustive: true` in place of
+`allow_gaps: false`, and `disjoint: true` in place of `allow_overlaps: false`.
+Their `false` values map to the new options' `true` values. Use only one
+spelling per policy in a declaration. Equivalent spellings preserve contract
+digests and obligation IDs.
+
+Run the checker and planner:
+
+```sh
+bundle exec specproof check examples/age_policy/specification.rb
+bundle exec specproof plan examples/age_policy/specification.rb
+bundle exec specproof plan examples/age_policy/specification.rb --format json
+```
+
+`check` reports declared partition gaps and overlaps. `plan` reports candidate values from the `input-basics-v1` criterion, including values at the domain edges and partition boundaries. It does not claim those candidates form a complete test suite. JSON output has a versioned schema and includes source locations and a digest of the declared contract.
+
+The age example plans `0`, `1`, `17`, `18`, `119`, and `120`. The shipping example in [examples/shipping.rb](examples/shipping.rb) shows finite domains. [examples/partition_gap.rb](examples/partition_gap.rb) is intentionally incomplete and makes `check` exit with a semantic finding.
+
+## Reuse an explicit RBS signature
+
+RBS can supply supported finite scalar input types for explicitly selected
+instance-method and singleton-method targets. Selectors use `Class#method` for
+instance methods and `Class.method` or `Module.method` for singleton methods.
+Add only behavioral bounds and partitions that the
+signature cannot express; an unrestricted `Integer` needs such a refinement.
+For a target selected from RBS, each DSL `input` or `exclude_input` must use a
+name declared in that signature. By default all named signature parameters
+must be analyzed; a deliberately narrower contract accounts for each omitted
+name with an explicit reasoned exclusion, and still analyzes at least one
+input. A mismatch reports `rbs_input_mismatch`; other DSL-only targets can
+still be supplied alongside selected RBS targets. Supported finite RBS types
+remain imported without duplicate DSL inputs. An explicit exclusion can scope
+out a type-only parameter, while an unsupported selected union remains an
+atomic failure.
+The reader supports the verified RBS `4.2.0` parser only. RBS remains an
+optional dependency, so consumers who use this workflow must add it to their
+own bundle:
+
+```ruby
+gem "rbs", "4.2.0", require: false
+```
+
+The core gem has no runtime gem dependencies. See
+[the supported integration limits](docs/rbs-implementation-status.md). For
+the opt-in adapter bundle in this checkout, the [registration example](examples/rbs_registration) combines
+`sig/registration.rbs` with a DSL age refinement. Its independent
+[eligibility rule](examples/rbs_registration/requirements.md) says an applicant
+is eligible exactly when `age >= 18` and consent is true.
+
+The compact [finite string example](examples/rbs_string_literals) imports
+`country: ("ro" | "de")` and `expedited: bool` without duplicate DSL inputs.
+Its plan includes the exact country strings. String values remain distinct
+from same-spelling symbols. RBS `String` remains an unrestricted domain and is
+not supported. RBS return types are ignored; expected behavior must come from
+an independent requirement.
+
+From this checkout, run the check and plan with the explicit file and target:
+
+```sh
+BUNDLE_GEMFILE=Gemfile.rbs bundle exec ruby -Ilib exe/specproof check examples/rbs_registration/specification.rb --rbs examples/rbs_registration/sig/registration.rbs --target 'Registration#eligible?' --format json
+BUNDLE_GEMFILE=Gemfile.rbs bundle exec ruby -Ilib exe/specproof plan examples/rbs_registration/specification.rb --rbs examples/rbs_registration/sig/registration.rbs --target 'Registration#eligible?' --format json
+```
+
+The plan contains nine marginal obligations: six age candidates and three
+consent values (`nil`, `false`, and `true`). They are not nine input
+combinations, do not specify expected results, and do not prove output
+behavior. The runnable example shows an eight-of-nine report when age 18 is
+omitted, the independent boundary assertion failing against an `age > 18`
+implementation, and a fresh complete report with the corrected `age >= 18`
+implementation. The faulty and corrected versions are separate files and each
+checkpoint runs in its own process. See the example README for exact commands.
+
+## Observe an existing Minitest suite
+
+The optional adapter records calls to directly defined public instance methods
+and class/module singleton methods with named required or optional
+positional/keyword parameters. By default, analyze every parameter, including
+optional ones. A deliberately partial input scope must explicitly exclude every
+other named parameter with `exclude_input :name, reason: "..."`, and at least
+one input must remain analyzed. It observes effective bound scalar values at
+method entry after Ruby applies defaults; an omitted argument and an explicitly
+supplied equal value exercise the same obligation. A default that raises before
+entry contributes no entry observation. Rest, keyword-rest, forwarding, and
+explicit block parameters remain unsupported.
+
+When only some parameters have finite input domains, you may explicitly exclude
+the remaining named parameters with a reason. The declaration must still account
+for every name in the runtime signature: each parameter is either analyzed or
+excluded. Excluded values are not read by the collector. In particular, an
+excluded object such as a `Hash` can coexist with selected scalar coverage,
+while an object-valued selected input still makes collection incomplete. This
+scope says nothing about excluded values or behavior involving their content.
+See the runnable [input selection example](examples/input_selection/README.md).
+
+It resolves the selected owner's canonical method name afresh when collection
+starts, then observes that directly defined method during the original test
+run in the same process and thread. A method object supplied at declaration
+time must still describe that current direct definition; declaration and
+collection both reject changed method identity. Calling an alias of the
+selected definition counts; a subclass override counts only when it calls the
+selected definition through `super`. Aliased target declarations and inherited
+target declarations are unsupported. It does not replay tests, capture return
+values, inspect assertions, infer defaults, or infer expected outcomes. A
+non-primitive effective value for an analyzed input makes collection
+incomplete, even if it comes from an optional default.
+
+Add a separate test entrypoint after Minitest and your application code have loaded:
+
+```ruby
+require "minitest/autorun"
+require "age_policy"
+require "specproof/minitest"
+
+SpecProof::Minitest.install!(
+  specifications: ["examples/age_policy/specification.rb"],
+  output: "tmp/specproof-coverage.json",
+  fail_on_missing: false
+)
+```
+
+The runnable [age policy example](examples/age_policy) includes a passing implementation and assertions at all six planned values. Its `faulty` variant isolates the common `age > 18` boundary defect: the five non-boundary examples pass, while the planned value `18` remains unobserved. The separate explicit boundary assertion fails against that faulty implementation. Collection remains independent of the test result; a collector integrity failure fails the run, and original Minitest failures are preserved.
+
+Reports distinguish exercised, not-observed, and unknown obligations; the `missing` summary lists the unobserved obligations. Missing values are informational unless `fail_on_missing: true` is selected. Reports identify their run, state whether collection completed, and use `obligation_hits` evidence with `replay: false`. JSON values include a type; integer values are decimal strings so large integers remain exact. String values use `{ "kind": "string", "value": "..." }` under the existing schema version 1, so consumers must handle this additive kind explicitly. Offline check/plan and runtime reports identify `scope.completeness_scope: "analyzed_inputs"` and list analyzed and excluded names in `scope.input_scope`. Human reports disclose excluded names and reasons. A matching set of obligation IDs does not establish matching scope: compare a fresh report's digest and input scope. `100%` means all candidates for analyzed inputs were exercised; excluded inputs, behavior, output, and interactions are not covered.
+
+## Scope and limits
+
+SpecProof currently focuses on bounded integer ranges and finite primitive values, including exact enumerated text. The opt-in RBS reader supports only explicitly selected scalar signatures and rejects unsupported types rather than guessing. It does not analyze floats, time values, arbitrary objects, stateful or multi-call behavior, or SMT-based constraints. Specifications are trusted Ruby code; do not load declarations from untrusted sources. Collection adds an observation hook to selected application methods during the test run, so inspect the report as supporting evidence rather than as a semantic proof.
+
+## Agent skills
+
+The gem includes two optional skills for authoring specifications and reviewing test gaps. Export them only to an explicit client directory:
+
+```sh
+bundle exec specproof skills export --to .agents/skills
+```
+
+The exporter reports the files it writes and refuses conflicting destination content. See [docs/agent-skills.md](docs/agent-skills.md) for their purpose and use.
+
+Try “Use specproof-specify to check whether these age partitions cover their declared range” or “Use specproof-test-gaps to find missing boundary inputs and add tests justified by the supplied eligibility rules.” See the [behavioral evaluation record](docs/evaluations/agent-skills-v0.1.md) for observed outcomes and limits.
+
+The [optional-argument pilot](docs/optional-arguments-results.md) shows adoption on PStoreLogger and the distinction between a complete scalar scenario report and incomplete full-suite collection on object payloads.
+
+The [RBS implementation results](docs/rbs-implementation-status.md) include
+the three-Ruby matrix, [six guided agent scenarios](docs/evaluations/rbs-agent-skills-v0.1.md),
+and [unchanged-signature BranchProof adoption](docs/pilots/rbs-v0.1/README.md).
+
+The [input-selection results](docs/input-selection-results.md) show the unchanged
+PStoreLogger suite collecting scoped file-ID coverage with Hash payloads,
+plus agent exercises that preserve excluded-input scope and failing assertions.
+
+The [finite-string results](docs/finite-strings-results.md) extend that pilot to
+the documented `"user_123"` case, showing its missing obligation and a separate
+requirement-backed assertion that exercises it.
+
+## Pairwise finite input combinations
+
+`input-basics-v1` remains the default scalar criterion. When a requirement
+defines a finite joint scenario, declare its inputs in one `combinations`
+group and explicitly choose `all_allowed: true` or list requirement-backed
+`forbid` clauses. The `pairwise-finite-v1` criterion plans each pair of values
+that occurs together in at least one allowed full assignment. It does not
+assert expected outputs or establish that inputs are behaviorally independent.
+Each analyzed input in a runtime call must still be valid before that call can
+earn pairwise evidence.
+
+The runnable [pairwise example](examples/pairwise/README.md) documents two
+independent DeliveryOptions requirements and shows the faulty interaction
+implementation passing three calls while missing the `expedited: true`,
+`notify: true` pair. A requirement-backed assertion exposes the defect; a
+separate corrected implementation then covers all four pair obligations. The
+example also shows a constrained plan with three required and one excluded
+pair, and a three-boolean plan with 12 pair obligations versus eight exhaustive
+tuples.
+
+Use `specproof suggest` when an intact pairwise coverage report has missing
+pairs. It replans the current declarations, checks that the report matches
+their exact typed obligations and recorded scope, then prints allowed full
+group assignments that cover the missing pairs. Suggestions are candidates
+for new tests: they are not executed, carry no expected results, and do not
+fingerprint implementation or test files. Rerun the intended suite after
+source or test changes. The [suggestion example](examples/pairwise_suggestions/README.md)
+shows a three-of-four DeliveryOptions baseline, the `11` candidate, a separate
+requirement-backed failing assertion, and a fresh corrected run. It also shows
+one suggested three-boolean assignment covering several missing pairs, with
+the other method inputs left for the caller to supply when outside the group.
+
+## Pairwise coverage over integer partitions
+
+`pairwise-partitions-v1` pairs explicitly complete and non-overlapping integer
+categories with other finite inputs. It supports `all_allowed: true` or
+requirement-backed `forbid` assignments that select whole integer
+partitions with `in_partition(:name)` and exact finite values. Each clause
+forbids matching full assignments; required and excluded pairs are derived
+from whether an allowed full completion exists. An excluded pair can therefore
+be impossible indirectly through a restriction on a third input. Integer
+restrictions must select a whole partition; raw integer values and partial
+range predicates are not supported. Finite inputs continue to use exact values.
+Category coverage is not boundary-value coverage and does not assert equivalent
+behavior throughout a category. The runnable [unrestricted partition
+example](examples/pairwise_partitions/README.md) shows a missing minor/`"de"`
+category pair. The [constrained example](examples/constrained_partition_pairs/README.md)
+shows requirement-backed restrictions, an excluded category pair, and allowed
+assignment suggestions. See the [initial partition results](docs/pairwise-partitions-results.md)
+and [constrained partition results](docs/constrained-partition-pairs-results.md)
+for verification evidence.
+
+## Development
+
+Run the test and lint tasks with `bundle exec rake`. The default task runs Minitest and RuboCop. The CI matrix covers Ruby 3.3, 3.4, and 4.0.
+
+To reproduce the small baseline and instrumented timing comparison, see [docs/benchmark.md](docs/benchmark.md).
+
+## License
+
+SpecProof is released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/docs/agent-skills.md

@@ -0,0 +1,60 @@
+# Agent skills
+
+SpecProof ships two optional Agent Skills alongside the Ruby gem. Export them
+into an application's own skill directory with an explicit destination:
+
+```sh
+specproof skills export --to .agents/skills
+```
+
+The command copies `specproof-specify/` and `specproof-test-gaps/` into that
+directory. Repeating the command leaves identical files alone. If a packaged
+file would overwrite different content, export reports a conflict before
+writing any skill files. Other files in the destination, including local files
+inside either skill folder, are kept. An interrupted filesystem operation can
+still leave a partial copy; rerun the command after correcting the reported
+filesystem issue.
+
+The skills also document the opt-in RBS workflow: inspect explicitly selected
+signatures, reuse supported finite input types, and add only requirement-backed
+behavioral refinements. They support deliberate partial input scope through
+one named, reasoned exclusion for each out-of-scope parameter; default scope
+remains every named parameter, with at least one analyzed input required. The
+gap-review skill requires fresh runtime evidence and compares the report's
+analyzed/excluded input scope as well as its digest, integrity, test results,
+and actual test command. A complete percentage covers analyzed input
+obligations only, and human reports disclose exclusions. RBS supplies no output
+oracle. The runnable [input selection example](../examples/input_selection/README.md)
+shows a Hash payload excluded while a boolean option remains analyzed. Earlier evaluation results
+in this document's linked record describe the workflows and artifacts named
+there; they do not establish agent performance for this newer RBS workflow.
+
+For Codex repository discovery, place the exported folders under
+`.agents/skills` in the repository. Codex searches that directory from the
+current working directory through its repository ancestors. Open a new Codex
+session in the project and ask for one of the named skills to confirm it is
+available. This discovery check is separate from the export result: export
+confirms that files were copied, while the client session confirms that the
+client found and loaded them. See the [Codex skills guide](https://learn.chatgpt.com/docs/build-skills)
+and the [Agent Skills format](https://agentskills.io/specification).
+
+Keep skill use opt-in. The exporter writes only to the path supplied by the
+caller; it does not select a home directory, edit global configuration, alter
+`AGENTS.md`, or access the network. The packaged skills and their local
+references are self-contained, so the exported folder can be reviewed and
+removed as ordinary project files.
+
+The current RBS workflow was exercised in six fresh, isolated native Luna
+tasks using skills exported from an installed gem. See the [RBS evaluation
+record](evaluations/rbs-agent-skills-v0.1.md) for actual outcomes, retained
+commands and reports, and the limits of these guided scenarios.
+
+The export and one specification workflow were exercised in Codex CLI
+`0.160.0` with `gpt-6-luna`, using `.agents/skills` in an isolated project and
+the installed gem rather than this checkout. A separate fresh formatting task
+did not load either SpecProof skill or create specifications. See the
+[evaluation record](evaluations/agent-skills-v0.1.md) for retained artifacts,
+baseline observations, repeated attempts, and limitations. These checks are
+bounded observations of agent behavior, not a guarantee for every agent or
+client. Other clients can receive the same exported folders through their
+documented manual skill installation workflow; they have not been tested here.

data/docs/benchmark.md

@@ -0,0 +1,24 @@
+# Small-suite collection timing
+
+This benchmark compares equivalent Minitest subprocesses that call `AgePolicy#adult?` three or six times. The test methods and assertions are generated once for each suite size and run unchanged in baseline and instrumented modes. The instrumented mode installs the optional adapter and verifies that report hit totals match the direct call counter.
+
+Run it from `gems/specproof` with a Minitest 5.27.x installation whose activated gem version and `Minitest::VERSION` both identify the supported release:
+
+```sh
+ruby script/benchmark_age_policy.rb
+```
+
+The script runs five repetitions per mode by default. Pass a positive iteration count as the first argument for a shorter smoke run.
+
+This recorded run used Ruby 4.0.1 on arm64 macOS, Minitest gem `5.27.0`, runtime `Minitest::VERSION` `5.27.0`, and SpecProof `0.1.0`. The available RubyGems 5.27.0 artifact on this machine had an embedded runtime version of `5.26.2`, so the measurement used an unmodified local rebuild of the `v5.27.0` source tag to meet the adapter's package/runtime version check. No Minitest code was patched for the run.
+
+Each timing includes Ruby process startup, Bundler setup, Minitest startup, the test suite, and report writing. All five repetitions made exactly the number of calls shown; instrumented hit totals matched those counts.
+
+| Suite size | Mode | Calls per run | Wall time, repetitions 1–5 (seconds) |
+| --- | --- | ---: | --- |
+| 3 tests | Baseline | 3 | 0.229863, 0.231492, 0.218486, 0.235095, 0.229194 |
+| 3 tests | Instrumented | 3 | 0.262548, 0.254388, 0.261317, 0.280937, 0.239743 |
+| 6 tests | Baseline | 6 | 0.236327, 0.230261, 0.241569, 0.230310, 0.220956 |
+| 6 tests | Instrumented | 6 | 0.241652, 0.250458, 0.237547, 0.246748, 0.239821 |
+
+These measurements describe only this tiny fixture and subprocess setup. Process startup dominates much of the elapsed time, so the results do not estimate overhead for a larger application suite.

data/docs/constrained-partition-pairs-results.md

@@ -0,0 +1,44 @@
+# Constrained partition pairs: verification
+
+The [example](../examples/constrained_partition_pairs/README.md) declares
+`forbid age: in_partition(:minor), account: "business"`. Filtering complete
+category assignments leaves six allowed tuples, eleven required pairs, and
+one excluded pair. Its three baseline calls cover nine pairs. Two suggested
+calls, with independent requirement-based assertions, bring coverage to eleven
+of eleven.
+
+Luna subagents implemented the core, integration tests and documentation.
+Separate specification and code reviews found no remaining code issues.
+Review corrected missing restriction provenance and clarified historical
+documentation. Native argument validation retains exact finite types,
+including `nil` and `false`; integer restrictions require explicit selectors.
+
+Verification on CRuby 3.3.6, 3.4.7 and 4.0.1 passed on each version:
+
+| Suite | Tests | Assertions |
+| --- | ---: | ---: |
+| Core | 303 | 1,579 |
+| Optional RBS | 55 | 509 |
+
+RBS signature validation, RuboCop (144 files), syntax checks, packaged skill
+checks and gem building passed. A final reuse of the memoized allowed
+assignments was checked with 50 focused tests and 240 assertions on Ruby 4.
+
+A separate exhaustive oracle checked all 256 forbidden subsets of an
+eight-tuple category space: two integer inputs sharing partition names and
+a finite input containing `nil` and `false`. Allowed assignments, required
+pairs, excluded pairs and acceptance of 8,192 native tuples matched independent
+expected results, including the entirely forbidden space.
+
+A Luna agent followed the updated test-gap skill against a scratch copy of
+the example. It obtained the two legal suggestions from the 9/11 baseline,
+used the separate requirements to justify expected outputs, and verified the
+complete run: two tests, five assertions and 11/11 feasible pairs exercised.
+The excluded minor/business pair remained outside the denominator. This was
+a source-checkout guidance exercise, not a fresh installed-gem evaluation.
+
+The implementation reuses existing coverage accounting, report validation and
+suggestion selection. No dependencies were added. Restrictions select whole
+integer partitions or exact finite values; arbitrary predicates and partial
+integer restrictions remain unsupported. Existing enumeration limits apply
+before restrictions reduce the space.

data/docs/finite-strings-results.md

@@ -0,0 +1,75 @@
+# Finite string values
+
+Implemented on `implement/finite-strings`, based on `main` at `f63dcaa`.
+Core, tests, documentation and skills are committed as `8195cae`.
+
+```ruby
+SpecProof.define "PStoreLogger#save" do
+  input :file_id, values: [nil, 1, "user_123"]
+  exclude_input :data, reason: "Payload contents are outside these file-ID scenarios"
+end
+```
+
+Finite domains and partitions now accept exact valid UTF-8 or US-ASCII String
+values, including empty strings and Unicode text. US-ASCII is stored as UTF-8;
+there is no trimming, case folding or Unicode normalization. Same-spelling
+strings and symbols are distinct. Declaration values and runtime observations
+are copied and frozen without changing application-owned values. Collection
+uses the value at method entry even when the method later mutates it.
+
+JSON adds the typed value `{ "kind": "string", "value": "user_123" }` under
+schema 1 and the existing `input-basics-v1` criterion. Existing nonstring IDs
+and digests remain unchanged. Consumers must handle the new value kind.
+
+## Changes and simplifications
+
+- `lib/specproof/domains.rb` centralizes supported-value validation and text
+  snapshots. The existing finite-domain representation, checker and planner
+  handle strings without a parallel string-domain hierarchy.
+- Model, coverage, collector, report and source-neutral type constraints reuse
+  those rules; `sig/specproof.rbs` describes the expanded public value union.
+- Focused tests cover encodings, mutation, mixed symbol/string values,
+  partitions, typed reports, runtime integrity and legacy identities.
+- README, report documentation and both packaged agent skills explain exact
+  scenario scope and preserve independent assertion requirements.
+
+No new dependency, CLI option, adequacy criterion or RBS extraction feature was
+added. RBS String types and string literals remain unsupported atomically,
+including mixed unions.
+
+## Verification
+
+Each CRuby version (3.3.6, 3.4.7, 4.0.1) passes **178 core tests / 885
+assertions** and **46 optional RBS tests / 433 assertions**, with zero failures,
+errors or skips. RBS signatures validate on all three. The locked default
+Ruby 4 bundle passes `rake`, including RuboCop's 98-file check. `bin/check`
+passes syntax, package and skill checks (2 tests / 76 assertions).
+
+Independent Luna specification and quality reviews approved the change.
+[Matrix records](pilots/finite-strings/matrix/) retain actual commands, outputs,
+statuses and library hashes. [Agent exercises](evaluations/finite-strings-skills.md)
+retain an old-guidance baseline and actual installed-package application runs.
+
+## Real-project value
+
+The [PStoreLogger pilot](pilots/finite-strings/README.md) preserves its original
+five source/test files. Its unchanged suite passes 7 tests / 23 assertions but
+exercises only 2/3 declared values: `"user_123"` is missing. Strict missing mode
+correctly exits 1 while the report preserves `tests_passed: true`.
+
+A separate test uses its README's custom-file-ID and collision rules to check
+`user_123.pstore`, `user_123_1.pstore`, and the stored payloads. The resulting
+suite passes 8 tests / 27 assertions and exercises 3/3 with intact collection.
+The original application and tests are unchanged.
+An independent evidence review confirmed the five source-file hashes, all 17
+runtime library hashes, matching scope/digest/obligation IDs, and distinct
+baseline/final run IDs.
+
+## Limits
+
+This covers explicitly enumerated scenarios, not the entire String domain or
+whole-method correctness. Other encodings, invalid text, String subclasses,
+patterns, length constraints, RBS strings, outputs and interaction coverage are
+outside this milestone. Outside-domain witness count remains bounded, but a
+retained string witness contains the full text, so there is no byte-size bound.
+The agent exercises are small guided tasks, not a general reliability estimate.

data/docs/implementation-status.md

@@ -0,0 +1,65 @@
+# First usable release implementation
+
+The [approved plan](../../../docs/superpowers/plans/2026-10-02-first-usable-release.md) is implemented inside this gem on branch `implement/first-usable-release` and recorded in the implementation commit containing this document. The gem remains unpublished. Verification below records local execution on 2026-10-02; GitHub Actions has been configured but has not been run remotely.
+
+## Scope and coordination
+
+- Core: explicit scalar input declarations, exact partition checks, `input-basics-v1`, deterministic human/JSON reports.
+- Runtime: bounded streaming input evidence for selected serial Ruby method calls; optional Minitest integration for >= 5.26.2 and < 5.28.0 with matching package/runtime minor versions.
+- Agent interface: two packaged skills, explicit offline export, isolated behavioral evaluations.
+- Existing development RuboCop/Rake tooling is retained; no new runtime dependencies.
+- Public namespace: `SpecProof`; preserve scaffold compatibility through `Specproof`.
+
+## Delivered work
+
+- Tasks 1–4: immutable scalar domains, trusted Ruby declaration loading, exact partition checks, shared `input-basics-v1` planning, human and JSON CLI reports.
+- Task 5: bounded TracePoint collection for directly owned public instance methods with named positional/keyword inputs, including optional parameters. Unsupported or duplicate resolved bindings, redefinition, and changed constant paths cannot produce complete evidence.
+- Tasks 6–7: streaming counters, whole-tuple input validation, positive versus unknown evidence, optional serial Minitest adapter with fresh run IDs and atomic reports, optional strict missing-obligation failure.
+- Task 8: [executable boundary workflow](../examples/age_policy/README.md), shipping and gap examples, [report contract](report-format.md), packaging, API signatures, compatibility checks, and [timing measurements](benchmark.md).
+- Task 9: two packaged skills, conflict-preserving explicit export, and [retained agent evaluations](evaluations/agent-skills-v0.1.md).
+
+Luna subagents implemented independent slices and reviewed specification conformance, runtime correctness, code quality, and evaluation outcomes. The implementation uses one shared obligation model rather than duplicating boundary logic in runtime coverage.
+
+## Acceptance evidence
+
+| Plan criteria | Evidence |
+| --- | --- |
+| A01–A04 | Loader/checker/planner tests cover unresolved and autoloaded target names, exact gap/overlap witnesses, large domains without enumeration, small-domain reference comparisons, and finite-value identity. |
+| A05–A06, A16 | Planner/coverage share obligations and IDs. CLI/report tests cover deterministic schema-versioned JSON, typed values, provenance, errors, and exit codes. |
+| A07–A11 | Collector/coverage/subprocess tests cover scope, method identity, invalid tuples, bounded retained evidence, interruption, changed definitions/constants, original failures/exceptions, strict mode, and unknown evidence. |
+| A12 | Shipped runner and workflow tests show passing tests with an age-18 gap, a meaningful assertion failing against the boundary bug, and the corrected implementation exercising all six unchanged obligations. |
+| A13–A14 | Local suites pass on CRuby 3.3.6, 3.4.7, and 4.0.1. Actual gem installation and CLI export work outside the checkout. Remote matrix execution remains unobserved. |
+| A15 | Packaged skill/reference validation, installed-gem export, idempotence, conflict preservation, symlink rejection, and paths containing spaces are tested. |
+| A17–A19 | All six scenarios passed two fresh attempts with the final skills (12 accepted outcomes), independently audited. Baselines, discarded attempts, final files, hashes, and real Codex client positive/negative discovery runs are retained. Small fixtures do not establish general agent reliability or a causal improvement rate. |
+
+## First implementation verification (commit fc876dd)
+
+- `bin/test`: **111 runs, 562 assertions, zero failures, errors, or skips**, separately on Ruby 3.3.6, 3.4.7, and 4.0.1.
+- Default `bundle exec rake` on Ruby 4.0.1: full suite and RuboCop pass; **81 files**, zero offenses.
+- `bin/check` from outside the checkout: syntax checks, skill/package tests (**2 runs, 66 assertions**), and gem build with its library present pass.
+- RBS 4.2.0 `rbs -I sig validate` passes. This validates declarations, not implementation type checking.
+- Five benchmark repetitions per mode preserve unchanged test bodies and exact 3/6 call counts; report hits match. No real-application overhead claim is made.
+
+### Minitest validation environment
+
+The locally available gem labeled Minitest `5.27.0` contained runtime version `5.26.2`. The adapter correctly rejects that mismatch. Validation used unmodified library files from the official `v5.27.0` source tag, packaged into an isolated temporary GEM_HOME. Neither global gems nor the runtime version constant were patched. Source archive SHA-256: `766c98a1d07df624320f69a013bd11994506eec930ce70964f87c7d2ee8a97c7`.
+
+That initial verification required both activated package and runtime versions to identify Minitest 5.27.x. The subsequent [compatibility change](minitest-compatibility.md) supports correctly labeled published 5.26.2 and removes the need for a source rebuild in the development bundle. Mismatched package/runtime minor versions remain rejected. Offline checking/planning and skill export do not need Minitest.
+
+## Installation and real-project pilot follow-up
+
+The normal development bundle now resolves published Minitest 5.26.2. Full suites pass with **115 tests and 573 assertions** on Ruby 3.3.6, 3.4.7, and 4.0.1. Ruby 3.3/3.4 checks used standard local Bundler installation from the checksum-verified published package, with unrelated ambient Ruby 4 gem paths cleared. No custom dependency source rebuild or version-constant patch was needed.
+
+The [real-project pilot](real-project-pilot.md) applied the updated exported skills to QualityGate's existing configuration tests. One default-key input gap was closed, moving scoped exercise from 7/8 to 8/8 with unchanged IDs/digest and a fresh report. All 143 copied source files remain unchanged. Two other real candidate methods were rejected because of optional keyword parameters and class-method syntax; three successful integrations were not demonstrated.
+
+Five baseline/instrumented timing pairs preserve the original 45-test, 342-assertion focused suite. The measured median subprocess difference was about 38 ms (12.5%); this is not a general application overhead claim. Source snapshots, package checksum, exact skills, test additions, reports, raw timings, and rejected probes are retained.
+
+## Limits and release follow-up
+
+The [optional-argument follow-up](optional-arguments-results.md) records support for effective scalar values after Ruby applies defaults and a scoped PStoreLogger adoption pilot. Reports explicitly state that argument presence is not observed. Earlier pilot rejections and archived skill bytes describe their original implementation cuts.
+
+This release checks explicit scalar input specifications and measures exercised input candidates; it does not prove implementation behavior or assertion quality. Declarations are trusted executable Ruby. Collection requires stable constant bindings and selected definitions in a serial same-process/thread window. Transient constant changes restored before final inspection are not detected.
+
+Sorbet/RBS importers, output contracts, inferred partitions, state machines, combinatorial criteria, SMT, parallel collection, and MCP remain deferred. API signatures do not constitute an RBS specification importer.
+
+The initial model evaluations preceded the final additive constant-binding guards and example-runner convenience changes; deterministic tests and review cover those changes. Their original skill bytes remain archived. Later live skill setup instructions reflect Minitest 5.26.2 compatibility and were freshly used in the focused real-project pilot. Remote CI, broader project adoption, and publishing remain release follow-up work. No gem was published and no branch was pushed.