rigortype 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a09068aa2810a8d01758e3ce78f52dc6020f0d197bb83a561684b96969e5eddf
-  data.tar.gz: 0105753f063477bea3a85ba3dea3fe660fbe58d846d9388867eafd3b6fed1055
+  metadata.gz: 608dc6b03dfc9267330c24c6493f3f4ee2d025ac5ce01a044202828fc282e258
+  data.tar.gz: 395692680ea16ec6dc42d4187fc57c10ce00731eea4cd1d03176fcc2daa07c14
 SHA512:
-  metadata.gz: fb111fc503dbb60810cbcdf4bfb0a717f694f771fe16bf41007ef1b9eb2728014aa19d112183e79652e4a1ae03c09d6e227ad13ebc063a9804b7a6ba916ae71b
-  data.tar.gz: 4c3d925ef588248fbd84529262632bcfa5e081eedd340c164f0de89b3a0f83abd5cdaad37be922a90571068966ec204f77e075993994db8b106abbaa8d135cd8
+  metadata.gz: c7145aafeaf9fd22fe3759970c9b4eaafd8720796048641a387ec7a02d4e579689fde37540db686da9904b7d8419a6338b9db7caa38997d7184960c346253f5a
+  data.tar.gz: bff814da943de361c7c1e5bee99fd0e4847d16bb8a9bd3e36609e69246e8eb0e141c6c6e87b425720d709e2277195d9a14100a3018fef75670361fe2acd2160b

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.4`** (2026-10-16) — on the
+Current release: **`v0.4.6`** (2026-10-23) — 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/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,8 +532,23 @@ 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
-computed `Float` are proposed as they are. An `untyped` that
+`-> (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. A literal inside a tuple, a
+record or a type argument is widened the same way while the
+shape stays (`-> [1, "a"]` becomes `-> [Integer, String]`,
+`-> { a: 1 }` becomes `-> { a: Integer }`); of the generic
+types, only the arguments of `Array`, `Hash`, `Set`, `Range`
+and `Enumerator` are widened. `nil` inside a union or a shape
+and a computed `Float` are proposed as they are. When the
+method also carries an inline `# @rbs` annotation for its
+parameters only, a return holding a literal that would be
+widened, nested or not, is not proposed at all and the
+`untyped` stays. An `untyped` that
 only the inline reader synthesizes for a `def` you did not
 annotate keeps the literal, as does a method no `.rbs`
 declares — the literal is still the strictest thing the body
@@ -590,9 +610,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 +643,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 +750,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 +758,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 +772,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
@@ -765,16 +832,31 @@ by side without coordination.
   `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` in
-  `sig/` is not yet recognised as declaring its name.
+  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

@@ -28,15 +28,25 @@ rigor check [paths...]
 `paths` are files or directories; when omitted, Rigor checks
 the `paths:` list from the configuration file.
 
+Only the files you name are reported on, but Rigor reads the
+declarations in the configured `paths:` too, so a file resolves a
+class or constant that another file declares. A file outside
+`paths:` also reads the files it loads with a literal
+`require_relative "..."`, and the files those load in turn. Their
+classes, modules and constants resolve and their methods count as
+defined, but Rigor does not infer what those methods return or
+check their arity, since another file may redefine them.
+
 | Option | Effect |
 | --- | --- |
-| `--config=PATH` | Use a specific config file instead of auto-discovery. |
+| `--config=PATH` | Use a specific config file instead of auto-discovery. A path that does not exist is an error (exit 64), not a run with the defaults. |
 | `--format=FORMAT` | Output format. Default `text`. Also `json` (structured stream), plus the CI-native renderings `sarif`, `github`, `gitlab`, `checkstyle`, `junit`, and `teamcity` — see [Running Rigor in CI](11-ci.md). |
 | `--no-ci-detect` | Disable CI auto-detection — by default `text` output also emits the running CI's native annotations / hint (`RIGOR_CI_DETECT=0` does the same). See [Running Rigor in CI § auto-detection](11-ci.md). |
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
 | `--no-cache` | Skip the persistent cache for this run. With `--incremental` it is a cold full analysis: the incremental snapshot and the run-result cache are neither read nor written, so the next plain `--incremental` run still uses the snapshot it had before. |
 | `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. A run with nothing changed is answered from the cache without starting the analyzer. See [Caching](12-caching.md). |
-| `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics agree as a set and in the same order, then exit (0 on match, 1 on mismatch: the differing diagnostics for a set mismatch, or the first index where the order diverges for a same-set, different-order mismatch). Used in CI to guarantee `--incremental` never serves a stale result. |
+| `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics agree as a set and in the same order, then exit (0 on match, 1 on mismatch: the differing diagnostics for a set mismatch, or the first index where the order diverges for a same-set, different-order mismatch). It re-analyses half of an unchanged tree and serves the other half from cache, so it checks the cache-merge path but not that an edit re-checks every file it affects; `--verify-incremental-edits` adds that. |
+| `--verify-incremental-edits=N` | With `--verify-incremental` (and implying it): after the check above, replay two edits on each of `N` files spread over the analysed list, through an editor buffer, never on disk: the file emptied, then the file reduced to its `class` / `module` declarations with every body dropped (skipped when that is the file itself, or holds no declaration). After each edit, the warm recheck of the baseline must equal a full analysis of the edited tree, or the run fails naming the edit and the file. Each replay costs a recheck and a full analysis. A replay the recheck declines (it would have been a full analysis) is counted in the OK line, and the run fails if every replay declined. Only these two removals are replayed, never an addition. Default 0. |
 | `--clear-cache` | Delete the cache directory before running. |
 | `--cache-stats` | Print the on-disk cache inventory when finished — on stdout under `--format text`, on stderr under every other format, so machine-readable output stays a parseable document. `--clear-cache`'s and `--verify-incremental`'s notes follow the same rule. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
@@ -60,7 +70,9 @@ that want the stricter reading.
 ### Editor mode scope
 
 `--tmp-file` / `--instead-of` on their own analyse **only** the
-buffer's file: fast, and blind to what the unsaved edit does to the
+buffer's file. It still reads the rest of the project's declarations
+(the classes and methods other files define), as `rigor check FILE`
+does, but it reports nothing about what the unsaved edit does to the
 rest of the project.
 
 Adding `--incremental` analyses the **whole project with the buffer
@@ -138,6 +150,19 @@ truncation explicit. `--trace` records fail-soft fallbacks,
 after the rows of a line table in text output. The editor-mode
 `--tmp-file` / `--instead-of` pair is accepted as on `check`.
 
+A class or constant that another project file declares reads as
+`rigor check` types it (`singleton(User)`) when a bare
+`rigor check --incremental` has left a snapshot for the project:
+`type-of` folds the cross-file declarations from that snapshot's
+per-file bundles, re-reading any file whose bytes changed since,
+and never writes it. With no reusable snapshot (none yet, or one a
+change made unusable, for example a changed configuration, lockfile, `sig/`, `pre_eval:`
+file or required feature, an engine upgrade, or a snapshot written
+for other roots) the probe types the one file on its own, so such a name reads
+`Dynamic[top]`, and it prints nothing about it. Only those
+declarations are shared: the types `check` infers for an unannotated
+parameter are not.
+
 A template a plugin compiles into Ruby (an ERB view under
 `rigor-actionpack`) is probed the way `rigor check` analyses
 it: the compiled Ruby is typed under the view's declared
@@ -162,7 +187,9 @@ and is probed as plain Ruby, parse error included.
 
 The four probe commands — `type-of`, `type-scan`, `trace` and
 `annotate` — build their environment fresh on every invocation
-and never read or write the persistent cache. That is why none
+and never read or write the persistent cache (apart from the
+read-only snapshot lookup `type-of` makes for the project's
+declarations, above). That is why none
 of them takes `--no-cache`: the flag would have nothing to skip.
 A probe therefore types against the environment `rigor check
 --no-cache` analyses with. The environment a cached (default)
@@ -224,7 +251,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 +381,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 +505,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 +525,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`
@@ -527,12 +559,22 @@ rigor sig-gen [paths]
 | `--no-cache` | Do not read or write the analysis cache. Only effect collection uses it. |
 | `--format=text\|json` | Output format. |
 
+A `paths` argument that does not exist, or is neither a directory nor a `.rb` file, is reported the way
+`rigor check` reports it: on stderr as `path:1:1: error: …`, or under `diagnostics` in `--print` and `--diff`
+JSON output. When no argument is readable this exits `1`, under every mode, `--write` and `--check` included.
+The configured default `paths:` count too, so `paths: [lib]` with no `lib/` directory exits `1`. A `--config`
+that names no file, is a directory, or is empty is a usage error and exits `64`.
+
 `--print`, `--diff`, `--write` and `--check` are mutually exclusive.
 `--check` fails exactly when `--write` would create, change or
 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 +658,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`
 
@@ -630,7 +673,7 @@ rigor triage [paths]
 
 `--top=N` sets the hotspot count (default 10); `--hints-only`,
 `--selectors-only`, and `--no-hints` select which sections print.
-`triage` is advisory and always exits `0` — it never gates a build.
+`triage` is advisory and exits `0` once it runs — it never gates a build; a usage error exits `64`.
 
 By default the distribution, selectors, and hotspots sections count
 only the **actionable** diagnostics (`error` + `warning`). `info`
@@ -936,6 +979,11 @@ loaded from (a `path:` line in text, a `"path"` key in JSON), so
 if a stale installed gem is shadowing a newer checkout's bundled
 plugin copy the mismatch is visible at a glance.
 
+A plugin that declares `per_invocation_classes:` or
+`per_invocation_non_action_macros:` ([ADR-125](../adr/125-per-invocation-classes.md))
+also gets a line for each in text, and a key in JSON (an empty
+array when it declares none).
+
 ```sh
 rigor plugins [--format=text|json] [--strict] [--capabilities] [--config=PATH]
 ```
@@ -1163,8 +1211,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
@@ -1177,6 +1234,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
@@ -1237,9 +1304,11 @@ 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`.
+`rigor triage` is the exception: it is advisory and exits `0`
+whenever it runs to completion. A usage error, such as a
+`--config` that names no file, still exits `64`.
 
 A configuration mistake prints one `rigor:` line naming the key
 and nothing else — no backtrace, on every command:

data/docs/manual/03-configuration.md

@@ -67,7 +67,7 @@ cache:
 | `target_ruby` | String | `"4.0"` | The lowest Ruby version *your* project runs on — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. Every value selects the syntax Rigor parses. A version you set explicitly also turns on the Ruby-deprecation rules for that version ([`call.deprecated-ruby2-keywords`](04-diagnostics.md#rule-call-deprecated-ruby2-keywords) from `"4.1"`); the default and `"latest"` never do, which is why `rigor init` writes the key commented out. |
 | `paths` | Array | `["lib"]` | Directories or files to analyse. |
 | `exclude` | Array | `[]` | Glob patterns to skip. A relative pattern is matched against the file's path relative to the directory of the config file in use (the working directory when no config file is used), so it excludes the same files whether the path came from `paths:` or from a command-line argument, and it never matches on a directory above that base (a file outside it is seen as `../…`, so `../shared/lib/gen/**` reaches a sibling directory that `paths:` names). A leading `./` is ignored, and a pattern starting with `.` (such as `.*`) also matches files outside the base, which appear as `../…`. A symlink to a file is matched only under its own name: the realpath pass resolves directories, not files. `*` and `**` also cross `/`, so `lib/*.rb` matches nested files too. An absolute pattern is matched against the absolute path. Patterns from an `includes:` file resolve against the top-level config's directory, not the included file's. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
-| `test_paths` | Array | `nil` | The project's test roots: the directories (or files) holding its tests. Relative entries resolve against the config file's directory. Unset auto-detects whichever of `spec/` and `test/` exist; `[]` declares none. `rigor sig-gen --params=observed` reads call sites there to type parameters, and names on stderr a declared root that does not exist. Test roots are not analysed unless `paths:` also lists them, and changing them invalidates no cache. |
+| `test_paths` | Array | `nil` | The project's test roots: the directories (or files) holding its tests. Relative entries resolve against the config file's directory. Unset auto-detects whichever of `spec/` and `test/` exist in the config file's directory, or in the working directory when the config file's directory has neither or no config file is used; `[]` declares none. `rigor sig-gen --params=observed` reads call sites there to type parameters, and names on stderr a declared root that does not exist. Test roots are not analysed unless `paths:` also lists them, and changing them invalidates no cache. |
 | `includes` | Array | `[]` | Other config files to layer underneath this one. |
 | `fold_platform_specific_paths` | Boolean | `false` | Resolve Ruby-version-conditional load paths when discovering sources. |
 | `parameter_inference` | Boolean | `false` | Opt-in call-site parameter type inference on the `check` walk ([ADR-67](../adr/67-parameter-type-inference.md) WD6). When `true`, an undeclared `def` / `initialize` / setter parameter is typed to the union of its resolved call-site argument types, sharpening downstream ivar reads, folds, and protection coverage. Precision-additive only — the negative rules never fire against an inferred parameter. Cannot be combined with `--incremental`. |
@@ -106,6 +106,7 @@ rigor: disable: "call.undefined-methdo" is not a recognized rule id; the suppres
 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: severity_overrides: "undefined-method" is a legacy alias of `call.undefined-method`; the override has no effect, so write `call.undefined-method`
 rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
 ```
 
@@ -128,18 +129,20 @@ 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
-`severity_overrides:` key under a non-built-in family (`rspec.…`,
-`rbs_extended.…`) is left alone, since its rule id cannot be enumerated
-statically and may resolve at run time. `disable:` is checked more
-closely, because what it can reach is known: a plugin's rule counts
+`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 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. The same findings appear in the
+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.
 
@@ -149,7 +152,7 @@ alone, other than the reserved run-level rows (`rbs.coverage.…`,
 | --- | --- | --- | --- |
 | `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

@@ -67,7 +67,7 @@ carries no `documentation_url`.
 | <a id="rule-flow-return-in-ensure"></a>`flow.return-in-ensure` | An explicit `return` inside an `ensure` clause — it overrides the method's in-flight return value and silently swallows any in-flight exception. A `return` in a nested `def`, lambda, or `define_method` block inside the `ensure` does not fire (it exits that inner frame). | high |
 | <a id="rule-flow-shadowed-rescue-clause"></a>`flow.shadowed-rescue-clause` | A `rescue` clause can never run because an earlier clause of the same chain already catches a superclass (or the same class) of every exception class it names. | high |
 | <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
-| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write, unless its RBS declaration (`@x: T` or an `attr_*` member) admits both writes. | high |
+| <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write, unless its RBS declaration (`@x: T` or an `attr_*` member) admits both writes. With `rigor-actionpack` or `rigor-actionmailer` loaded, writes in two different actions of a controller or mailer are not compared, since Rails runs one action per instance. A write in a private or protected helper, `initialize` or the same action still is, and so is one in a callback target or `helper_method` that a macro in the same file names. A public method named only by a macro in another file or a concern, or reached through a lambda callback, counts as an action, and so does an action another action calls. | high |
 | <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
 | <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
@@ -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,7 +261,8 @@ named rules on that line:
 config.merge(extra)  # rigor:disable call.undefined-method
 ```
 
-It accepts qualified IDs, family wildcards (`call`), a
+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
@@ -332,10 +342,11 @@ gem that did not resolve (`dynamic.dependency-source.*`), the
 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).
-`severity_overrides:` matches the row's rule ID without the
-source prefix, so the plugin loader's rows are `load-error` and
-`runtime-error` there — and that key also re-stamps any plugin
-diagnostic whose bare rule is the same. `rigor check` warns when a
+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)).

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
 

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