rigortype 0.4.7 → 0.4.8

data/skills/rigor-rbs-contract/references/03-target-own-code.md

@@ -0,0 +1,90 @@
+# 03 — Target: the project's own code
+
+A gem's shipped `sig/`, an application's `sig/`, or rbs-inline annotations (`#:`, `# @rbs`) in either.
+The project's owner is the authority on every contract this code makes, so this target is
+**interactive**: Rigor and the documentation narrow the questions, and the owner answers the ones they
+leave open.
+
+## Setup
+
+The project's Rigor configuration already analyses its source with its `sig/` on the signature path, so
+the commands in [`01-finding-candidates.md`](01-finding-candidates.md) run as they are:
+
+```sh
+rigor check --no-baseline --format=json lib            # Signal 1
+rigor sig-gen --diff --format=json lib                 # Signal 2
+rigor check --no-baseline --format=json spec           # Signal 3, or test/, or the application's callers
+```
+
+If `rigor` is not configured yet, run `rigor-next-steps` first. Record the current `rigor check` result
+(with the baseline, as the project normally runs it) before changing anything; the gate below compares
+against it.
+
+## Ask, in one batch
+
+After triage, sort what is left into three groups:
+
+1. **Settled by evidence** — a `def.return-type-mismatch`, a `sig-gen` proposal over `untyped`, a
+   documented value. Apply these, with their citations.
+2. **Settled as "leave it"** — a `void` over a value nobody documented, a wide nominal, a proposal that
+   is an inference gap. Do not ask about these one by one; list them.
+3. **Open contract questions** — everything that needs the owner. Ask them together, each with the
+   evidence and the concrete options:
+
+> `Client#push` is declared `-> String`. Its body returns `nil` when a middleware halts the job
+> (`lib/client.rb:88`, `return nil unless item`), and `rigor check` cannot see that early return.
+> Should callers be told to expect `nil`?
+> (a) `-> String?` — callers must handle a halted job; (b) keep `-> String` and raise instead of
+> returning `nil`; (c) `-> void` — callers should not use the value.
+
+Never ask an open question as "what type is this?". The owner should choose a contract, not reverse-
+engineer one.
+
+## Write the answer where it can be cited
+
+An answer that lives only in the conversation is lost to the next contributor and to anyone writing RBS
+for this library elsewhere. Offer to record each answered contract as a doc comment in prose — "Returns
+the job id, or nil when a middleware stops the job." — next to the method. The declaration then has a
+documented source, which is what makes it checkable later.
+
+If the project keeps types out of doc comments, prose describing behaviour is still fine; a bracketed
+YARD type is not, and `rigor-type-oracle` covers why.
+
+## The gate
+
+1. `rigor check` on the project, run as the project normally runs it, gains no new diagnostic. A new one
+   means a caller relied on the old contract: show it to the owner. It is either a bug the new contract
+   exposed, or a sign the contract change is wrong.
+2. If the project ships its RBS (a gem's `sig/`), it still loads: `rbs -I sig validate`, or the
+   project's own RBS task.
+3. If the project also runs Steep or another RBS consumer, run it. Rigor is not the only reader of these
+   files.
+4. Where you widened a return, a witness shows the case is real (see `01-finding-candidates.md`
+   § "Signal 6") and a test or a use site now handles it; where you widened a parameter, a test now
+   passes the newly accepted argument. The owner may accept a change without a witness — say so in the
+   write-up — but a Rigor finding alone is never presented as proof.
+5. If the project has a test suite, use it as the command for the declaration-mutation pass
+   ([`05-declaration-mutants.md`](05-declaration-mutants.md)): it runs the suite under `rbs/test/setup`
+   once per broken declaration. A killed mutant is a declaration the suite checks against real values,
+   which no static signal does; a survivor is one it does not check, however green the suite is. Report
+   the survivors to the owner.
+6. For a gem with no RBS yet, the skeleton and new-method rules in `04-target-gem-rbs-collection.md`
+   § "New declaration set" apply to its `sig/` as well; ship it with the gem rather than through the
+   collection.
+
+## When the wrong signature belongs to a dependency
+
+If a diagnostic in the project traces to a dependency's community RBS, the fix belongs upstream:
+follow [`04-target-gem-rbs-collection.md`](04-target-gem-rbs-collection.md) for that gem. Until the fix
+is released, a local corrected copy can stand in:
+
+- in `rbs_collection.yaml`, set that gem to `ignore: true`, then run `rbs collection install` again so
+  `rbs_collection.lock.yaml` drops it (the old directory under `.gem_rbs_collection/` stays, but only
+  gems listed in the lockfile load) — otherwise the collection copy still loads next to yours and the duplicate declarations fail to build, which reads as a quieter run, not a
+  fixed one;
+- copy its RBS into a project directory on `signature_paths`, apply the fix, and note the upstream pull
+  request next to it;
+- remove the copy and the `ignore:` once the fix is in a collection release you have installed.
+
+Do not patch the installed collection under `.gem_rbs_collection/`; the next `rbs collection install`
+overwrites it.

data/skills/rigor-rbs-contract/references/04-target-gem-rbs-collection.md

@@ -0,0 +1,210 @@
+# 04 — Target: a gem_rbs_collection entry
+
+RBS for a gem you do not own, in a checkout of
+[`ruby/gem_rbs_collection`](https://github.com/ruby/gem_rbs_collection). The gem's documentation is the
+authority, so this target can run without questions up to a finished branch and pull request
+description. **Pushing the branch and opening the pull request are the user's call**: both are
+outward-facing, even to a fork. Show them the local branch and the description, and push or open only
+on their go-ahead, unless they already gave it for this change.
+
+The collection's own guide is `docs/CONTRIBUTING.md` in the checkout; read it once. Two of its points
+shape this workflow: focus on the API the README and documentation present, and write `_test/` code that
+checks RBS against *application* code, not against the gem's implementation.
+
+## Setup
+
+Paths below use `gems/NAME/X.Y` for the entry, `$COLLECTION` for the checkout, `$GEM_DIR` for the gem's
+source and `$SCRATCH` for a scratch directory. **Run every block from here to Signal 3 in one shell
+session**, or as one script: an agent's shell tool often keeps no variables between calls, and an empty
+`$GEM_DIR` or `$SCRATCH` turns `cp -R "$GEM_DIR/lib" "$SCRATCH/lib"` into a copy of `/lib`. If the
+variables cannot persist, set them again at the top of each block and guard them, for example
+`: "${GEM_DIR:?}" "${SCRATCH:?}"`.
+
+1. In the checkout: `bin/setup`.
+2. Fetch the source of the version the entry describes. Unpacking reads it without building native
+   extensions or running anything:
+
+   ```sh
+   COLLECTION=$PWD
+   SRC=$(mktemp -d)
+   (cd "$SRC" && gem fetch NAME -v '~> X.Y.0' && gem unpack NAME-*.gem)
+   GEM_DIR=$(ls -d "$SRC"/NAME-*/ | head -n 1)
+   ```
+
+   If the gem is already installed, `ruby -e 'puts Gem::Specification.find_by_name("NAME", "~> X.Y.0").gem_dir'`
+   gives the same directory.
+
+3. Run the entry's tests once before changing anything, so you know they were green:
+
+   ```sh
+   bin/test gems/NAME/X.Y
+   ```
+
+   This also leaves an `rbs_collection.lock.yaml` in `_test/`, which puts the entry's dependency RBS in
+   reach for the use-site check below.
+
+## Signals 1 and 2 — the declarations against the gem's source
+
+Work in a scratch directory outside the checkout, so nothing Rigor writes ends up in the diff, and copy
+in only what is under review:
+
+```sh
+SCRATCH=$(mktemp -d)
+mkdir -p "$SCRATCH/sig"
+cp -R "$GEM_DIR/lib" "$SCRATCH/lib"
+rsync -a --exclude _test --exclude .gem_rbs_collection "$COLLECTION/gems/NAME/X.Y/" "$SCRATCH/sig/"
+printf 'paths: ["lib"]\nsignature_paths: ["sig"]\n' > "$SCRATCH/.rigor.yml"
+cd "$SCRATCH"
+rigor check --format=json lib
+rigor sig-gen --diff --format=json lib
+```
+
+Excluding `_test/` matters: its `.rbs` files and any `.gem_rbs_collection/` left by an earlier
+`bin/test` would load as duplicate declarations. A gem whose RBS depends on another gem's RBS will show
+`rbs.coverage.*` warnings and undefined-method noise here; copy that dependency's entry into `sig/` too,
+or read Signal 1 for the methods whose types do not touch the dependency.
+
+## Signal 3 — the entry's `_test/` code
+
+```sh
+cd "$COLLECTION/gems/NAME/X.Y/_test"
+printf 'paths: ["."]\nsignature_paths: ["."]\n' > .rigor.yml    # with rbs_collection.lock.yaml present
+rigor check --no-cache --format=json
+```
+
+Without an `rbs_collection.lock.yaml`, use `signature_paths: [".."]` instead, and expect missing
+dependency RBS. `--no-cache` keeps a `.rigor/` cache directory out of the entry. Keep `.rigor.yml` out of
+the commit by listing it in `.git/info/exclude`, and check `git status` before committing: nothing under
+`_test/` but your test files belongs in the diff.
+
+## Signal 5 — the gem's documentation
+
+Read the doc comments in `$GEM_DIR/lib` and the README in `$GEM_DIR` — the source of the version under
+review. Quote what you rely on in the write-up with its path and line in that source. A website or the
+default branch's README may describe another release: use it to ask, not to decide.
+
+## Signal 6 — the runtime witness
+
+Every change that makes a declaration say less needs a witness or that version's documentation here; a
+Rigor finding alone does not go upstream. Give both when you can. Run the witness from Signal 6 of
+`01-finding-candidates.md` in `$SCRATCH`, against the unpacked source and the copied declarations:
+
+```sh
+: "${SCRATCH:?}"
+cd "$SCRATCH"
+RBS_TEST_TARGET='Namespace::*' RBS_TEST_OPT='-I sig' ruby -I lib -rrbs/test/setup witness.rb
+```
+
+**This executes the gem's code with the user's privileges, and installing what it needs at runtime
+installs more.** A scratch directory is not isolation. Run it in a container or VM, or ask the user
+before executing a gem that is not already in their bundle. Record the call and the error. After editing the declaration,
+copy it into `$SCRATCH/sig` again and confirm the same run passes. `witness.rb` is evidence for the pull
+request description, not a committed test: the collection's `_test/` code is checked statically.
+
+## Writing the change
+
+- Edit `gems/NAME/X.Y/*.rbs`. Keep types inside the gem's namespace; no new top-level aliases or
+  interfaces.
+- A new standard-library or gem dependency in the RBS, or in the test, goes into `manifest.yaml`
+  (marcel's test needed `tempfile`).
+- Apply the same contract to every version directory whose code and documentation agree, and only to
+  those.
+
+## New declaration set (a new entry)
+
+When the gem has no entry yet, there is nothing for Signals 1 and 2 to compare against, and three jobs
+take the place of the audit:
+
+1. **The skeleton.** `"$COLLECTION"/bin/init_new_gem NAME` creates the directory and `_test/`. It
+   prompts on stdin for the version and then a GitHub account for `_reviewers.yaml`, so answer both
+   explicitly — `printf '0.6\n\n' | "$COLLECTION"/bin/init_new_gem NAME` — and leave the account empty
+   unless the user gives you one; never put their name in it on your own. Take the
+   module structure — classes, modules, `include` / `extend`, superclasses, `attr_*`, aliases,
+   constants, and methods that exist only through metaprogramming — from the loaded gem, because
+   `sig-gen` writes none of these:
+
+   ```sh
+   RUBYLIB="$GEM_DIR/lib" rbs prototype runtime -r FEATURE Namespace 'Namespace::*' > "$SCRATCH/skeleton.rbs"
+   ```
+
+   `-r` takes the gem's feature name (`rgl/adjacency`); `-R` means `require_relative`, and there is no
+   `-I`. Name the top-level module on its own as well as `Namespace::*`: the pattern alone excludes it. rbs 4.2 marks the command deprecated (ruby/rbs#2841) but it still works. It loads the gem, so
+   the witness safety rule applies.
+2. **The types.** Run `rigor sig-gen --print` in `$SCRATCH` with an empty `sig/`, and take each
+   method's types from it under `02-contract-rules.md`: a literal, empty-collection, `nil` or
+   procedure-tail proposal becomes `void` or `bool` unless documented; blocks follow § "Blocks".
+3. **The contracts.** Fill what `sig-gen` skipped from the documentation, witness every `nil`, and leave
+   the rest `untyped`. A method that appears in the skeleton but in neither `sig-gen` list was silently
+   dropped (#3068); give it a disposition too.
+
+**A dependency without an entry.** When the new entry must reference a type from another gem — a mixin
+(`include Stream`), a superclass, a parameter type — and that gem has no entry either, the other entry
+comes first, in its own pull request, or the reference is dropped (with the methods it would have
+supplied declared directly). Say which in the description. Never ship a stub of another gem inside this
+entry.
+
+## The gate
+
+1. Add or extend a test under `_test/` that exercises the contract you changed, as application code
+   would: `&.` or an `if` on a newly nilable return, calls to newly declared methods, the newly accepted
+   argument shapes. A new file pair `test_N.rb` / `test_N.rbs` is fine when the existing test does not
+   fit.
+2. `"$COLLECTION"/bin/test gems/NAME/X.Y`, run from `$COLLECTION`, passes for every version you
+   touched. It runs `rbs validate`, `steep check` and the untyped-call check.
+3. `rigor check` on `_test/` reports nothing new compared with before the change.
+4. Every change that says less has a witness that fails under the old declaration and passes under the
+   new one, or a quote from that version's documentation, for each version you changed.
+5. The declaration-mutation pass ([`05-declaration-mutants.md`](05-declaration-mutants.md)) has run over
+   the entry with `_test/` and your witnesses as the command, and its survivors are listed in the
+   description.
+
+When `bin/test` cannot run — it needs the network to lock and install the collection — run the same
+three checks offline and say in the description that `bin/test` was not run. Offline there is no
+installed collection, so the Steepfile names the entry (`signature ".."`) and each dependency entry
+itself:
+
+Add `-r <library>` to `rbs` and a `library "<library>"` line to the Steepfile for each standard library
+`manifest.yaml` lists, which `bin/test` would otherwise install. A library that is part of core in the
+`rbs` you run (`set` under rbs 4.2) has no separate signatures, and `-r set` fails with "Cannot find
+type definitions"; leave it out there:
+
+```sh
+rbs -r <each manifest library> -I "$COLLECTION/gems/NAME/X.Y" -I <each dependency entry> validate
+cd "$COLLECTION/gems/NAME/X.Y/_test"     # Steepfile: bin/test's generate_steepfile, plus signature ".." and each dependency entry
+steep check
+steep stats --format=csv                 # every row's "Untyped calls" must be 0, as bin/check-untyped-call.rb checks
+```
+
+## The pull request
+
+Branch from the collection's default branch and keep one gem, one concern per pull request. Title it
+`NAME: <what the contract now says>` — for example `sidekiq: Client#push and client_push return
+String?`. The body follows the shape reviewers have accepted:
+
+```markdown
+## Summary
+
+What was wrong with the contract and why, with the quote that settles it.
+
+Changed in `gems/NAME/X.Y`:
+
+- `Klass#meth` now returns `String?`. <the evidence, one line>
+
+Deliberately left unchanged:
+
+- `Klass#other` stays `void`. Its implementation returns the same value, but NAME does not document a return value for it.
+- `Klass#memo` stays `Chain`. Rigor reports `Chain?`, but no input returns `nil` (the value is memoised).
+
+## How this was found
+
+The signal that surfaced it — the Rigor command and the finding, or the documentation sweep.
+
+## Verification
+
+The witness for each change that says less: the call, and the runtime type checker's error under the old declaration (it passes under the new one). The declaration-mutation result (killed / survived) and every survivor, named as unchecked at runtime. The test added, and the `bin/test gems/NAME/X.Y` result for each version.
+```
+
+Write each paragraph and list item on one line; GitHub renders a newline inside a paragraph as a line
+break. "Deliberately left unchanged" lists every Rigor finding you did not act on and every `void`,
+`boolish` or wide declaration kept over a body that returns more: it is the evidence that the restraint
+was a decision.

data/skills/rigor-rbs-contract/references/05-declaration-mutants.md

@@ -0,0 +1,182 @@
+# 05 — Declaration mutants: which declarations does any run actually check?
+
+A runtime witness proves something only if the checker looked. RBS's runtime checker silently skips
+some declarations: it checks a method only against a declaration on the same class or module that
+defines the method in Ruby, so a declaration inherited from a module or superclass by a class that
+defines or overrides the method is skipped (unless it carries `%a{rbs:test:target}`). In a field trial
+on rgl 0.6.7, rgl's own test suite ran under `rbs/test/setup` with one expected failure while several
+declarations of that kind were never checked. A single witness has the same problem: a clean exit means
+nothing until a deliberately broken declaration makes the same run fail.
+
+This is mutation testing aimed at the declarations instead of the code. Break one method return at a
+time, re-run the witnesses, and see whether the run notices:
+
+- **killed** — the run reports a type error, naming the mutated method or one of its RBS aliases, that
+  the clean run did not. The return is checked.
+- **SURVIVED** — no such error. Nothing you ran checks this return: no call reaches it, or the checker
+  skips it. Treat it as unverified at runtime, whatever the suite reported.
+- **ERROR** — the mutant does not load. Nothing was learned; fix the script or the declarations.
+- **UNKNOWN** — the clean run already reports a return error on this method. Fix that first.
+
+| Operator | Mutation | A survivor means |
+| --- | --- | --- |
+| `bot` | the return type becomes `bot`, which no value inhabits | no run checks this return at all |
+| `drop-nil` | a `T?` return becomes `(T)` | no run reaches the `nil` arm, so the `?` has no witness |
+
+`void` returns are skipped (the checker does not compare them, by design), and so is `drop-nil` on
+`untyped?` (`untyped` already admits `nil`). Parameters, blocks and `attr_*` declarations are not mutated:
+the pass says nothing about them.
+
+A built-in command for this is proposed in #3072; until it exists, the script below is the procedure.
+
+## Running it
+
+The script needs only the `rbs` gem. Give it the directory of declarations under review and the
+command that runs your witnesses — a witness script, the project's test suite, or a collection entry's
+`_test/` — under `rbs/test/setup` with `RBS_TEST_TARGET` set. The script sets `RBS_TEST_OPT` to the
+mutant directory itself; pass any further `-I` / `-r` options in `RBS_DECL_MUTANTS_EXTRA_OPT`. Save it as
+`rbs_decl_mutants.rb` outside the project.
+
+```sh
+RBS_DECL_MUTANTS_EXTRA_OPT='-I ../deps-sig' ruby rbs_decl_mutants.rb sig -- ./run-witnesses.sh
+```
+
+`run-witnesses.sh` is whatever runs your witnesses, for example:
+
+```sh
+#!/bin/sh
+RBS_TEST_TARGET='MyGem::*' ruby -I lib -I test -rrbs/test/setup -e 'Dir["test/*_test.rb"].each { |f| require_relative File.expand_path(f) }'
+```
+
+Each mutant is one full run, so the pass costs the command's runtime times the number of non-`void`
+returns (rgl: 61 mutants, about 70 seconds). It runs the library's code, so the safety rules for a
+witness apply: for a gem not already in the user's bundle, use a container or VM or ask first.
+
+```ruby
+# frozen_string_literal: true
+
+# Break each RBS method return in turn and check whether a witness command notices.
+#
+#   ruby rbs_decl_mutants.rb SIG_DIR -- COMMAND...
+#
+# COMMAND runs the witnesses under rbs/test/setup (RBS_TEST_TARGET set) and must read declarations from
+# $RBS_TEST_OPT, which this script sets to `-I <mutant dir>` plus RBS_DECL_MUTANTS_EXTRA_OPT.
+# Operators: `bot` (nothing inhabits it: is this declaration checked at all?) and `drop-nil` (`T?` -> `T`:
+# does any witness reach the nil arm?). A mutant is killed only by a type error that names the mutated
+# method and that the clean run did not report; a mutant that does not load is an ERROR, never a survivor;
+# a method whose return the clean run already fails on is UNKNOWN.
+require "rbs"
+require "rbs/cli"
+require "optparse"
+require "fileutils"
+require "open3"
+require "set"
+require "shellwords"
+require "tmpdir"
+
+Encoding.default_external = Encoding::UTF_8
+sig_dir = File.expand_path(ARGV.shift.to_s)
+ARGV.shift if ARGV.first == "--"
+command = ARGV
+abort "usage: ruby rbs_decl_mutants.rb SIG_DIR -- COMMAND..." if !File.directory?(sig_dir) || command.empty?
+extra = ENV.fetch("RBS_DECL_MUTANTS_EXTRA_OPT", "")
+
+# `[Owner#name] KindError: ...` -> ["Owner#name", "KindError"]; the value after the colon is dropped
+# because it carries object addresses and sampled elements that differ from run to run.
+ERROR_TAG = /^.*?\[(.+?)\] (\w+Error):/
+RETURN_KINDS = %w[ReturnTypeError UnresolvedOverloadingError].freeze
+def type_errors(out) = out.each_line.filter_map { |l| (m = l.match(ERROR_TAG)) && [m[1], m[2]] }.to_set
+
+def run(command, dir, extra)
+  out, = Open3.capture2e({ "RBS_TEST_OPT" => "-I #{dir} #{extra}".strip }, *command, stdin_data: "")
+  out
+end
+
+# Load the mutant exactly as rbs/test/setup parses RBS_TEST_OPT, so one that does not load is reported.
+def loads?(dir, extra)
+  options = RBS::CLI::LibraryOptions.new
+  OptionParser.new { |o| options.setup_library_options(o) }.parse!(Shellwords.split("-I #{dir} #{extra}"))
+  env = RBS::Environment.from_loader(options.loader).resolve_type_names
+  RBS::DefinitionBuilder.new(env: env)
+  true
+rescue StandardError => e
+  warn "  load error: #{e.class}: #{e.message.lines.first}"
+  false
+end
+
+files = Dir[File.join(sig_dir, "**", "*.rbs")].reject { |f| f.split(File::SEPARATOR).include?("_test") }
+sites = []
+collect = lambda do |decl, ns, file, aliases = Hash.new { [] }|
+  case decl
+  when RBS::AST::Declarations::Class, RBS::AST::Declarations::Module
+    # The checker reports a call made through an alias under the alias's name, so a kill may carry it.
+    aliases = Hash.new { |h, k| h[k] = [] }
+    decl.members.grep(RBS::AST::Members::Alias).each do |a|
+      aliases[[a.kind, a.old_name]] << a.new_name
+      aliases[[a.kind, a.new_name]] << a.old_name
+    end
+    decl.members.each { |m| collect.call(m, ns + [decl.name.to_s.delete_prefix("::")], file, aliases) }
+  when RBS::AST::Members::MethodDefinition
+    sep = decl.kind == :singleton ? "." : "#"
+    names = [decl.name, *aliases[[decl.kind == :singleton ? :singleton : :instance, decl.name]]]
+    decl.overloads.each_with_index do |overload, index|
+      ret = overload.method_type.type.return_type
+      next if ret.location.nil? || ret.is_a?(RBS::Types::Bases::Void)
+      label = "#{ns.join('::')}#{sep}#{decl.name} (overload #{index}, #{ret})"
+      tag_suffix = names.map { |n| "#{sep}#{n}" }
+      sites << [file, ret.location, "bot", label, tag_suffix]
+      next unless ret.is_a?(RBS::Types::Optional) && !ret.type.is_a?(RBS::Types::Bases::Any)
+      sites << [file, ret.location, "(#{ret.type})", "#{label} drop-nil", tag_suffix]
+    end
+  end
+end
+files.each { |f| RBS::Parser.parse_signature(File.read(f, encoding: "UTF-8"))[2].each { |d| collect.call(d, [], f) } }
+
+Dir.mktmpdir("rbs-decl-mutants") do |tmp|
+  clean = File.join(tmp, "clean")
+  FileUtils.cp_r(sig_dir, clean)
+  FileUtils.rm_rf(Dir[File.join(clean, "**", "_test")])
+  abort "the clean declarations do not load" unless loads?(clean, extra)
+  baseline = type_errors(run(command, clean, extra))
+  warn "clean run reports #{baseline.size} type error(s); those tags are ignored" unless baseline.empty?
+
+  tally = Hash.new(0)
+  sites.each do |file, loc, replacement, label, tag_suffix|
+    dir = File.join(tmp, "mutant")
+    FileUtils.rm_rf(dir)
+    FileUtils.cp_r(clean, dir)
+    target = File.join(dir, file.delete_prefix(sig_dir).delete_prefix(File::SEPARATOR))
+    src = File.read(file, encoding: "UTF-8") # RBS locations are character offsets
+    File.write(target, src[0...loc.start_pos] + replacement + src[loc.end_pos..])
+    verdict =
+      if baseline.any? { |tag, kind| RETURN_KINDS.include?(kind) && tag.end_with?(*tag_suffix) }
+        "UNKNOWN" # the clean run already fails on this method; fix that first
+      elsif !loads?(dir, extra)
+        "ERROR"
+      else
+        fresh = type_errors(run(command, dir, extra)) - baseline
+        fresh.any? { |tag, _kind| tag.end_with?(*tag_suffix) } ? "killed" : "SURVIVED"
+      end
+    tally[verdict] += 1
+    puts "#{verdict.ljust(8)} #{label}"
+  end
+  puts "#{sites.size} mutants: #{tally['killed']} killed, #{tally['SURVIVED']} survived, " \
+       "#{tally['ERROR']} did not load, #{tally['UNKNOWN']} already failing in the clean run"
+end
+```
+
+## Reading the result
+
+- Report every survivor in the write-up as "unchecked at runtime", with the operator. It is not a
+  defect in the declaration; it is the limit of what your evidence covers.
+- A `bot` survivor on a method your witnesses call is the checker's skip rule at work. Redeclare the
+  member on the class that defines the method (where that is also a correct declaration), add
+  `%a{rbs:test:target}` to the inherited declaration, or rely on documentation for it and say so.
+- A `bot` survivor on a method nothing calls is a missing witness: add a call, or say so.
+- A `drop-nil` survivor means the `?` rests on documentation alone. If the documentation does not
+  mention `nil` either, the `?` has no evidence: re-examine it.
+- A killed mutant on a "say less" change is the negative control that change needs.
+
+On the rgl draft the pass reported 61 mutants: 56 killed, 5 survived. Three survivors were the skip
+rule (`Graph#directed?`, `#has_vertex?`, `#has_edge?`, declared on the module `Graph` and overridden in
+classes); `Graph#to_s` was never called; and the `?` on `Edge::DirectedEdge#<=>` had no witness.

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

@@ -82,7 +82,9 @@ rbs --version            # or: bundle exec rbs --version
 If it is missing, add it to the project's development group
 (`bundle add rbs --group development`) or install it standalone
 (`gem install rbs`). Prefer `bundle exec rbs …` when `rbs` is in the
-Gemfile so it matches the project's resolved versions.
+Gemfile so it matches the project's resolved versions. If `bundle exec rbs`
+runs an `rbs` that a mise-installed `gem:rigortype` put on `PATH`, 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).
 
 ### Phase 3 — initialise the collection config (first time only)
 

data/skills/rigor-type-oracle/SKILL.md

@@ -69,6 +69,9 @@ scope the moment you are about to write or assert one:
 - **Working an existing `.rigor-baseline.yml` down** →
   `rigor-baseline-reduce`. That is fixing diagnostics, not sourcing a
   type.
+- **Auditing, repairing, or contributing RBS declarations** — a gem's
+  `sig/`, an application's `sig/`, a gem_rbs_collection entry →
+  `rigor-rbs-contract`. This skill still governs every type it writes.
 - **Raising type protection from a `coverage --protection` list** →
   `rigor-protection-uplift`. It owns the "where should a type go, and how
   do I verify it" loop; this skill owns "where does the type itself come
@@ -76,7 +79,9 @@ scope the moment you are about to write or assert one:
 
 ## The three allowed sources
 
-Every type you write comes from exactly one of these. There is no fourth.
+Every type you write comes from exactly one of these. There is no fourth
+source for a type itself; what a *declaration* promises is the separate
+contract question below.
 
 | What you need | Ask Rigor with | What you write |
 | --- | --- | --- |
@@ -96,6 +101,26 @@ adopting, under the gate that `rigor check` gains no new diagnostic.
 Exact command forms, flags, position syntax, JSON shapes, and how to read
 each output: [`references/01-oracle-commands.md`](references/01-oracle-commands.md).
 
+## A declaration is a contract, not a missing type
+
+None of the three sources says what a declaration *promises* to callers.
+Ruby returns every method's last expression, so a body almost always has
+a value; a declared `void` says callers must not depend on it, and
+`boolish` says only its truthiness counts. **Never tighten `void`,
+`boolish`, or a declared type deliberately wider than the body (anything
+but `untyped`) to what the body happens to return** — in `sig/`, in an
+inline annotation, or in RBS sent upstream — unless the library documents
+that value or, for the project's own code, the owner decides. A
+`sig-gen` proposal over `untyped` is not this case; it is the second
+source above.
+
+The reverse also holds. A contract the body does not prove — `String?`
+because the method's documentation says it returns `nil` when a job is
+halted — is not a guess when it is cited: the library's documentation,
+quoted, for code you do not own; the owner's explicit answer for code
+they do. Auditing, repairing, or contributing a set of RBS declarations
+on that basis is **`rigor-rbs-contract`**.
+
 ## The gap protocol — a gap is a finding, not a blank to fill
 
 `Dynamic[top]`, `untyped`, and a `sig.skipped.*` classification are

data/skills/rigor-type-oracle/references/02-agents-md-fragment.md

@@ -17,7 +17,7 @@ the project is already onboarded, add it now.
   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
-  rather than adding a second one, and keep the five bullets intact.
+  rather than adding a second one, and keep the six bullets intact.
 
 Never overwrite unrelated content, and never rewrite a rule the project
 already wrote for itself — show the user the conflict instead.
@@ -27,13 +27,14 @@ already wrote for itself — show the user the conflict instead.
 ```markdown
 ## Types come from Rigor, not from reading code
 
-This project is type-checked by [Rigor](https://github.com/rigortype/rigor). A type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere: not in `sig/`, not in an inline annotation (`#:`, `# @rbs`), not in a doc comment, not in a review comment, and not as the reason for a nil check or an `is_a?` guard.
+This project is type-checked by [Rigor](https://github.com/rigortype/rigor). A type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere: not in `sig/`, not in an inline annotation (`#:`, `# @rbs`), not in a doc comment, not in a review comment, and not as the reason for a nil check or an `is_a?` guard. The one other source is a contract: what a declaration promises callers may rest on the library's documentation, quoted, or for this project's own code on the owner's explicit decision.
 
 - The type of an expression: `rigor type-of FILE:LINE:COL`, or `rigor annotate FILE` for a whole file.
 - The signature of a method: `rigor sig-gen --print FILE`; paste what it prints, never what you expect.
 - A parameter type is the one thing inference does not give you: derive it from the call sites with `rigor sig-gen --observe PATH` and keep it only while `rigor check` stays green.
-- When Rigor answers `Dynamic[top]` or `untyped`, or `sig-gen` skips the method, do not fill the gap. Report the exact command and its output; the gap is the finding.
+- When Rigor answers `Dynamic[top]` or `untyped`, or `sig-gen` skips the method, do not fill the gap from your reading. Report the exact command and its output; the gap is the finding. Only a contract source, cited as above, fills it.
 - Every type you state to a human carries the command that produced it, so it can be re-run.
+- A declared `void` or `boolish` return, or a declared type deliberately wider than the body (anything but `untyped`), is a contract, not a missing type: never tighten it to what the body happens to return unless the library documents that value or, for this project's own code, the owner decides. Auditing or repairing RBS declarations is the `rigor-rbs-contract` skill.
 
 The `rigor-type-oracle` skill (`rigor skill --full rigor-type-oracle`) has the full procedure. With the Rigor MCP server connected, `rigor_type_of`, `rigor_annotate`, and `rigor_sig_gen` are the same oracle as tool calls.
 ```