specproof 0.1.0

data/skills/specproof-specify/references/usage.md

@@ -0,0 +1,265 @@
+# SpecProof command and report reference
+
+This reference targets SpecProof `0.1.x`, JSON schema `1`, and
+`input-basics-v1`. Confirm `specproof --version` and the report's
+`specproof_version`, but do not infer finite-string support from a `0.1.x`
+version alone. A fresh `plan` from the installed build must accept the
+declaration and report a typed string value; otherwise preserve the requested
+value and report that the build does not support it. Report unsupported
+versions or value kinds instead of guessing field meanings.
+
+Pairwise finite planning is opt-in and supported when the installed build
+accepts `--criterion pairwise-finite-v1`. The default remains
+`input-basics-v1`; verify the actual `criterion` in every report rather than
+inferring it from a package version. A pairwise plan requires a `combinations`
+group for every target. `pairwise-partitions-v1` is a separate opt-in criterion
+for complete, non-overlapping integer partitions crossed with finite values.
+It supports all-allowed groups and explicit whole-partition restrictions.
+
+Run commands from the application project and use its normal Ruby/Bundler
+environment:
+
+```sh
+specproof check spec/registration.rb --format json
+specproof plan spec/registration.rb --format json
+```
+
+For a mixed DSL/RBS declaration, repeat `--rbs FILE` for supplied RBS files
+and `--target 'Class#instance_method'` for each selected target. RBS requires
+at least one explicit target, and a target without an RBS file is an error.
+Keep both options the same across check and plan:
+
+```sh
+bundle exec specproof check spec/registration.rb --rbs sig/registration.rbs --target 'Registration#eligible?' --format json
+bundle exec specproof plan spec/registration.rb --rbs sig/registration.rbs --target 'Registration#eligible?' --format json
+```
+
+For an RBS-only contract, omit the positional DSL path and retain both explicit
+RBS options:
+
+```sh
+bundle exec specproof plan --rbs sig/registration.rbs --target 'Registration#eligible?' --format json
+```
+
+The DSL also accepts Ruby method objects for directly defined public methods
+on named classes and modules:
+
+```ruby
+SpecProof.define DeliveryOptions.instance_method(:build) do
+  input :quantity, range: 0..100
+end
+
+SpecProof.define DeliveryOptions.method(:build) do
+  input :quantity, range: 0..100
+end
+```
+
+Use a canonical string target such as `"DeliveryOptions#build"` or
+`"DeliveryOptions.build"` when checking/planning offline or when loading the
+owner would trigger autoload. Strings do not resolve the target. Use an
+`UnboundMethod`/`Method` object when the owner is already loaded and reflection
+is useful; target methods are not invoked. Equivalent forms normalize to the
+same canonical target, digest, and obligation IDs. Instance objects must be
+unbound; aliases, inherited singleton methods, anonymous owners, and methods
+bound to arbitrary instances are unsupported. RBS selectors remain explicit
+strings and can select `def self.method` on a named class or module. Reports
+retain string target identities, while source navigation depends on editor LSP
+support.
+
+`check` returns declared gap, overlap, empty-domain, and out-of-domain findings.
+It cannot decide which of two conflicting policies is intended. `plan` requires
+a specification with no semantic findings and uses the `input-basics-v1`
+criterion. It proposes domain endpoints, neighboring values, and declared
+partition boundaries; its output is a set of candidates for review.
+
+For finite joint scenarios, declare one `combinations` group per target and
+select `pairwise-finite-v1` explicitly:
+
+```ruby
+SpecProof.define "DeliveryOptions#build" do
+  input :expedited, values: [false, true]
+  input :notify, values: [false, true]
+  combinations :expedited, :notify, all_allowed: true
+end
+```
+
+`all_allowed: true` explicitly says every tuple is valid; it does not establish
+behavioral independence. Alternatively, use a nonempty block containing only
+requirement-backed `forbid` assignments. A partial assignment forbids every
+matching completion. Rules are data, never executable predicates. Never add a
+restriction just to remove a missing pair. A pair is required only if it has
+an allowed full assignment as a completion, so feasibility must account for
+all group inputs. A forbidden tuple with three inputs can still contain
+individually feasible pairs.
+
+The CLI form is
+`specproof plan PATH --criterion pairwise-finite-v1 --format json`. `check`
+does not accept a criterion. Pairwise plans require a group for every supplied
+target and reject oversized domains rather than sampling them.
+
+Use `pairwise-partitions-v1` only when every grouped integer range has
+`allow_gaps: false`, `allow_overlaps: false`, and explicit partitions, and every other
+grouped input uses finite values. The partitions form categories, and each
+finite value is a singleton category. Use `all_allowed: true` only when every
+full tuple is allowed; otherwise declare requirement-backed `forbid`
+assignments. Integer restrictions select a whole partition with
+`in_partition(:name)`, and finite inputs use exact values:
+
+```ruby
+combinations :age, :account, :country do
+  forbid age: in_partition(:minor), account: "business"
+end
+```
+
+Restrictions are partial assignments over full tuples. A pair is required only
+when an allowed full completion exists; a restriction involving a third input
+can exclude a pair indirectly. A forbidden runtime tuple fulfills no pair
+obligations. Integer restrictions cannot use raw values or partial ranges, and
+finite inputs continue to require exact values. The criterion reports category
+pairs, not boundary candidates or a claim of behavioral equivalence. Never add
+a restriction merely to erase a missing pair.
+
+```ruby
+SpecProof.define "AgePolicy#eligible?" do
+  input :age, range: 0..120, allow_gaps: false, allow_overlaps: false do
+    partition :minor, range: 0...18
+    partition :adult, range: 18..120
+  end
+  input :country, values: ["ro", "de"]
+  combinations :age, :country, all_allowed: true
+end
+```
+
+Run `specproof plan spec/age.rb --criterion pairwise-partitions-v1 --format json`.
+`check` remains criterion-independent.
+
+JSON reports use `schema_version: 1`. Check reports include `kind: "check"`,
+`contract_digest`, and `findings`. Plan reports include `kind: "plan"`, the
+same digest, `criterion`, and `obligations`. Every planned obligation has a
+stable `id`, target, input name, typed value, reasons, and source locations.
+Integer values are decimal strings inside a typed value object. Compare the
+digest when comparing reports; compare obligation IDs when linking tests to
+planned values. Re-run the current command before relying on old output.
+Finite strings add `{ "kind": "string", "value": "..." }` under schema 1.
+Consumers must handle this kind wherever typed values and witnesses occur.
+
+For `pairwise-finite-v1`, each obligation instead has an `inputs` object with
+two input names mapped to typed values; the row also has the shared stable ID,
+target, reasons, and source locations. Pair names are sorted canonically.
+`excluded_pairs` lists typed pairs with no allowed full completion, their
+`no_allowed_completion` reason, and relevant constraint sources. These pairs
+are excluded from the denominator. Runtime rows add status and hit counts to
+the planned pair fields. A forbidden runtime tuple satisfies no pair
+obligations. Keep pair coverage separate from test assertions and output
+correctness.
+
+For `pairwise-partitions-v1`, the `age` typed value is a category object, for
+example `{ "kind": "partition", "name": "minor", "lower": "0", "upper": "17" }`.
+Bounds are inclusive in the report. Other finite input values retain their
+ordinary typed value. A pair row therefore describes categories, not a set of
+boundary-value obligations. Runtime collection counts a call when its actual
+integer belongs to the declared category and its full assignment is allowed.
+The normalized constraint value used for the contract digest has a distinct
+canonical encoding, `{ "kind": "partition_reference", "name": "minor" }`;
+the existing partition obligation encoding is unchanged.
+
+Use only the declaration forms supported by SpecProof:
+
+```ruby
+SpecProof.define "Checkout#shipping" do
+  input :cents, range: 0..100_000, allow_gaps: false, allow_overlaps: false do
+    partition :standard, range: 0..4_999
+    partition :free, range: 5_000..100_000
+  end
+end
+```
+
+When finite-string support is present, enumerate exact text values with
+`values`, for example `values: [nil, 1, "user_123"]`. This is a finite scenario
+subset, not a model of all strings. Symbols and strings with the same spelling
+are distinct values. Only exact `String` instances containing valid UTF-8 or
+US-ASCII are accepted; 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. Values are not trimmed, case-folded, or
+Unicode-normalized. SpecProof owns frozen copies of declared strings and
+observed entry values, so mutating an application argument after method entry
+does not alter matching or freeze the application's string. A retained
+outside-domain string witness is full-sized even though witness count is
+bounded.
+
+Do not add inferred partitions to close a gap or remove an overlap. Explain
+the witnesses and ask for the intended policy.
+
+Successful check and plan reports both include
+`scope.completeness_scope: "analyzed_inputs"` and `scope.input_scope`. Each
+scope entry contains a target, its `analyzed_inputs` names, and any
+`excluded_inputs` with a name, reason, and declaration source. By default every
+named runtime parameter is analyzed. An intentionally partial contract must
+explicitly exclude every remaining named parameter with a reason and retain at
+least one analyzed input; there are no wildcards or implicit exclusions. For
+an RBS-selected target, DSL `input` and `exclude_input` names must match its
+signature. An exclusions-only DSL declaration is valid when supported finite
+inputs can be imported from RBS. A type-only unsupported input may be excluded
+only by an explicit declaration; an unsupported selected union remains an
+atomic error.
+
+The report digest represents normalized behavioral domains, partition
+policies, and sorted excluded names. Exclusion reason/source and declaration
+order do not affect it. No-exclusion digests and obligation IDs remain stable.
+It does not fingerprint all DSL source text, the full RBS signature, or
+implementation correctness. Provenance source objects require `path` and
+`line`; schema 1 permits additional fields, so consumers must tolerate unknown
+fields. A source's `kind` identifies its family but does not change obligation
+identity. Read the coverage reference for runtime `declaration_sources` and
+collection scope; offline check/plan scope describes the declaration and does
+not attest runtime binding or that tests loaded.
+RBS string literals, finite unions of supported literals, and optional literal
+forms provide exact finite scenarios without duplicate DSL inputs. Unrestricted
+RBS `String` and selected unions containing unsupported members fail atomically.
+Return types are ignored and do not supply expected behavior. Verify support
+with a fresh plan; do not infer it from `0.1.x`.
+
+## Pairwise suggestions
+
+After an intact runtime coverage report records missing pair obligations, ask
+SpecProof for allowed group assignments with:
+
+```sh
+specproof suggest spec/delivery.rb --report tmp/coverage.json --format json
+specproof suggest --rbs sig/delivery.rbs --target 'Delivery#build' spec/delivery.rb --report tmp/coverage.json --format json
+```
+
+There must be exactly one nonempty `--report`. The command infers its criterion
+from the validated coverage report and rejects `--criterion`; it does not add
+a new default to check or plan. It uses `greedy-pairwise-v1` for
+`pairwise-finite-v1` and `greedy-partition-pairwise-v1` for
+`pairwise-partitions-v1`. It replans the supplied current declarations, then
+checks schema 1, `kind: "coverage"`, the pairwise criterion, digest, exact
+target and analyzed/excluded/group scope, exact typed
+obligation denominator, row statuses/hits, counters, and missing/exercised
+projections. The report must be completed, intact, free of errors and
+incomplete reasons, and have no unknown observations. `tests_passed` must be a
+Boolean; `false` is retained as the actual test outcome rather than rejected.
+Filtered reports are usable only for their recorded scope.
+
+The output retains `source_run_id`, `source_tests_passed`, and `source_scope`.
+It marks `assignment_scope: "combination_group"` and
+`minimality: "not_guaranteed"`. Each suggestion has a typed full group
+assignment and `covers` lists only newly covered missing IDs. The rows' union
+must equal the source missing set. `unassigned_inputs` lists every analyzed
+parameter outside the group and every explicitly excluded parameter; the
+caller remains responsible for supplying those values. Runtime evidence still
+requires all analyzed inputs to be valid.
+
+For a partition pair, the typed plan contains category names and bounds, while
+the suggestion contains an ordinary concrete integer using that category's
+lower endpoint. It is a representative call value only; it does not establish
+boundary coverage or expected behavior.
+
+No candidate is executed and no expected output is inferred. Use a separate
+requirement as the assertion oracle before writing an assertion. The digest
+does not fingerprint implementation or test files; rerun the intended suite in
+a fresh process after either changes and inspect its new run ID and result.
+Generation rejects reports over 32 MiB and work over 10,000 cumulative full
+assignments, 10,000 cumulative possible pair rows, or 1,000,000 candidate-to-pair
+memberships. It never truncates or returns partial suggestions.

data/skills/specproof-test-gaps/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: specproof-test-gaps
+description: Finds untested SpecProof input obligations and adds evidence-backed Minitest coverage for Ruby methods. Use when reviewing boundary or pairwise gaps, integrating SpecProof with Minitest, suggesting allowed assignments, or verifying a fresh coverage report.
+---
+
+# Find and close SpecProof test gaps
+
+Use SpecProof plans to find candidate inputs missing from a Minitest suite.
+Use an independent requirement or trusted existing test as the expected-result
+oracle. SpecProof observes method calls; it does not inspect assertions, replay
+tests, infer expected results, or prove application correctness.
+
+## Workflow
+
+1. Read the request, independent behavior requirements, target method, current
+   tests, and the input specification. Confirm that the canonical target
+   (`Owner#method` for an instance method or `Owner.method` for a class/module
+   singleton method) and parameter names match the real method signature.
+   Default scope is strict: every named
+   parameter is analyzed. If the task deliberately covers only some inputs,
+   every other name must have an explicit `exclude_input :name, reason: "..."`
+   declaration, and at least one input must remain analyzed. Do not introduce
+   exclusions to make findings, missing obligations, or a strict run disappear.
+2. Create or validate the intended input declaration before measuring coverage.
+   Run `specproof check PATH --format json`, then
+   `specproof plan PATH --format json`; inspect findings, errors, digest, and
+   input scope. Resolve or report every finding. Do not change domains,
+   partitions, or exclusions merely to make a check or report green. Ask before
+   changing the declared contract when its intent is uncertain. Record each
+   candidate's stable obligation ID, value,
+   and source locations, plus every excluded input and its reason. A plan's
+   candidate set covers only its analyzed inputs.
+   For a finite-string scenario such as `values: [nil, 1, "user_123"]`, keep
+   each value and type exactly as required; `"user_123"` and `:user_123` are
+   distinct. Use finite strings only after a fresh plan reports a string value.
+   Do not infer support from `0.1.x`, and do not drop or relabel a required
+   string to obtain a valid report. If the installed build rejects a required
+   string, report that unsupported value rather than substituting a symbol or
+   omitting it.
+   Use `input-basics-v1` for marginal input candidates unless requirements
+   explicitly describe finite joint scenarios. For pairwise coverage, opt in
+   with `--criterion pairwise-finite-v1` and require a `combinations` group
+   for every target. `all_allowed: true` is an explicit claim that every tuple
+   is valid, not a claim of behavioral independence. A `forbid` clause must
+   come from a requirement; never add one to erase a missing pair. Pair
+   feasibility depends on an allowed full assignment, including all other
+   group inputs. For bounded integer inputs, use `pairwise-partitions-v1` only
+   when each grouped range has an explicit complete, non-overlapping partition
+   and all other grouped inputs are finite values. Use `all_allowed: true` only
+   when every full tuple is allowed; otherwise encode stated restrictions with
+   a nonempty block of `forbid` assignments. Integer selectors must use
+   `in_partition(:name)` for a whole declared partition; finite inputs require
+   exact values. Pair feasibility depends on whether any allowed full
+   completion exists, including the values of other group inputs. A call that
+   matches a forbidden assignment contributes no pair coverage. Never change
+   restrictions to remove a missing pair. Explicit partitions on finite-valued
+   inputs remain unsupported. This criterion counts category pairs, not
+   boundary candidates or inferred behavior equivalence. Use `allow_gaps: false` and
+   `allow_overlaps: false` to require that grouping. Omitted options allow
+   gaps/overlaps. When migrating legacy specifications, invert the booleans:
+   `exhaustive: true` becomes `allow_gaps: false`, and `disjoint: true` becomes
+   `allow_overlaps: false`. Do not weaken either policy to close a reported gap.
+3. Before editing tests or production code, run the intended current suite in a
+   fresh process and capture its coverage report as the baseline. Check its run
+   ID, digest, input scope, completion, integrity, and original test result.
+   Use an intact report to identify existing input evidence; an incomplete
+   report cannot establish a baseline gap. Preserve the baseline result as
+   recorded, including `tests_passed: false` when the current suite fails.
+   For pairwise runs, compare the exact planned pair IDs and typed assignments.
+   Partition-pair rows identify category names and bounds; a suggestion uses a
+   lower-endpoint input representative. That input is not a behavioral oracle
+   or a boundary-coverage claim.
+   A method call can satisfy only pairs present together in that valid tuple;
+   evidence from separate calls is never combined into a synthetic pair.
+4. For each uncovered value, derive its expected result from an independent
+   normative requirement or source document. A trusted existing test can
+   preserve the exact case it states, but cannot establish a general boundary
+   rule from one example. If there is no oracle, ask a precise question and do
+   not invent an assertion. A candidate value alone does not say what the
+   method should return.
+5. Add a meaningful assertion for each agreed gap. Keep the obligation ID and
+   the normative requirement/source location beside the assertion, such as in
+   its failure message. Identify the implementation method as the code under
+   test, not as the source of expected behavior. Preserve every existing domain
+   obligation unless an independently justified requirement change is explicit.
+6. Change production behavior only when the task explicitly authorizes a
+   behavior fix. For an authorized fix, add the failing regression assertion
+   and capture its failure against the current implementation before making
+   the smallest requirement-backed change. For a test-only or review task,
+   preserve production code and existing assertions; keep and report a failing
+   regression with `tests_passed: false` when the requirement exposes an
+   unresolved defect.
+7. Rerun the intended test command in a fresh process after the final source or
+   test edit. Collection observes calls made during that run only; a previous
+   report cannot establish fresh coverage. Verify the newly written report has
+   a new `run_id`, the current `contract_digest`, input scope, and obligation
+   IDs. Confirm its completion, integrity, actual test result, and
+   `scope.targets`, `scope.declaration_sources`, run arguments, and filters
+   match the actual test command and loaded test files. `scope.targets` and
+   `scope.declaration_sources` are runtime coverage fields; offline check and
+   plan results do not have them. If a source changes, run the suite again and
+   inspect a fresh report. Compare `scope.completeness_scope` and
+   `scope.input_scope` with both the current plan and the actual named runtime
+   signature; matching obligation IDs alone do not establish that the analyzed
+   scope is the same. Human summaries must disclose excluded names and reasons.
+   `100%` means all obligations for analyzed inputs were exercised; it says
+   nothing about excluded values or behavior, outputs, interactions, or complete
+   method correctness. A matching digest does not fingerprint all source text,
+   the full RBS signature, or implementation correctness. Report the actual
+   `tests_passed` value and any unresolved finding. Never narrow or exclude
+   inputs, weaken strict missing policy, or alter production behavior just to
+   turn a failing result green.
+
+For a pairwise baseline, you may use `specproof suggest PATH --report FILE`
+after checking the report against a fresh plan with the criterion named in the
+coverage report. `suggest` infers that criterion and accepts no `--criterion`
+option. Suggestions require a completed, intact report with exact typed obligations, current digest and
+declared scope, consistent rows and projections, no errors or unknowns, and a
+Boolean original `tests_passed` value. A failing test result is accepted and
+preserved. A filtered report supports only its recorded scope. Do not infer
+freshness from the digest: it does not include implementation or test bytes,
+so run the intended suite again after changes.
+
+Treat each row as an unexecuted, allowed full assignment for the combination
+group. Its `covers` field lists missing pair IDs newly covered by that row;
+the output has no expected result. Inspect `unassigned_inputs`, which lists
+analyzed inputs outside the group and every explicitly excluded parameter,
+then supply valid values for those names. Every analyzed input must be valid
+before runtime pair evidence counts. Use the independent normative
+requirement to write assertions; never generate expected values from the
+implementation or the suggestions. Never add exclusions or `forbid` clauses
+to erase a gap or make a report green.
+
+When testing a pairwise interaction, derive the expected output from an
+independent rule for each combination. A pair coverage hit says only that the
+input combination reached the method. Keep the baseline, any newly failing
+requirement-backed assertion, and any corrected implementation run in separate
+fresh processes, with a fresh report and run ID for each. A passing pairwise
+report and passing assertions establish evidence only for the declared inputs
+and assertions; they do not prove exhaustive tuple coverage or behavioral
+independence. `pairwise-partitions-v1` records whether an observed value belongs
+to a declared category. It does not prove that all values in that category
+behave alike or that a category pair was tested at its boundaries. Derive each
+expected result from an independent requirement.
+
+For adapter setup, report fields, and evidence checks, read
+[the bundled coverage report reference](references/usage.md).
+
+## Minitest adapter setup
+
+Use canonical string targets for offline planning and when the application
+owner may not be loaded; strings do not resolve or autoload that owner. Use
+`Owner.instance_method(:name)` or `Owner.method(:name)` when code is already
+loaded and a method object is useful. These use reflection without invocation
+and are accepted only for directly defined public methods on named classes or
+modules. Unbound instance methods identify their defining class. Aliases,
+inherited singleton methods, anonymous owners, and methods bound to arbitrary
+instances are unsupported. Recheck object targets against the current direct
+definition when declaring them. Equivalent strings and method objects share
+canonical string report targets and obligation IDs. Navigation from a target
+name depends on the editor's language server. For live collection, require the
+application code before installing the adapter. Method objects and matching
+digests say nothing about returned values; derive assertions from the
+independent requirement and collect a fresh report after any implementation,
+specification, or test change.
+
+Keep Minitest in the application's test environment and use the supported
+version range `>= 5.26.2` and `< 5.28.0`, with matching package/runtime major
+and minor versions. Prefer `~> 5.26.2` for ordinary published packages.
+Require application code and Minitest before installing the
+adapter. Install it once in the suite entrypoint:
+
+```ruby
+require "minitest/autorun"
+require "registration"
+require "specproof/minitest"
+
+SpecProof::Minitest.install!(
+  specifications: ["spec/registration.rb"],
+  output: "tmp/specproof-coverage.json",
+  fail_on_missing: false
+)
+```
+
+Use `fail_on_missing: false` when first adding the adapter to a suite with no
+established missing-obligation policy, so gaps can be reported without changing
+the suite's existing pass/fail behavior. Preserve an existing
+`fail_on_missing: true` policy; the adapter still writes its report when
+unobserved obligations make the run fail. Never disable that strict policy just
+to obtain a green result. Use the report to decide whether gaps remain; a
+passing suite alone does not close them. Keep independent input scope intact;
+do not exclude an input simply because it has missing obligations or a
+non-primitive value.
+
+RBS supplies input types only. It does not supply expected return values or
+behavioral output assertions. Derive each assertion from an independent rule
+or trusted stated requirement. A coverage candidate or a successful hit
+establishes only that an input obligation was exercised; it does not establish
+the expected result or prove correctness.
+
+Finite strings are explicitly enumerated text scenarios, not open-ended String
+coverage. A supported build accepts only exact String instances containing
+valid UTF-8 or US-ASCII text (canonicalized to UTF-8); empty strings,
+whitespace, Unicode, and embedded NUL are valid. Invalid bytes, other encodings,
+and String subclasses are rejected. No trimming, case folding, or Unicode
+normalization occurs. SpecProof copies and freezes owned declaration and
+method-entry snapshots without freezing application values; post-entry
+mutation cannot change matching. A direct Coverage observation likewise owns
+retained strings. Outside-domain string witnesses retain the full string even
+though only a bounded number of witnesses are retained. Explicitly selected
+RBS string literals and finite unions of supported literals provide exact
+scenarios; unrestricted RBS `String` and unions containing unsupported members
+remain unsupported and fail atomically. Verify support from a fresh plan; do
+not infer it from `0.1.x`.