rigortype 0.4.7 → 0.4.8

data/skills/rigor-ask/SKILL.md

@@ -130,6 +130,7 @@ A good hand-off is two or three sentences of orientation plus the pointer:
 - baseline reduction → **`rigor-baseline-reduce`** · coverage holes → **`rigor-protection-uplift`**
 - a missing gem/DSL → **`rigor-plugin-author`** · monkey-patch clusters → **`rigor-monkeypatch-resolve`**
 - about to *write* a type (RBS, `#:`, a Sorbet `sig`, a YARD tag, a doc sentence) → **`rigor-type-oracle`**
+- auditing, fixing, or contributing RBS declarations (a gem's `sig/`, a gem_rbs_collection entry) → **`rigor-rbs-contract`**
 
 When in doubt, give less and point — it respects the user's "three skills
 to remember" promise and keeps each answer to the part only `rigor-ask`

data/skills/rigor-project-init/references/01-detect.md

@@ -56,6 +56,7 @@ bundle exec rbs collection install
 Use `bundle exec` when `rbs` appears in `Gemfile` or `Gemfile.lock`
 (the common case — Steep / rbs_rails workflows put it there). If `rbs`
 is not in the Gemfile, use the bare `rbs collection install` instead.
+If `bundle exec rbs` runs an `rbs` that `gem:rigortype` put on `PATH` instead of the project's, see the [install guide's note on `rbs` shadowing](https://github.com/rigortype/rigor/blob/master/docs/install.md#case-a--mise-is-available-recommended).
 
 Ask the user for permission before running, since this installs files
 into `.gem_rbs_collection/` (a generated directory that belongs in

data/skills/rigor-project-init/references/03-baseline-and-bugs.md

@@ -170,6 +170,8 @@ bundle exec rbs collection install   # if rbs is in Gemfile
 # or: rbs collection install
 ```
 
+If `bundle exec rbs` runs an `rbs` that `gem:rigortype` put on `PATH` instead of the project's, see the [install guide's note on `rbs` shadowing](https://github.com/rigortype/rigor/blob/master/docs/install.md#case-a--mise-is-available-recommended).
+
 Re-run `rigor triage`. If the `gem-without-rbs` count drops, carry
 the new, smaller count into Phase 7.
 
@@ -397,7 +399,9 @@ information and Rigor has no built-in coverage. In order:
 
 1. `bundle exec rbs collection install` (bare `rbs collection install`
    if `rbs` is not in the project's Gemfile) — pulls community RBS for
-   the gem if it exists. Re-run triage afterwards.
+   the gem if it exists. Re-run triage afterwards. If `bundle exec rbs`
+   runs a `gem:rigortype` `rbs` instead of the project's, see the
+   [install guide's note on `rbs` shadowing](https://github.com/rigortype/rigor/blob/master/docs/install.md#case-a--mise-is-available-recommended).
 2. `dependencies.source_inference:` in `.rigor.dist.yml` — opt the
    gem into Rigor inferring `Dynamic`-typed returns from its source.
 3. If the gem is widely used and genuinely warrants first-class

data/skills/rigor-project-init/references/06-agent-contract.md

@@ -28,13 +28,13 @@ rigor skill --full rigor-type-oracle
 ```
 
 Its `references/02-agents-md-fragment.md` section carries the paragraph
-and the five bullets. Copy that block **verbatim** — including its
+and the six bullets. Copy that block **verbatim** — including its
 single-long-line shape, which is deliberate (some renderers turn a
 newline inside a paragraph into a line break).
 
-Do not paraphrase it from memory, and do not shorten it: the five bullets
+Do not paraphrase it from memory, and do not shorten it: the six bullets
 are the load-bearing part — expression, method signature, parameter,
-the gap rule, and provenance.
+the gap rule, provenance, and the declared-`void` contract.
 
 ## Where it goes
 
@@ -44,7 +44,7 @@ the gap rule, and provenance.
 | Only `CLAUDE.md` exists | Append it there. |
 | Both exist | Put it in `AGENTS.md`. Add `@AGENTS.md` to `CLAUDE.md` only if it is not already pulled in. |
 | Neither exists | **Create `AGENTS.md`** with this as its first section. |
-| A types / type-checking section already exists | Merge into it; keep the five bullets intact. Never write a second, competing rule. |
+| A types / type-checking section already exists | Merge into it; keep the six bullets intact. Never write a second, competing rule. |
 
 Never overwrite unrelated content. If the project already states a rule
 about type authorship that contradicts this one, stop and show the user

data/skills/rigor-rbs-contract/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: rigor-rbs-contract
+description: >-
+  Audit, repair, and extend RBS declarations as contracts — a gem's own `sig/`, an application's `sig/`,
+  or a gem_rbs_collection entry — by checking each one against Rigor's inference and the library's
+  documented behaviour, then proving and explaining the change. Use when correcting or contributing RBS;
+  not for sourcing one type mid-task (`rigor-type-oracle`) or raising `coverage --protection` numbers.
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor RBS Contract
+
+An RBS declaration is not a record of what a method happens to return. It is a promise about what
+callers may rely on. Ruby returns every method's last expression, so inference always finds *some*
+type; whether callers may depend on it is a choice only a declaration makes. This skill turns that into
+a repeatable loop: find where declarations and code disagree, decide which side is wrong on cited
+evidence, change the declaration, prove the change, and explain it so a reviewer can re-check it.
+
+## First: load the version-current copy
+
+Commands, flags, rule ids and skip-reason ids drift between Rigor releases, so follow the copy that
+ships with the **installed** Rigor rather than a vendored or frozen copy of this file:
+
+```sh
+rigor skill --full rigor-rbs-contract   # this body + all its references/, inline
+```
+
+If you already loaded it via `rigor skill`, proceed. If `rigor` is not on `PATH`, run
+**`rigor-next-steps`** first.
+
+## When to use
+
+- A gem author wants their shipped `sig/` checked, corrected or extended.
+- An application's quality owner wants the RBS their `rigor check` relies on — the project's `sig/`, or
+  a dependency's community RBS — audited, or a wrong dependency signature fixed.
+- Someone is contributing to `ruby/gem_rbs_collection`: adding methods, fixing a declaration, or acting
+  on a discrepancy Rigor surfaced.
+- A diagnostic or a review comment says "the RBS says X but the code does Y", and the task is to settle
+  which one is right.
+
+## When NOT to use
+
+- **Writing one type in the middle of another task** → `rigor-type-oracle`. It owns where a single type
+  comes from; this skill owns what a set of declarations should promise.
+- **Raising `rigor coverage --protection` numbers** on the project's own code → `rigor-protection-uplift`.
+- **Installing community RBS** that exists but is not set up → `rigor-rbs-setup`.
+- **A Rigor diagnostic you believe is wrong about correct code** → `rigor-ask`; that is an engine
+  question, not a contract one.
+
+## The two rules
+
+**Contract rule.** Inference proves what a body does. It may *refute* a declaration, or fill a slot
+nobody declared, but it never chooses the abstraction a declaration makes. A contract the body does not
+prove is written only on the word of the party entitled to make it, and cited: the library's own
+documentation for code you do not own, the owner's explicit answer for code they do.
+
+**Direction rule.** Making a declaration *say less* — a return that admits `nil`, a parameter that
+accepts more — needs a **witness** that the case is real: a call shown, by RBS's own runtime type checker,
+to return or to need what the old declaration excludes; or the library's documentation. Rigor's findings
+locate these cases and name the exit to aim at, but they have false positives, so on their own they are
+a lead, not a witness. **A witness counts only once its negative control has failed**: break the
+declaration on purpose and confirm the same run reports a type error. RBS's checker silently skips
+some declarations (one inherited from a module or superclass by a class that defines the method itself
+is never checked), so a clean run means nothing until the broken one fails. Making it *say more* — a narrower return, a narrower parameter, `void` replaced by
+a value — needs a contract source. A `sig-gen` proposal counts only where the slot was undeclared or
+`untyped`.
+
+Five consequences come up on almost every run:
+
+- **`void`, `boolish` and a deliberately wide nominal stand** unless the library documents a value.
+  The body returning something is not documentation.
+- **A new declaration is where that choice is made.** A `sig-gen` proposal for an undeclared method
+  that is a literal (`-> 0`, `-> false`), an empty collection (`-> {}`), `nil`, or the incidental value of
+  a procedure's last statement becomes `void` (`bool` for a predicate) unless the documentation names
+  the value. Adopting it would create the contract the `void` rule protects.
+- **Reading the implementation finds candidates; it does not decide them.** The one exception is an
+  undeclared or `untyped` parameter's structural need — an argument used only through `to_s` accepts
+  `_ToS`. A *declared* parameter is a promise too; today's body is no reason to widen it.
+- **A wholly wrong declaration is treated as missing.** When the declared type and the body share
+  nothing (declared a connection pool, returns an `Integer`), it is neither saying less nor more: type
+  the slot as if it were undeclared, and witness that the declared type never comes back.
+- **One alias that is both input and output carries two contracts.** When they differ, split it rather
+  than weaken it until both fit.
+
+The full decision table, with the evidence each change needs and the shapes that look like findings but
+are not: [`references/02-contract-rules.md`](references/02-contract-rules.md).
+
+## Step 0 — Pick the target; it decides who has authority
+
+| Target | Who decides a contract | Mode | Reference |
+| --- | --- | --- | --- |
+| The project's own code — a gem's `sig/`, an application's `sig/` | the owner | **interactive**: batch the open contract questions and ask | [`03-target-own-code.md`](references/03-target-own-code.md) |
+| A gem you do not own — a gem_rbs_collection entry, or a local override of one | the gem's documentation | **autonomous** up to a finished branch and description; undocumented contracts are left alone and listed; pushing and opening the pull request wait for the user's go-ahead | [`04-target-gem-rbs-collection.md`](references/04-target-gem-rbs-collection.md) |
+
+An application whose wrong signature comes from a dependency's community RBS is the second row: fix it
+upstream, and keep a local override only until the fix is released.
+
+Either target may be a **new declaration set** rather than an audit: a gem with no RBS anywhere, or a
+new collection entry. Then there is nothing to compare against, the skeleton (mixins, attributes,
+aliases, metaprogrammed methods) does not come from `sig-gen`, and most decisions are about
+undocumented proven slots and blocks. The reference for the target has a "New declaration set" section.
+
+## The loop
+
+1. **Find.** Collect candidates from Rigor and from the documentation, not from a read-through. How,
+   per signal, and what each one can and cannot see:
+   [`references/01-finding-candidates.md`](references/01-finding-candidates.md).
+2. **Triage.** Drop the shapes that are not contract findings — abstract methods, mutable registries
+   proposed as `[]`, platform-guarded files, a `Dynamic` inference, a memoised value Rigor reads as
+   nilable — before spending evidence on them.
+3. **Decide.** For each remaining candidate, gather the evidence the direction rule asks for and cite
+   it: the witness call and the error it raised, the command and its output, the quote with its
+   `file:line` in the version under review, or the owner's answer. A candidate without the evidence it
+   needs is not changed; it is reported.
+4. **Write.** Change the declaration. Prefer `rigor sig-gen` output verbatim where it applies; write by
+   hand only what the evidence supports, and nothing beyond it.
+5. **Prove.** Run the target's gate. For every change that says less, keep the runtime witness: the
+   call fails RBS's type checker under the old declaration and passes under the new one. Before trusting
+   any clean run — one witness or a whole test suite — run the declaration-mutation pass: break each
+   method's return in turn and list the ones no run notices. Those returns are unchecked, whatever the
+   suite says (parameters and attributes are not covered by the pass). How: [`references/05-declaration-mutants.md`](references/05-declaration-mutants.md). Add
+   a use-site test that exercises the new contract — a `nil` check on a newly optional return, a call
+   with the newly accepted argument.
+6. **Explain.** Every change carries its evidence. Every Rigor finding and every candidate you
+   deliberately left alone — above all a `void` whose body returns a value, and a Rigor finding no
+   witness confirmed — carries its reason, so a reviewer can tell restraint from oversight.
+
+## Done when
+
+Every candidate from step 1, including every row Rigor reported, is changed with its cited evidence,
+left alone with its reason, or reported as an open question; the target's gate is green; every
+declaration the mutation pass left surviving is named in the write-up as unchecked at runtime; and the
+write-up lists all three groups.
+
+When the owner does not answer an open question, or the documentation cannot be found, stop there: leave
+those declarations as they are, finish and prove the changes the evidence did settle, and hand back the
+open list. Never resolve an open question by picking the option the body happens to match.
+
+## Gaps are findings here too
+
+When Rigor answers `Dynamic[top]`, `untyped`, or skips a method, that is not permission to fill the
+slot from your reading — `rigor-type-oracle`'s gap protocol applies unchanged. What this skill adds is
+the other source: where the library documents the contract, the documentation fills the slot, with the
+quote. Where neither speaks, the slot stays as declared.

data/skills/rigor-rbs-contract/references/01-finding-candidates.md

@@ -0,0 +1,212 @@
+# 01 — Finding candidates
+
+A candidate is a declaration that may promise the wrong thing, or a public method that promises nothing
+because it is not declared. Collect them from the signals below, record the command that produced each,
+and only then decide anything. Every signal sees part of the picture; the table at the end says which
+part.
+
+All commands run with the RBS under review on Rigor's signature path and the library's source as the
+analysed paths. How to arrange that for each target: [`03-target-own-code.md`](03-target-own-code.md),
+[`04-target-gem-rbs-collection.md`](04-target-gem-rbs-collection.md).
+
+## Signal 1 — `rigor check` over the library's own source
+
+```sh
+rigor check --no-baseline --format=json lib
+```
+
+The rule to look for is **`def.return-type-mismatch`**: the body's last expression has a type the
+declared return does not accept. Its message names both sides — `declared String, inferred String?`, or
+a literal such as `inferred "a"?`. It compares a union member by member, so a typed member beside
+`Dynamic` still counts: sidekiq 7.0's `Client#push` against its old `-> String` reports
+`declared String, inferred Dynamic[top]?`. `--no-baseline` matters in an application: a baseline may
+already be hiding exactly these.
+
+A mismatch is a **lead**, not a witness. The rule has false positives: a memoised value re-read after a
+`yield` (`@c ||= Chain.new(self); yield @c if block_given?; @c`) reads as `Chain?` although it can
+never be `nil` — sidekiq's `Config#client_middleware` is that shape. A mismatch becomes a change only
+with a runtime witness (Signal 6) or documentation.
+
+Also worth reading here: `def.override-return-widened` (a subclass's declaration widens what its parent
+promised). `static.value-use.void` (code uses a value a declaration says is `void`) is off in every
+profile and fires only under the `use-of-void-value` bleeding-edge feature, so its silence proves
+nothing.
+
+What it cannot see: only the **last expression** is compared. An explicit `return nil` earlier in the
+body, or a falsy arm behind an untyped value (`mime && new(mime[0])` where `mime` is untyped reads as
+`Dynamic[top] | Marcel::Magic`), produces no diagnostic. The rule is also silent when the declared return
+is `untyped` or `void`, and when the whole inferred type is `Dynamic`.
+
+## Signal 2 — `rigor sig-gen --diff` against the declarations
+
+```sh
+rigor sig-gen --diff --format=json lib
+```
+
+Each entry in `candidates` has a `classification`:
+
+| `classification` | Meaning | What it is evidence for |
+| --- | --- | --- |
+| `new_method` | a public method with no declaration; `rbs` is the proposal | filling an undeclared slot — adopt the proposal verbatim, or leave the method out |
+| `tighter_return` | Rigor proved a return narrower than `declared_return_rbs` | over `untyped`: an adoptable proposal. Over anything else: a "say more" change, which needs a contract source — the proposal alone is not enough |
+| `skipped` | no proposal; `skip_reason` says why | nothing — see triage below |
+
+`sig-gen` never proposes over a declared `void` and never tightens a declared nominal to a literal. It
+also compares a declaration that is *narrower* than the body over every exit — an early `return nil`
+included — but classifies the result `equivalent`, which `--diff` does not print (#3062). So an empty
+`--diff` does not mean the declarations are sound; Signal 1, the leads below and Signal 6 cover that
+half.
+
+Private and protected methods are skipped unless you pass `--include-private`; a collection entry rarely
+wants them.
+
+`sig-gen` writes method signatures and nothing else: no `include` / `extend`, no `attr_*`, no `alias`, no
+constants, and no method that only exists through metaprogramming (`define_method`, `class_eval` strings).
+Readers come back as `untyped-return` skips rather than `attr_reader` lines. Some methods are also
+absent without a skip row (#3068). So for a new declaration set its output is the types, not the
+skeleton: see the target reference's "New declaration set" section.
+
+## Signal 3 — `rigor check` over code that uses the library
+
+Use-site code is where an input contract shows up: the project's own callers, the gem's `spec/` or
+`test/`, or a collection entry's `_test/`.
+
+```sh
+rigor check --no-baseline --format=json <use-site paths>
+```
+
+Read each finding against the question "is this call correct Ruby that the library accepts?":
+
+- **`call.argument-type-mismatch` on a call the library accepts** — the declared parameter is too
+  narrow. retryable's `{ sleep: 3.2 }` failed because one record type required all ten keys.
+- **`call.undefined-method` on a method the library defines** — a missing declaration.
+- **`call.possible-nil-receiver`** — usually the declaration is right and the caller is wrong; check
+  before "fixing" the RBS to silence it.
+
+A use-site diagnostic can also be a Rigor false positive. If the call is correct and the declaration is
+correct too, reproduce it minimally and route it through `rigor-ask`; do not bend the RBS around it.
+
+## Signal 4 — `rigor type-of` on a returned value
+
+```sh
+rigor type-of lib/foo.rb:LINE:COL
+```
+
+Point it at the returned *value*, not the `return` keyword: in `return nil unless ok`, the column of
+`nil` answers `nil`, while the column of `return` answers `bot` (the statement itself never produces a
+value). Use it to confirm or rule out a lead. `String?` is proof. `Dynamic[top] | Foo` means one arm is unknown —
+the declaration may or may not be right, and the decision needs documentation or a run.
+
+## Leads from reading — locate only
+
+These are worth searching for because no command reports them, but each is a lead, not evidence. A
+lead becomes a change only with documentation or a witness (Signal 6).
+
+- an explicit `return` or `return nil` before the last expression;
+- `x && y`, `x&.y`, or `find`/`detect`/`Hash#[]` whose `nil` result is returned as is;
+- `rescue … nil` or a `rescue` clause whose value is returned;
+- a method whose declaration is `void` but whose doc comment describes a return value (the reverse
+  case: the declaration may be too wide, and the documentation is the evidence).
+
+## Signal 5 — the documentation
+
+Read the documentation that ships with the version under review — doc comments and the README in that
+version's source — as its own sweep, not only to confirm a lead, and note each quote's `file:line`. A
+website or wiki describes some other release; see `02-contract-rules.md` for what it may support.
+
+- doc comments containing "Returns", "nil", "or", "raises", "yields";
+- the README's examples, which show which calls the authors consider the public API;
+- the API reference, for public methods the RBS does not declare.
+
+A documented return that the declaration contradicts is a candidate even when every Rigor signal is
+silent. For sidekiq's `Client#push`, Signal 1 found the candidate and the doc comment — "If middleware
+stops the job, nil will be returned instead" — settled it.
+
+## Signal 6 — a runtime witness
+
+RBS ships a runtime type checker. It wraps the methods of the classes you name, runs your Ruby, and
+reports every argument or return value that does not match the loaded declarations. A call it rejects
+is a **witness**: the evidence a "say less" change needs, and the way to tell a real Rigor finding from
+a false positive. This **executes the library's code with the user's privileges**. For the project's
+own code or a gem already in the user's bundle that is the same trust as running its tests. For any
+other gem, run it in a container or VM, or ask the user before executing it.
+
+Write a short script that calls the method with an input aimed at the exit Rigor or your reading
+pointed to — for `return nil unless carrier_accepts?(parcel)`, a parcel the carrier rejects:
+
+```ruby
+# witness.rb
+require "courier"
+Courier::Client.new.deliver(Courier::Parcel.new(2, 50))
+```
+
+```sh
+RBS_TEST_TARGET='Courier::*' RBS_TEST_OPT='-I sig' ruby -I lib -rrbs/test/setup witness.rb
+# [Courier::Client#deliver] ReturnTypeError: expected `::String` but returns `nil`
+```
+
+Under Bundler, run the same line as `bundle exec ruby -I lib -rrbs/test/setup witness.rb`. Do not add
+`-rbundler/setup` instead: when Bundler switches versions it re-executes Ruby without `-I` and `-r`, the
+script fails to load, and the non-zero exit looks like a witness. When the target's bundle does not
+contain `rbs` (a gem's own `Gemfile` usually does not), run plain `ruby` with `GEM_PATH` naming both the
+directory where the target's gems are installed and one where `rbs` is installed. Add `-r <library>` to
+`RBS_TEST_OPT` for each standard library the declarations use.
+
+A witness is the `ReturnTypeError` (or `ArgumentTypeError`) naming the method, not a non-zero exit: read
+the error. Run it again after the change: it must exit 0. The same check
+fits a test suite as `RBS::UnitTest`'s `assert_send_type "(untyped) -> String?", receiver, :deliver,
+arg`, which also checks the call against the declaration loaded for the class, so it fails before the
+fix and passes after it.
+
+**Run the negative control first.** Run every witness once under a declaration you have broken on
+purpose and confirm it reports the type error; only then does a clean run under the real declaration
+mean anything. The checker silently skips some declarations. It checks a method only against a
+declaration written on the same class or module that defines the method in Ruby. A declaration
+inherited from a module or superclass, applied to a method an including class or subclass defines or
+overrides, is skipped unless it carries `%a{rbs:test:target}`. So are methods of classes created
+without `class … end` (`Struct.new`, `Class.new`, `Data.define`) and of classes loaded before
+`rbs/test/setup`. A witness that calls a skipped method exits 0 whatever the declaration says. On rgl,
+`remove_edge` declared `-> bool` on the module `MutableGraph` (which defines an abstract version) and
+overridden in the class `DirectedAdjacencyGraph` returned a `Set` and the run passed; redeclared on the
+class, the same run raised `expected bool but returns Set[5]`.
+
+A run that raises nothing is not a witness the other way: it shows only that the inputs you tried
+behave. When no input you can justify produces the excluded value, the finding is "left unchanged — no
+witness", not a change. A whole test suite run under `rbs/test/setup` checks only the declarations its
+calls reach and the checker does not skip; the declaration-mutation pass in
+[`05-declaration-mutants.md`](05-declaration-mutants.md) lists the ones it does not, which is the
+negative control for every declaration at once.
+
+`rbs prototype runtime` is a different tool: it prints the methods, arities, mixins and constants of the
+loaded classes, with every type `untyped`. It is useful for the skeleton of a new declaration set and
+for finding undeclared methods — including ones `define_method` creates — and parameter shapes, never
+for a return type. It loads the library, so the witness safety rule applies to it too.
+
+## Triage before deciding
+
+Drop these before spending evidence on them:
+
+| Shape | Why it is not a contract finding |
+| --- | --- |
+| `skip_reason` `sig.skipped.abstract-method`, `template-method`, `overridden-bot`, `overridden-by-unsigned-subclass` | abstract or template methods; the declaration states what overriders return, which the base body cannot show |
+| `sig.skipped.platform-guarded` | the definition loads only under a `RUBY_ENGINE` / `RUBY_PLATFORM` guard; the declaration describes the other platform's implementation |
+| `sig.skipped.untyped-return` | Rigor has no answer; the gap protocol in `rigor-type-oracle` applies |
+| a proposal of `[]` or `{}` | usually a collection the method fills later, or a registry callers append to; the element type is the contract, not "empty" |
+| a proposal of `bot` or `top` | `bot` is almost always an abstract or raising method; `top` says nothing a declaration should adopt |
+| a `tighter_return` that drops an arm the code clearly has (an `else`, a `rescue`) | an inference gap; report it, do not adopt it |
+| a `def.return-type-mismatch` adding `nil` to a memoised value (`@x ||= …`, possibly re-read after a `yield`) | a known false-positive shape; it needs a witness, and usually none exists |
+| a mismatch whose `nil` comes only from a lookup (`Hash#[]`, `find`, `detect`) on a key or element the library always supplies | worst-case reading; it needs a witness with an input the library allows |
+
+`rigor explain <skip-reason>` documents each skip reason in full.
+
+## What each signal sees
+
+| Question | Signal |
+| --- | --- |
+| Is a declared return narrower than the body's last expression? | 1, confirmed by 6 |
+| Is a declared return narrower than an early `return` or an untyped falsy arm? | leads, confirmed by 6 or 5 |
+| Is a Rigor finding real or a false positive? | 6 |
+| Is a public method undeclared? | 2 (`new_method`), 5, `rbs prototype runtime` |
+| Could an `untyped` return be precise? | 2 (`tighter_return` over `untyped`) |
+| Is a parameter too narrow? | 3 |
+| Is a `void` hiding a documented value? | 5 |

data/skills/rigor-rbs-contract/references/02-contract-rules.md

@@ -0,0 +1,157 @@
+# 02 — Deciding a candidate
+
+Every change to a declaration either makes it say less, makes it say more, or replaces a declaration
+that is wholly wrong. The kind decides the evidence it needs. Cite that evidence with the change;
+without it, the candidate is reported, not changed.
+
+## What counts as evidence
+
+| Evidence | How to cite it | Good for |
+| --- | --- | --- |
+| The library's documentation **for the version under review**: a doc comment on the method, the README shipped in that gem | quote it with its `file:line` in that version's source | any contract on code you do not own |
+| The owner's explicit answer, for the project's own code | the question and the answer; better, a doc comment written from it | any contract on that code |
+| A runtime witness: a call that RBS's runtime type checker (`rbs/test/setup` or `RBS::UnitTest`) rejects under the old declaration and accepts under the new one | the call, and the error it raised under the old declaration | saying less; showing a wholly wrong declaration is never returned |
+| Rigor's findings: `def.return-type-mismatch`, a `sig-gen` proposal, a `type-of` answer | the command and its output | locating a candidate and the exit to aim a witness at; filling an undeclared or `untyped` slot |
+| A correct call the old declaration rejects, found by `rigor check` on use-site code | the call and the diagnostic | widening a parameter or an input record |
+| An undeclared or `untyped` parameter's structural need, read from the body | the line that uses it | typing that parameter as an interface (`_ToS`, `_Each[T]`) |
+| Reading the implementation for anything else | — | nothing. It finds candidates; it does not decide them |
+
+How to run a witness: [`01-finding-candidates.md`](01-finding-candidates.md) § "Signal 6".
+
+**Documentation is pinned to the version.** Quote the doc comment or README from the unpacked source of
+the version whose declaration you are changing. A website, wiki or default-branch README describes some
+other release, so it may support a question in the write-up but is never the sole support for a change —
+least of all for `void` → a value. Grade what you quote: a doc comment that states the return ("Returns
+a unique Job ID. If middleware stops the job, nil will be returned instead") is strong; a README example
+that happens to use the value is weak. Say which kind you are citing.
+
+**The gem's own type annotations are documentation, and can be wrong.** A YARD `@return [Foo]` or
+`@param` in the gem's source is the author's statement, so you may read and quote it; `rigor-type-oracle`'s
+rule against bracketed YARD types governs what *you* write, not what you read. Grade a tag like any other
+documentation, and expect it to drift: on rgl 0.6.7, `Graph#reverse` is tagged
+`@return [DirectedAdjacencyGraph]` while its own prose says an undirected graph returns `self`, and the
+README's `remove_edge … #=> true` is stale (the call returns a `Set`). **When two pieces of the same
+version's documentation disagree, or a tag disagrees with Rigor's proof, a witness decides.** Quote
+both and cite the witness.
+
+## Saying less
+
+| Change | Needs | Example |
+| --- | --- | --- |
+| A return admits a value it excluded (`String` → `String?`) | a runtime witness or that version's documentation. On code you do not own, a Rigor finding alone is never enough | sidekiq `Client#push` (documented, and a halting middleware returns `nil`); marcel `Magic.by_magic` (`instance` → `instance?`, witnessed by a lookup on input that matches nothing) |
+| A parameter accepts more (`String` → `String \| Pathname`) | documentation, or a correct call the old declaration rejects | — |
+| An undeclared or `untyped` parameter is typed as an interface | the body's structural need | marcel `by_extension` takes `_ToS`, because the gem only calls `to_s` on it |
+| A record key becomes optional on input | a correct call that omits it | retryable `{ sleep: 3.2 }` |
+| A declaration is added for a public method, as `untyped` slots | nothing beyond the method existing | — |
+
+**Rigor's findings have false positives, so they are leads.** sidekiq 7.0's `Config#client_middleware`
+is `@client_chain ||= Chain.new(self); yield @client_chain if block_given?; @client_chain`, and
+`rigor check` reports `declared Chain, inferred Chain?` although it never returns `nil`. An agent that
+widened on that finding would push a `nil` check onto every caller of the gem. A witness is what tells
+the two apart: no input makes `client_middleware` return `nil`, so none can be produced.
+
+**A missing witness is not proof the other way.** A run that raises nothing shows only that the inputs
+you tried behave; it never justifies a narrower declaration. When you cannot produce a witness and the
+documentation is silent, leave the declaration and record the finding.
+
+**A declared parameter is a promise both ways.** Widening it promises callers that the library accepts
+more, and the next release may not keep that promise (a body that only calls `to_s` today may call
+`downcase` tomorrow). So a declared parameter widens only on documentation or a correct call it rejects,
+never on the body's current structural need alone.
+
+Before widening a return, look at what callers lose. Every caller now has to handle the new case, so the
+change is right only if the case is real. "It could be nil if someone passes nonsense" is not a witness;
+an input the documentation allows, or a use the library's own callers make, is.
+
+## Saying more
+
+| Change | Needs |
+| --- | --- |
+| A narrower return over a declared non-`untyped` type | a contract source. A `tighter_return` proposal alone is not enough |
+| A narrower return over `untyped`, or a new method's return | Rigor's proof (`sig-gen`'s proposal, verbatim) — or a contract source for anything it did not propose |
+| A narrower parameter | a contract source. Observed call sites (`sig-gen --params=observed`) show what callers pass today, not what the method accepts; widen literals before adopting them |
+| `void` or `boolish` → a value type | that version's documentation of the value. The body returning something is not documentation |
+| A deliberately wide nominal (`Numeric`, `Object`) → what the body returns | that version's documentation of the narrower value |
+| A new method whose `sig-gen` proposal is a literal (`-> 0`, `-> false`), an empty collection (`-> {}`, `-> []`), `nil`, or the incidental value of a procedure's last statement | nothing adopts it as is: write `void` (`bool` for a predicate) unless the documentation names the value. A literal default that subclasses override (`directed? -> false`, overridden with `true`) is a predicate: `bool` |
+| `instance` or `self` instead of the class `sig-gen` printed (a `new` in a singleton method, `self.class.new`, a method returning `self`) | the body's construction (`new` on the receiver's own class) plus documentation that subclasses get their own type. A witness cannot show it, because the checker accepts a subclass instance either way (#3069) |
+
+## Replacing a wholly wrong declaration
+
+Sometimes the declared type and the body have nothing in common: sidekiq 7.0's `Config#total_concurrency`
+is declared `ConnectionPool[RedisClientAdapter]`, and its body is `capsules.each_value.sum(&:concurrency)`
+(`rigor check` reports `inferred Integer`). That is neither saying less nor saying more. Treat the slot
+as undeclared:
+
+1. Take the type from that version's documentation, or from `rigor sig-gen --print` run on a copy of the
+   declarations with this member removed — the same source an undeclared method would get.
+2. Witness that the old declaration is wrong: one call whose result RBS's type checker rejects against
+   the old type.
+3. Say in the write-up that the declaration was replaced, not widened or narrowed.
+
+## Blocks
+
+Most of a new declaration's work is in its parameters and blocks, and `sig-gen` does not always type
+blocks (#3067). Decide them in this order:
+
+- **Required or optional.** Optional (`?{ … }`) when every `yield` or `block.call` is guarded by
+  `block_given?` (or the block is passed on to a method whose declaration makes it optional); required
+  when one is unconditional. If the documentation says optional and the body uses the block
+  unconditionally, see "When the documented contract crashes" below.
+- **Two overloads, not an optional block,** when the method returns something else without a block
+  (`return enum_for(__method__) unless block_given?`): `() { (T) -> void } -> self` and
+  `() -> Enumerator[T, self]`, rather than one optional block with a union return.
+- **Block parameters** come from what is yielded, and from `:yields:` / `@yield` / `@yieldparam` in the
+  documentation.
+- **Block return** is `void` unless the method uses the value; `boolish` when it is used only for
+  truthiness (a filter or predicate block); a precise type only when the method's documented result
+  depends on it.
+
+## When the documented contract crashes
+
+Sometimes a witness shows the documentation promising more than the code delivers: rgl documents
+`depth_first_search`'s block as optional, and calling it without one raises `NoMethodError`. Keep the
+documented declaration — it is the contract — note the defect as an upstream bug for the user to
+report (filing an issue on someone else's repository is outward-facing; do not do it unasked), and put
+it under open questions in the write-up. Narrowing the declaration to what the code survives would be saying more
+without a contract source.
+
+## Rules that come up on almost every run
+
+**`void` and `boolish` stand.** (For the project's own code, the owner may decide otherwise; that is a
+contract decision, so ask rather than infer.) Every Ruby method returns its last expression, so a body
+nearly always has a value. `-> void` says that value is not part of the contract; `boolish` says only
+its truthiness is. `static.value-use.void` reports a use of the first where a project enables it. Do not
+tighten either to the body's value unless the library documents that value. In sidekiq 7.0,
+`perform_async` and `Client.enqueue*` return `push`'s result from their bodies, but nothing documents
+it, so their `void` stayed while `push` itself became `String?`.
+
+**One alias, two contracts.** When a type alias, record or interface is both what callers pass in and
+what the library hands back, check whether the two agree. Inputs usually accept partial or loose values;
+outputs usually guarantee more. If they differ, split the alias — for example `option_overrides` (keys
+optional) for input and `options` (keys required) for output — rather than making it loose enough for
+both and weakening every return that uses it. Inputs stay lenient; outputs stay as precise as their
+documented guarantee.
+
+**A nilable wrapper on a value is not the same as an optional key.** `{ ?sleep: Numeric }` says the key may
+be absent; `{ sleep: Numeric? }` says it may be present and `nil`. Use the second only where a present
+`nil` is accepted and means something.
+
+**Interfaces describe what the method uses.** When an undeclared or `untyped` parameter is only used
+through one or two methods, an interface (`_ToS`, `_ToPath`, `_Each[T]`, or one you declare inside the
+library's namespace) is the honest contract. Do not add top-level aliases or interfaces to a shared RBS
+tree.
+
+**Consistency across versions.** A collection entry often has several version directories. Apply the same
+contract to each version whose code and documentation say the same thing — witnessed or quoted in that
+version — and say in the write-up which versions you changed and which you did not and why.
+
+## Every finding gets a disposition
+
+Each row Rigor reported (Signal 1 and Signal 2) and each lead you followed ends in exactly one list:
+
+- **Changed** — with its evidence.
+- **Deliberately left unchanged** — you looked, and the declaration is the right contract: a `void` over
+  a value; a wide nominal; a proposal that is an inference gap; a Rigor finding no witness confirmed
+  (say so — "`rigor check` reports `Chain?`; no input returns `nil`").
+- **Open questions** — the evidence does not settle it. For your own code, ask the owner. Upstream, a
+  question in the pull request description is better than a guess in the diff.