rigortype 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a09068aa2810a8d01758e3ce78f52dc6020f0d197bb83a561684b96969e5eddf
-  data.tar.gz: 0105753f063477bea3a85ba3dea3fe660fbe58d846d9388867eafd3b6fed1055
+  metadata.gz: 4da9b991a97cd586806b416facb6dbf6c3a3b938c7c9433e330bc44c0757fdaf
+  data.tar.gz: 1167e8d91ccbc8740ac4094f67db82937bd3b374d2488a43e514f7922c7a98b1
 SHA512:
-  metadata.gz: fb111fc503dbb60810cbcdf4bfb0a717f694f771fe16bf41007ef1b9eb2728014aa19d112183e79652e4a1ae03c09d6e227ad13ebc063a9804b7a6ba916ae71b
-  data.tar.gz: 4c3d925ef588248fbd84529262632bcfa5e081eedd340c164f0de89b3a0f83abd5cdaad37be922a90571068966ec204f77e075993994db8b106abbaa8d135cd8
+  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.4`** (2026-10-16) — 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/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
@@ -765,16 +823,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

@@ -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`
 
@@ -1163,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
@@ -1177,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
@@ -1237,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

@@ -128,18 +128,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 +151,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

@@ -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
 

data/docs/manual/10-mcp-server.md

@@ -391,6 +391,13 @@ Generate RBS skeleton signatures inferred from Ruby source files.
 project's test roots: the configured `test_paths:`, or whichever of
 `spec/` and `test/` exist.
 
+Under `params: "observed"` the response also carries a top-level
+`observation` object, `{"paths": [...], "missing": [...]}`: the test
+roots that were read and the declared ones that do not exist or that
+the collector would not read (neither a directory nor a `.rb` file). Both
+empty means no test root was found, so every parameter stays `untyped`.
+The key is absent under the default `untyped` policy.
+
 **Returns:** JSON — the same as `rigor sig-gen --print --format json`.
 
 ```json
@@ -430,7 +437,7 @@ Look up the description of one or all Rigor diagnostic rules.
 
 Accepted values: a canonical rule ID (`call.undefined-method`), a
 legacy alias (`undefined-method`), or a family prefix (`call`, `flow`,
-`assert`, `dump`, `def`).
+`def`, `assert`, `dump`, `global`, `suppression`, `static`, `effect`).
 
 **Returns:** JSON — an array of rule catalog entries.
 

data/docs/manual/18-removing-dead-code.md

@@ -6,7 +6,9 @@ into a finite list of specific questions. It does not answer them.
 
 The command reference — every flag, every output section — is in
 [CLI reference](02-cli-reference.md#rigor-unused). This chapter is the
-workflow around it.
+workflow around it. For an AI coding agent, the bundled
+[`rigor-unused-adjudicate`](08-skills.md) skill walks through this
+adjudication workflow step by step.
 
 **Before you start** you need a working `rigor check` setup: a config
 file with `paths:`, and the plugins for your framework enabled. See
@@ -270,12 +272,21 @@ implicit, `self` or `self.class` inside a method (or a block in a class
 body, such as a lambda or `define_method`), the call may run on a
 subclass or on an includer, so a `Handler` declared in a descendant is
 kept reachable too. Descendants are the classes written `class D < Base`
-and the declarations whose body has a plain `include`, `prepend` or
-`extend` of the module; `K.include(Mix)`, `K.send(:include, Mix)`,
-`K.extend(Ext)` and `K = Class.new(Base)` are not followed yet. A call
-written directly in a class body is not widened. Inside
-`Other.instance_eval { }` (or `class_eval`, `module_eval` and their
-`_exec` forms) the receiver is `Other`. A name built into a
+or `K = Class.new(Base)`, and the classes that `include`, `prepend` or
+`extend` the module in their body or through a receiver Rigor can name:
+`K.include(Mix)` in an initializer, its `send`, `public_send` and
+`__send__` spellings, or `include Mix` inside `K.class_eval { }`. A call written directly in a
+class body is not widened. Inside `Other.instance_eval { }` (or
+`class_eval`, `module_eval` and their `_exec` forms) the receiver is
+`Other`, and a method the block defines (`def`, `define_method`,
+`define_singleton_method`) runs on `Other` or a descendant. When the
+receiver cannot be named at all, the name is kept wherever it is
+declared: an eval block on a local variable (`k.class_eval { }`), the
+module's own lookups when such a receiver includes it, or a class that
+includes a computed module (`K.include(mods.first)`). A class that gains
+a module through a receiver Rigor cannot name (`[Foo].each { |k|
+k.include(Consts) }`, an `include` in a `Class.new` block) is not
+followed for its own lookups of that module's constants. A name built into a
 local variable first (`name = "V#{version}"; const_get(name)`) is read
 the same way. A
 class name appearing as a string in a `.yml`, `.json` or template file