rigortype 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b20cef50f4d076f1afefb8c20563cd21a95a56b01bf4db3257371adfe7c64d5d
-  data.tar.gz: 9c4f5f8825106ece96fb2ac00dc1ad4ef43f302368f1a12f87521c725530b924
+  metadata.gz: 4da9b991a97cd586806b416facb6dbf6c3a3b938c7c9433e330bc44c0757fdaf
+  data.tar.gz: 1167e8d91ccbc8740ac4094f67db82937bd3b374d2488a43e514f7922c7a98b1
 SHA512:
-  metadata.gz: 4418a4a75a22d27038d0607caa5a79723470e68f9662da1aec0b79e8056a1b157f78cf85f83cb51f646aa22d2634b0d851bb9f0132a548f5104acdee2372d1d2
-  data.tar.gz: 026710fb13eebddf98776d6a9a3fb8e1738a7cc5fdd77c326afa0adb680c0760462d9e41b4aff57d1c41d1878fc05c41a8658be7b69ed4f265709aa27f6fc825
+  metadata.gz: db2047e49879c399812704702d4064304bf4ac9be8fe25132cc65ac441e2962f7b8c45cf59371727dffaf52caab9accbfb7c8ea0abe1976f264a7a4506e46e6f
+  data.tar.gz: e426da15aeb714ab906df710946ae3b2c96b35509632b9c35efba289d303da519f58e3cd362a8b47c4ba8a9f883e54e657edeb3e09c1934b4cd542f119440678

data/README.md

@@ -106,7 +106,7 @@ https://raw.githubusercontent.com/rigortype/rigor/refs/heads/master/docs/install
 ```
 
 Ready-made prompts — 日本語, 简体中文, 繁體中文, 한국어, Español,
-Português, Français, Deutsch, Italiano, Tiếng Việt, ภาษาไทย,
+Português (Brasil), Português, Français, Deutsch, Italiano, Tiếng Việt, ภาษาไทย,
 Bahasa Indonesia, Polski, Українська, Русский, Română, Türkçe,
 العربية, فارسی — are in
 the [installation guide](https://rigor.typedduck.fail/manual/01-installation/#set-up-in-your-language).
@@ -232,7 +232,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.4.3`** (2026-10-15) — on the
+Current release: **`v0.4.5`** (2026-10-19) — on the
 `0.4.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a
@@ -256,9 +256,9 @@ Mozilla Public License Version 2.0. See [`LICENSE`](LICENSE).
 
 ## Sponsors
 
-Rigor is built and maintained by one person, who has spent the better
-part of the last month — nearly every spare hour of personal time — on
-this project. Sustainable development depends on sustainable funding.
+Rigor is built and maintained by one person, who has put nearly every
+spare hour of personal time into it since development began in April
+2026. Sustainable development depends on sustainable funding.
 
 **The current monthly budget is well short of the $200 minimum needed
 to keep this pace going; $600 or more would let me work on it

data/data/core_overlay/ostruct.rbs

@@ -0,0 +1,40 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- OpenStruct#method_missing (issue #1456) ---
+#
+# rbs 4.2 ships no `ostruct` signatures (since Ruby 4.0 `ostruct` is a bundled
+# gem, not a default one), and the gem ships no `sig/`. The only `OpenStruct`
+# declaration in the environment is json's add-on reopening in
+# `stdlib/json/0/json.rbs` (`json_create` / `as_json` / `to_json`), so the
+# class read as fully declared and `OpenStruct.new(name: "x").name` reported
+# `call.undefined-method`.
+#
+# Upstream: ostruct 0.6.3 `lib/ostruct.rb` defines each field as a
+# per-instance singleton method (`new_ostruct_member!` through
+# `define_singleton_method!`) and answers the rest through
+# `private def method_missing(mid, *args)`, which this file declares. It
+# defines no `respond_to_missing?` of its own (Kernel's answers, and the
+# fields are real singleton methods), so none is declared here.
+#
+# The per-field accessors cannot be declared on the class at all, so
+# `Rigor::Analysis::CheckRules::CORE_OVERLAY_OPEN_RECEIVERS` names
+# `OpenStruct` as an open receiver: an RBS `method_missing` alone does not
+# stop the undefined-method rule. That list is what quiets `rigor check`;
+# this file supplies the declaration the maintainer decision asked for.
+#
+# The declaration sits on a module the class includes, as `process.rbs`
+# does, so a project `sig/` that declares `OpenStruct#method_missing` itself
+# overrides it instead of raising `DuplicatedMethodDefinitionError`.
+#
+# Maintainer decision on #1456 (2026-10-16, option c): this narrow overlay.
+# The general rule for a class declared only by another library's partial
+# reopening is #1978.
+module RigorCoreOverlay
+  module OpenStructMissing
+    private def method_missing: (Symbol mid, *untyped args) -> untyped
+  end
+end
+
+class OpenStruct
+  include RigorCoreOverlay::OpenStructMissing
+end

data/docs/handbook/11-sig-gen.md

@@ -165,6 +165,11 @@ The `sig.skipped.*` reasons are:
   RBS for it, so `--write` and `--check` are unaffected. Its
   JSON row has no `class` key. `def self.x`, a `def` inside a
   block body and one inside `class << obj` are not reported.
+- `sig.skipped.uncertain-module-function` — a bare `public`,
+  `private` or `protected` that may not run (under an `if`, in
+  a block) sits between a bare `module_function` and the
+  method, so it is either a module function or an instance
+  method only. sig-gen writes neither.
 - `sig.skipped.unrenderable-rbs` — the signature Rigor
   rendered for this method does not parse as RBS. This one
   is a **bug in Rigor**, not a property of your code: every
@@ -527,7 +532,13 @@ A declared `untyped` that you wrote in `sig/` is treated
 the same way for a value literal: an Integer, String or
 Symbol the body proves is widened to its class (`-> 1`
 becomes `-> Integer`, `-> ("S" | nil)` becomes
-`-> (String | nil)`), while `nil`, `true`, `false` and a
+`-> (String | nil)`), and `true` or `false` is widened to
+`bool` (written `(false | true)`), so a subclass that
+overrides the method with the other one is not reported as
+widening the return. A body that returns only `nil` keeps
+the `untyped`: it is the shape of a template method a
+subclass fills in, and `-> nil` would make every override
+that returns a value a widening. `nil` inside a union and a
 computed `Float` are proposed as they are. An `untyped` that
 only the inline reader synthesizes for a `def` you did not
 annotate keeps the literal, as does a method no `.rbs`
@@ -590,9 +601,16 @@ list is the current state):
   `attr_writer` / `attr_accessor` ivar reads untyped.
   The accessor, and any other method returning that
   ivar, is skipped even beside a concrete write such as
-  `@logger = Logger.new`, unless `--params=observed`
-  types the constructor parameter the ivar is assigned
-  from. The
+  `@logger = Logger.new`. `--params=observed` types an
+  `attr_reader` from the constructor parameter its ivar
+  is assigned from (`Box.new(0)` gives
+  `def count: () -> 0`) only when that assignment is the
+  ivar's only write in the class's body in that file: an
+  attr writer, a hand-written setter, or a write in any
+  other instance method leaves both reader and writer
+  skipped. A writer declared in another file, in a
+  superclass or module, or through `class_eval` from
+  outside is not seen. The
   generator emits the long-form `def name: () -> T`
   spelling so the writer's merge path applies unchanged;
   existing short-form `attr_reader name: T` declarations
@@ -616,9 +634,28 @@ two are wired today, one is reserved.
 | Policy | Behaviour |
 | --- | --- |
 | `untyped` (default) | Every parameter is spelled `untyped`. No inference-derived parameter contract is imposed on future callers. The user retains complete authorship over parameter typing. |
-| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. With no test root to observe, or a declared root that does not exist, sig-gen says so on stderr. |
+| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to the configured `test_paths:`, or whichever of `spec/` and `test/` exist), union per parameter position, erase to RBS, emit the union. With no test root to observe, or a declared root that does not exist or is not read, sig-gen says so on stderr, and `--format=json` carries the same fact in a top-level `observation` key (below). |
 | `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
 
+Under `--params=observed`, the `--print` / `--diff` JSON payload gains
+a top-level `observation` key next to `candidates`, so a consumer that
+never reads stderr (the MCP `rigor_sig_gen` tool included) can tell
+"no test root was observed" from "the tests pass no typed arguments":
+
+```json
+{ "candidates": [ … ],
+  "observation": { "paths": ["/app/spec"], "missing": ["/app/tests"] } }
+```
+
+`paths` are the roots the collector reads (a directory or a `.rb`
+file); `missing` are the other declared roots: ones that do not exist,
+or exist but are not read (`README.md`). An identical repeat is listed once. `paths: []` with `missing: []` means
+there was no test root at all. Paths are spelled as the run resolved
+them: `--observe=PATH` as typed, `test_paths:` as absolute paths, resolved against the
+config file's directory, auto-detected `spec/` / `test/` absolute. The key is
+absent under `--params=untyped`, and absent from the `--write` and
+`--check` JSON payloads, which have their own shapes.
+
 The default deliberately favours `untyped` because of
 [ADR-5](../adr/5-robustness-principle.md)'s clause 2: a
 method's parameter contract should be the **most permissive**
@@ -704,7 +741,7 @@ output it got before.
 ## RSpec-aware observations
 
 When the observed test roots hold an RSpec suite, the
-generator recognises three RSpec-shaped binding patterns
+generator recognises four RSpec-shaped binding patterns
 and uses them to type receivers that would otherwise
 degrade to `Dynamic[top]`:
 
@@ -712,10 +749,12 @@ degrade to `Dynamic[top]`:
 RSpec.describe Calc do
   subject { Calc.new }         # binds :subject → Nominal[Calc]
   let(:other) { Calc.new }     # binds :other   → Nominal[Calc]
+  before { @calc = Calc.new }  # binds @calc    → Nominal[Calc]
 
   it "..." do
     subject.greet("Alice")     # observed: Calc#greet receives String
     other.greet("Bob")         # observed: same
+    @calc.greet("Carol")       # observed: same
     described_class.new.add(1, 2)  # observed: Calc#add receives Integer, Integer
   end
 end
@@ -724,17 +763,36 @@ end
 The recogniser handles `RSpec.describe Foo`, bare
 `describe Foo` (no `RSpec.` receiver), `subject { … }`,
 `subject(:name) { … }`, `let(:name) { … }`, `let!(:name)`,
-and `described_class.new(...)`. Same-name `let` bindings
-across nested scopes are last-wins; the recogniser does not
-re-implement RSpec's full scope rules — the typical
-one-spec-file shape is the target.
+an ivar assigned by a top-level statement of a `before`
+block, and `described_class.new(...)`. Same-name `subject` /
+`let` bindings across nested scopes are last-wins; the
+recogniser does not re-implement RSpec's full scope rules —
+the typical one-spec-file shape is the target. A `before`
+ivar is scoped: it types reads only inside the `describe` /
+`context` block that holds the `before`, through nested
+`describe` / `context` / `it` / hook blocks but not through
+any other block (`Class.new { … }`, `instance_eval { … }`,
+`each { … }`), and a read that two
+enclosing `before`s assign different classes is not
+observed.
 
 A Minitest suite under `test/` is observed too, with no
 recogniser of its own: a call whose receiver types to one
-class counts. A receiver assigned in `setup` is the gap —
-inside a `test_*` method it reads as `Foo | nil`, and such
-a call is not observed yet
-([#1389](https://github.com/rigortype/rigor/issues/1389)).
+class counts. A receiver assigned in `setup` reads as
+`Foo | nil` inside a `test_*` method, since `setup` is not
+`initialize`; a receiver of that shape — one class or class
+object plus `nil` — is observed as that class when `nil`
+does not answer the method, because such a call cannot
+have been made on `nil`. A call of a method `nil` does
+answer (`==`, `respond_to?`, `is_a?`) is not observed, as
+it may have run on `nil`; with `&.` it is, since `&.` skips
+`nil`. Which methods `nil` answers comes from the loaded
+RBS for `NilClass`, `Object` and `Kernel`, so a method a
+library adds to `nil` (ActiveSupport's `try`, `as_json`)
+counts only when that library's RBS is loaded.
+`@foo&.bar(1)` counts the same way. A receiver
+that could be one of two classes (`Foo | Bar | nil`), or
+`untyped | nil`, is still not observed.
 
 The recogniser is part of the generator itself; you do not
 need to install `rigor-rspec` to benefit from it. If you
@@ -751,14 +809,45 @@ by side without coordination.
   every other byte of the file verbatim.
 - **Will** append a new `class Foo … end` block when the
   target file does not declare the class yet.
+- **Will** treat a method as already declared when a file
+  under the signature tree declares it on the same class
+  with a `def` or an `attr_*` of the same kind (instance or
+  singleton), in any opening of the class in that file. A
+  `def self?.` declares both kinds, and a `def self?.`
+  proposal counts as declared when either kind is. The
+  method is updated (`--overwrite`) or skipped in the file
+  that declares it instead of being added to the class's
+  first file. A replacement lands only on a `def` of the
+  proposal's own kind in the first opening of the class:
+  a `def self?.` proposal over a lone `def self.f` or
+  `def f`, a plain proposal over a `def self?.f`, or a
+  method declared in a later opening is skipped. A
+  `def f: ... | ...` overload is never replaced and never
+  counts as the file that declares `f`. An `alias new old`
+  (or `alias self.new self.old`) declares `new` under its own
+  kind and is never replaced, so a proposal for that name is
+  skipped.
 - **Will not** touch files outside the configured signature
   tree.
+- **Will** name every proposal it skipped, one
+  `  skipped Class#method (reason): <proposed RBS>` line under
+  its target (`Class.method` for a singleton), with the same
+  rows under `skipped` in `--format=json`. The reason is
+  `user-authored` (the target declares the member and the
+  writer does not replace it) or `outside-sig-root` (the
+  member routes to a file in a signature path other than the
+  first, which `--write` does not modify, whether the member
+  is declared there or is new to a class that lives there).
+  A target left unchanged by skips alone prints
+  `unchanged <file>`. The exit status stays `0`: a skip is
+  not a refusal, and `--check` still reports `sig/` as up to
+  date.
 - **Will not** replace an existing method declaration
   unless `--overwrite` is set AND the candidate is a
   `tighter-return`, and then only its return changes: the
   rest of the declaration is kept. Without `--overwrite`,
   existing declarations are user-authored and the new method
-  is silently skipped.
+  is skipped.
 - **Will not** change an existing method declaration that
   disagrees with the method's inline declaration unless
   `--overwrite` is set; it reports the method as `REFUSED`

data/docs/manual/02-cli-reference.md

@@ -224,7 +224,7 @@ rigor type-scan PATH...
 `--show-recognized` includes fully-covered classes,
 `--threshold=RATIO` makes the command exit non-zero when the
 unrecognized-node ratio exceeds `RATIO`, and `--format=text|json`
-selects the output format.
+selects the output format. `--config=PATH` overrides config discovery.
 
 ## `rigor effects`
 
@@ -354,6 +354,8 @@ accept `--config=PATH`, `--format=text|json` and `--full`;
 configured one — `--baseline <(git show
 origin/main:.rigor-effects.yml)` in a bot),
 `--strict-tolerated` and `--no-tolerated-effects`.
+`explain` additionally accepts `--symbol=KEY` to explain one
+specific unit instead of the changed ones.
 
 The file records two tables. `methods:` holds each method's
 **direct** summary — what its own body does, block literals
@@ -476,12 +478,13 @@ Print the catalogue entry for a diagnostic rule, or list every
 rule when called with no argument.
 
 ```sh
-rigor explain [rule]
+rigor explain [options] [rule]
 ```
 
 `rule` is a rule ID (`call.undefined-method`), a legacy alias,
-or a family wildcard (`call`, `flow`, `def`, `assert`, `dump`).
-`--format=json` is available. Exit `64` for an unknown rule.
+or a family wildcard (`call`, `flow`, `def`, `assert`, `dump`, `global`,
+`suppression`, `static`, `effect`).
+`--format=text|json` selects the output format. Exit `64` for an unknown rule.
 
 It also answers the `sig.skipped.*` identifiers `rigor sig-gen`
 prints when it declines to write a signature — `rigor explain
@@ -495,11 +498,13 @@ Compare the current diagnostics against a saved baseline JSON
 and report only what is new.
 
 ```sh
-rigor diff <baseline.json> [paths...]
+rigor diff [options] <baseline.json> [paths...]
 ```
 
 `--current=PATH` compares against a saved diagnostics JSON
-instead of running a fresh check. Exit `1` when new
+instead of running a fresh check. `--format=text|json` selects the
+output format (default `text`), and `--config=PATH` passes a custom
+configuration to the implicit check. Exit `1` when new
 diagnostics appear.
 
 ## `rigor sig-gen`
@@ -533,6 +538,10 @@ refuse a file, so a tighter return `--write` declines without
 `--overwrite` does not fail it; `--check --overwrite` counts one.
 See [handbook chapter 11](../handbook/11-sig-gen.md#keeping-sig-current-in-ci).
 
+`--write` names each proposal it skipped (a member `sig/` already declares, an `alias` included, or one that
+routes to a signature path it does not write to, because it is declared there or its class lives there) on its own `skipped Class#method (reason)` line; the exit status is
+unchanged. See [handbook chapter 11](../handbook/11-sig-gen.md#safety-what---write-will-and-will-not-do).
+
 A method declared inline with `# @rbs` / `#:` is written as that
 declaration, not as what its body infers; a parameter-only
 annotation keeps its parameters and takes the return from the body,
@@ -616,7 +625,8 @@ rigor baseline <generate|regenerate|dump|drift|prune> [options]
 
 `generate` and `regenerate` accept `--output=PATH` and
 `--match-mode=rule|message`; `dump`, `drift`, and `prune` accept
-`--baseline=PATH` to read a non-default baseline file.
+`--baseline=PATH` to read a non-default baseline file. `dump`
+also accepts `--format=text|json` for machine-readable output.
 
 ## `rigor triage`
 
@@ -913,10 +923,11 @@ rigor mcp [--transport=stdio] [--config=PATH]
 ```
 
 `stdio` is the only transport. The server is a pure-Ruby
-JSON-RPC 2.0 implementation exposing seven read-only tools:
-`rigor_check`, `rigor_type_of`, `rigor_triage`,
+JSON-RPC 2.0 implementation exposing eight read-only tools:
+`rigor_check`, `rigor_type_of`, `rigor_triage`, `rigor_lens`,
 `rigor_annotate`, `rigor_sig_gen`, `rigor_explain`,
-`rigor_coverage`.
+`rigor_coverage`. `rigor_lens` writes only the incremental
+cache `rigor check --incremental` writes.
 
 ## `rigor lsp` vs `rigor mcp`
 
@@ -1162,8 +1173,17 @@ Runs a scoped analysis and audits:
 - **Plugin load errors** — whether every configured plugin loaded.
 - **Baseline drift** — whether the current diagnostics have drifted
   from the saved baseline.
-- **Rails plugin gap** — whether `Gemfile.lock` contains Rails gems
-  but no Rails plugin is enabled.
+- **Plugin gap** — whether the project's direct dependencies (the
+  `DEPENDENCIES` section of `Gemfile.lock`, plus the Rails components
+  a direct `rails` stands for) include gems a bundled plugin models —
+  Rails, Devise, Pundit, Sidekiq, ... — while `plugins:` does not list
+  that plugin ([ADR-96](../adr/96-plugin-target-gems.md)). An entry
+  with `enabled: false` counts as listed. Each missing plugin is a
+  warning, since leaving one out can be deliberate; it is a failure
+  only when `plugins:` lists none of the bundled plugins that model
+  gems (those declaring `target_gems:`).
+  Skipped when no `.rigor.yml` or `.rigor.dist.yml` is discovered in
+  the current directory.
 - **Gemfile install** — whether Rigor itself resolves as one of the
   project's dependencies, which
   [Installing Rigor](01-installation.md) tells you not to do. Only a
@@ -1176,6 +1196,16 @@ Runs a scoped analysis and audits:
   versioned together, so a copy from another installation can run
   the engine with a mismatched plugin. A warning, not a failure;
   third-party plugins from your own bundle are never flagged.
+- **Bundle layout** — whether Rigor can locate the bundle a
+  `Gemfile.lock` in the current directory was installed into; when it
+  cannot (typically gems in the active Ruby's default gem home), no
+  gem-shipped `sig/` is discovered. Rigor finds a bundle only where the
+  project records it. A `bundler.bundle_path:` in `.rigor.yml` is used
+  alone and must exist. Without one — and unless
+  `bundler.auto_detect: false` — Rigor reads `.bundle/config`'s
+  `BUNDLE_PATH`, then an in-tree `vendor/bundle`, then the global
+  Bundler config. A warning, not a failure: the default layout is
+  correct, and most gems ship no `sig/`.
 
 Text output prints `[PASS]`, `[FAIL]`, or `[WARN]` per check plus a
 routed hint (e.g. "Run `rigor baseline regenerate`"). JSON output
@@ -1236,6 +1266,7 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 | `0` | Success — no diagnostic at or above the exit threshold (`error` by default; `rigor check --fail-on=SEVERITY` lowers it to `warning` or `info`). |
 | `1` | Diagnostics found at or above the threshold, or a per-command failure (parse error, missing file, new diagnostics on `diff`, effect drift on `effects check`). |
 | `64` | Usage error — unknown command, bad flag, malformed argument, or a value in `.rigor.yml` the loader cannot proceed on. |
+| `70` | Internal fatal error — `SystemStackError` or `NoMemoryError` inside the analysis; Rigor could not finish the run, so its report on disk is empty rather than clean. |
 
 `rigor triage` is the exception: it is advisory and always
 exits `0`.

data/docs/manual/03-configuration.md

@@ -78,7 +78,7 @@ cache:
 | --- | --- | --- | --- |
 | `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
 | `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
-| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. The walker does not follow `require` / `require_relative`, so list the files in load order: a method declared in two files takes the last-listed one, and a file that requires a later-listed one is still read in list order. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. The walker does not follow `require` / `require_relative`, so list the files in load order: a method declared in two files takes the last-listed one, and a file that requires a later-listed one is still read in list order. `type-of`, `type-scan`, `trace`, `annotate` and `sig-gen` read the patches too, so they type a patched method as `rigor check` does. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
 ### Signature generation
@@ -103,6 +103,8 @@ rigor: signature_paths: "/path/to/sig" does not exist (no signatures loaded from
 rigor: signature_paths: "/path/to/sig" matched 0 signature files
 rigor: libraries: "csb" is not an available RBS library (no signatures loaded from it)
 rigor: disable: "call.undefined-methdo" is not a recognized rule id; the suppression has no effect
+rigor: disable: "plugin_loader.load-error" names a run-level row, which `disable:` does not reach; use `severity_overrides:` or a baseline
+rigor: disable: "plugin.shoulda-matchers.unknown-column" names no plugin `plugins:` configures; the suppression has no effect
 rigor: severity_overrides: "flow.bogus" is not a recognized rule id; the override has no effect
 rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
 ```
@@ -125,10 +127,21 @@ the JSON schema as you type rather than at check time.
 These are warnings, not errors — partial or optional bundles and
 forward-looking config are valid setups. The audit only fires on explicit,
 working-setup-safe signals: an unset default (auto-detected `<root>/sig`,
-auto-detected bundle) is never warned about, and a `disable:` /
-`severity_overrides:` token under a *plugin* family (`rspec.…`,
-`rbs_extended.…`) is left alone, since its rule id cannot be enumerated
-statically and may resolve at run time. The same findings appear in the
+auto-detected bundle) is never warned about, and a
+`rbs_extended.…`, `rbs.…` or `dynamic.…` key in `severity_overrides:` or
+`disable:` is left alone, since the engine emits those ids outside the
+catalogue. `disable:` and `severity_overrides:` are both checked
+closely, because what they can reach is known: a plugin's rule counts
+only in its qualified `plugin.<id>.<rule>` form, so a bare plugin rule
+(`rspec.let-binding`) is warned about. A qualified token is checked
+against `plugins:` only when every entry's plugin ID is known without
+loading it — an explicit `id:`, or a bundled plugin's gem name minus
+`rigor-`; one third-party gem listed without `id:` turns that check
+off. A `disable:` token under `rbs_extended.…`, `rbs.…` or `dynamic.…`
+is left alone, other than the reserved run-level rows (`rbs.coverage.…`,
+`dynamic.dependency-source.…`), which are flagged; in `severity_overrides:`
+those rows are the intended keys and are never flagged, while a bare plugin
+rule, `all`, or a `plugin.`-qualified key for an unconfigured plugin is. The same findings appear in the
 `--format=json` payload under `config_warnings` (each tagged with a
 `kind`), so CI can assert on them.
 
@@ -136,9 +149,9 @@ statically and may resolve at run time. The same findings appear in the
 
 | Key | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `disable` | Array | `[]` | Rule IDs or families to suppress project-wide. |
+| `disable` | Array | `[]` | Rule IDs or families to suppress project-wide; `all` suppresses every built-in check rule. A plugin's diagnostics are named by qualified ID (`plugin.<id>.<rule>`, or `plugin.<id>` for the whole plugin); a bare ID or `all` does not reach them. The run-level `.rigor.yml` rows (`plugin_loader.*`, `dynamic.dependency-source.*`, `rbs.coverage.*`, `plugin_trust.*`, `pool-degraded`) are not reached by any spelling; use `severity_overrides:` for those. See [Diagnostics](04-diagnostics.md#suppressing-a-diagnostic). |
 | `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
-| `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
+| `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. A plugin's diagnostics are named by qualified ID (`plugin.<id>.<rule>`, or `plugin.<id>` for the whole plugin); a bare rule or family does not reach them. The plugin loader's own rows are `plugin_loader.load-error` / `plugin_loader.runtime-error` (or the bare `load-error` / `runtime-error`). |
 | `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |
 | `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued changes early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
 

data/docs/manual/04-diagnostics.md

@@ -162,6 +162,15 @@ the diagnostic from the result entirely, which makes
 below — both silence a rule; the override reads as "this one
 rule, at this severity" alongside the rest of the profile.
 
+A plugin's diagnostic is named by its qualified ID, as in `disable:`:
+`plugin.<id>.<rule>` for one rule (`plugin.rails-i18n.load-error: off`),
+or `plugin.<id>` for every row of that plugin. A bare rule or a family
+never reaches a plugin's row, so `load-error: off` leaves each plugin's
+own `load-error` alone. The plugin loader's rows are
+`plugin_loader.load-error` and `plugin_loader.runtime-error`, which also
+answer to the bare `load-error` / `runtime-error`. `rigor check` warns
+about a key it can tell reaches no row.
+
 YAML reserves the bareword `off` as a boolean. If an override
 that names it seems not to apply, quote it — `"off"` — and the
 same for `on`.
@@ -252,8 +261,14 @@ named rules on that line:
 config.merge(extra)  # rigor:disable call.undefined-method
 ```
 
-It accepts qualified IDs, family wildcards (`call`), a
-comma- or space-separated list, or `all`. The comment must sit
+It accepts qualified IDs, family wildcards (`call`, `flow`, `def`, `assert`,
+`dump`, `global`, `suppression`, `static`, `effect`, `pre-eval`), a
+comma- or space-separated list, or `all`. A plugin's diagnostic
+is reached only by its qualified ID as printed in brackets
+(`plugin.shoulda-matchers.unknown-column`) or by the plugin's
+whole family (`plugin.shoulda-matchers`); its bare rule
+(`unknown-column`) and `all` leave it alone, because several
+plugins share bare rules. The comment must sit
 on the line the diagnostic points at; there is no
 `disable-block` form, so an expression spread over several
 lines needs the comment on each line that fires.
@@ -283,7 +298,8 @@ suppressible like any other rule.
 
 **In-source, whole file.** `# rigor:disable-file <rules>`
 anywhere in a file suppresses those rules for every line;
-`# rigor:disable-file all` silences the file. Convention is to
+`# rigor:disable-file all` silences every built-in rule in the file
+(a plugin's diagnostics need their qualified ID, as above). Convention is to
 put it near the top — typically on a generated file, a fixture,
 or a vendored snippet — but every comment in the file is
 scanned, so any placement works.
@@ -300,6 +316,43 @@ disable:
   - flow.dead-assignment
 ```
 
+`disable: [all]` turns off every built-in check rule, including
+`effect.annotations-unchecked`, which is reported at a signature
+file.
+
+A plugin's own diagnostics are turned off by their qualified ID —
+`plugin.<id>.<rule>` for one rule, `plugin.<id>` for every rule
+of that plugin:
+
+```yaml
+disable:
+  - plugin.shoulda-matchers.unknown-column
+  - plugin.rails-i18n
+```
+
+A bare rule (`unknown-column`, `load-error`) and `all` do not
+reach them, so one plugin's suppression never hides another
+plugin's finding of the same name.
+
+The list does not reach the run-level rows reported at
+`.rigor.yml` — a plugin that failed to load or raised in
+`prepare` (`plugin_loader.*`), a `dependencies.source_inference:`
+gem that did not resolve (`dynamic.dependency-source.*`), the
+`rbs.coverage.*` notices, `plugin_trust.*`, `pool-degraded` —
+under any spelling, `plugin_loader.load-error` included. Turn
+those off with [`severity_overrides:`](#severity-profiles) set
+to `off`, or record them in a [baseline](06-baseline.md).
+In `severity_overrides:` the plugin loader's rows are
+`plugin_loader.load-error` and `plugin_loader.runtime-error`, or the
+bare `load-error` / `runtime-error` (the qualified key wins if both
+are set); a bare key does not reach a
+plugin's own row of the same name (`plugin.<id>.load-error`). `rigor check` warns when a
+`disable:` entry names one of these rows, names no rule at all,
+or names a plugin `plugins:` does not configure (see
+[Config validation warnings](03-configuration.md#config-validation-warnings)).
+A path or parse error, which has no rule ID, is always
+reported.
+
 For a *known backlog* you want to keep visible but not fail
 on, prefer a [baseline](06-baseline.md) over a blanket
 `disable:` — `disable:` also hides any new occurrences.

data/docs/manual/05-inspecting-types.md

@@ -2,8 +2,8 @@
 
 Rigor's analysis is invisible by default — it only speaks up to
 report a diagnostic. When you want to *see* what type the
-engine assigns an expression, there are four tools: two source
-helpers and two CLI commands.
+engine assigns an expression, there are six tools: two source
+helpers and four CLI commands.
 
 ## `dump_type` — print a type from source
 

data/docs/manual/06-baseline.md

@@ -73,7 +73,7 @@ a diagnostic another layer has already suppressed.
 | --- | --- |
 | `rigor baseline generate` | Write a fresh baseline from the current diagnostics. Refuses to clobber an existing file without `--force`. |
 | `rigor baseline regenerate` | Rewrite unconditionally — run it after fixing diagnostics so the file shrinks. |
-| `rigor baseline dump` | Print the baseline, filterable with `--rule` and `--file`. |
+| `rigor baseline dump` | Print the baseline, filterable with `--rule` and `--file` (`--format=json` for tooling). |
 | `rigor baseline drift` | Show how buckets have moved — `--only=over` for buckets that grew, `reducible` for ones you have already improved past, `cleared` for empty ones. |
 | `rigor baseline prune` | Drop buckets that match nothing any more. `--dry-run` previews. |
 

data/docs/manual/07-plugins.md

@@ -5,7 +5,8 @@ application DSL that plain inference cannot see — Rails route
 helpers, RSpec `let` bindings, dry-rb struct attributes, and
 so on. This page is about *activating* plugins. Writing one is
 covered by [`examples/`](../../examples/README.md) and the
-[`rigor-plugin-author` skill](08-skills.md).
+[`rigor-plugin-author` skill](08-skills.md); reviewing and modernising
+an existing plugin is [`rigor-plugin-review`](08-skills.md).
 
 ## Activating a plugin
 
@@ -95,7 +96,7 @@ with the `plugins_isolation:` configuration key or the
 | --- | --- |
 | `process` (default) | Run the call in a forked, crash-contained worker, so the target library's monkey-patches and any crash never contaminate Rigor. Falls back to `none` where `fork` is unavailable (Windows / JRuby). |
 | `none` | Load the library into Rigor's own process and call it directly. |
-| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
+| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. The same check runs when `RUBY_BOX=1` is already in your environment: without the fix, the launcher prints a notice and restarts itself without `RUBY_BOX`, so the run completes but plugins are not boxed. The check result is cached per Ruby build under `$XDG_CACHE_HOME/rigor` (or `~/.cache/rigor`) and never expires, so if you rebuild a Ruby in place with the fix, delete `$XDG_CACHE_HOME/rigor/ruby-box-probe` (or `~/.cache/rigor/ruby-box-probe`). A check that times out is not cached, so it costs up to ten seconds on every run. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
 
 The environment variable wins over `plugins_isolation:`, so you can
 override a project's committed choice for one invocation. The legacy

data/docs/manual/08-skills.md

@@ -87,6 +87,10 @@ is not repeated here.)
 - **`rigor-monkeypatch-resolve`** — resolves an `undefined-method`
   cluster that is really your project's own monkey-patches by wiring the
   defining files into `pre_eval:`.
+- **`rigor-unused-adjudicate`** — adjudicates a `rigor unused` report
+  safely before proposing dead-code removals, checking framework roots
+  and false-positive shapes. See
+  [Removing dead code with `rigor unused`](18-removing-dead-code.md).
 - **`rigor-type-oracle`** — sources every type an agent writes from
   Rigor (`type-of` / `annotate` / `sig-gen`) instead of from reading the
   code, and reports the gaps rather than filling them. It is triggered by
@@ -119,6 +123,9 @@ is not repeated here.)
   repository to teach Rigor an application DSL or metaprogramming
   pattern it cannot infer. Reach for it when no bundled plugin covers a
   framework or DSL your project depends on.
+- **`rigor-plugin-review`** — audits an existing Rigor plugin against
+  the current authoring contract and produces a prioritized upgrade
+  path. The review/upgrade counterpart to `rigor-plugin-author`.
 
 ## Discovering skills from the CLI