rigortype 0.3.8 → 0.3.9

data/docs/handbook/appendix-type-theory.md

@@ -19,7 +19,7 @@ specification](../type-specification/README.md), the spec binds.
 | What about types that may or may not match? | Gradual consistency (`~`) | The `Dynamic[T]` carrier and the trinary certainty `yes / no / maybe` |
 | How are user types identified? | Nominal vs structural | **Nominal-first hybrid** — classes by name, plus structural facets (`interface`, `HashShape`, capability roles) |
 | How are generics expressed? | Parametric polymorphism (System F-style, but predicative) | RBS generics `class Array[Elem]`, method generics `def map: [U] () { (Elem) -> U } -> Array[U]` |
-| How is "x is a non-empty string" expressed? | Refinement / predicate subtyping | First-class refinement carriers (`non-empty-string`, `int<min, max>`, …) |
+| How is "x is a non-empty string" expressed? | Refinement / predicate subtyping | First-class refinement carriers (`non-empty-string`, `Integer[min..max]`, …) |
 | How does `if x.is_a?(String)` change `x`'s type? | Occurrence typing / flow-sensitive narrowing | Edge-aware narrowing with trinary certainty |
 | What about side effects? | Effect systems | The engine's effect model (mutation, exception, escape) — internal, not user-visible |
 | Soundness or completeness? | Pick one (or neither) | **Neither in full** — Rigor optimises for no-false-positives, with a robustness-principle bias |
@@ -528,7 +528,7 @@ refinements with reserved names:
 | `non-empty-string` | `s : String, s.size >= 1` | refinement on `String` |
 | `numeric-string` | `s : String, s =~ /\A[+-]?\d+(\.\d+)?\z/` | refinement on `String` |
 | `literal-string` | "provably built from literals" | refinement on `String` |
-| `int<min, max>` | `n : Integer, min <= n <= max` | range carrier |
+| `Integer[min..max]` | `n : Integer, min <= n <= max` | range carrier |
 | `non-zero-int` | `n : Integer, n != 0` | refinement on `Integer` |
 | `positive-int` | `n : Integer, n > 0` | refinement on `Integer` |
 | `non-empty-array[T]` | `arr : Array[T], arr.size >= 1` | refinement on `Array[T]` |
@@ -1491,7 +1491,7 @@ here so you can stop looking:
   and Rigor does not synthesise it.
 - **Full dependent types.** No `Vec[n, T]` with `n : Integer`.
   Type-checking is decidable but inference is not; integer-range
-  refinements (`int<min, max>`) cover the most common practical
+  refinements (`Integer[min..max]`) cover the most common practical
   need without crossing the line.
 - **Row polymorphism as a user-quantifiable axis.** `HashShape`
   carries open-vs-closed semantics internally but does not
@@ -1581,7 +1581,7 @@ they map to the sections of this appendix:
   matching and exhaustiveness."
 - Rondon, Kawaguchi & Jhala. "Liquid Types." *PLDI 2008.* The
   refinement-types-with-SMT framework that informs the
-  `int<min, max>` carrier (Rigor uses a much weaker, decidable
+  `Integer[min..max]` carrier (Rigor uses a much weaker, decidable
   fragment).
 - Lucassen & Gifford. "Polymorphic Effect Systems."
   *POPL 1988.* Origin of effect systems.

data/docs/handbook/appendix-typescript.md

@@ -101,7 +101,7 @@ positive, an array that is provably non-empty.
 | --- | --- | --- |
 | `non-empty-string` | `\`${string}${string}\`` (template literal trick) or branded `NonEmptyString` | Awkward in TS; Rigor produces it from `unless s.empty?` automatically. |
 | `positive-int` | branded `PositiveInt` | TS users tend to skip the brand — Rigor narrows from `n > 0`. |
-| `int<1, 9>` | union of literal types `1 \| 2 \| 3 \| ... \| 9` | Rigor's range carrier handles arbitrary bounds without exploding. |
+| `Integer[1..9]` | union of literal types `1 \| 2 \| 3 \| ... \| 9` | Rigor's range carrier handles arbitrary bounds without exploding. |
 | `numeric-string` | (none useful) | TS has no equivalent; Rigor narrows from regex matches against numeric patterns. |
 | `non-empty-array[T]` | `[T, ...T[]]` (tuple-with-rest) | TS has the encoding but few APIs use it; Rigor produces it from `unless arr.empty?`. |
 

data/docs/llms.txt

@@ -42,6 +42,8 @@ Skill with `rigor skill <name>`. (The canonical web copy is
 - `15-type-protection-coverage` — `rigor coverage --protection`.
 - `16-rbs-extended-annotations` — the `%a{rigor:v1:…}` annotations.
 - `17-driving-improvement` — the `rigor-next-steps`-driven improvement loop.
+- `18-removing-dead-code` — working `rigor unused` as a campaign on an old codebase.
+- `19-effect-labels` — `rigor effects`, the `.rigor-effects.yml` snapshot, and `%a{pure}`.
 
 ## Handbook (read with `rigor docs <name>`)
 

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

@@ -45,6 +45,7 @@ the `paths:` list from the configuration file.
 | `--baseline=PATH` | Load a baseline file, overriding config. |
 | `--no-baseline` | Ignore any configured baseline. |
 | `--baseline-strict` | Fail the run on any baseline drift — a CI gate. |
+| `--fail-on=SEVERITY` | Exit non-zero when a diagnostic at or above `SEVERITY` (`error`, the default; `warning`; or `info`) survives baseline filtering — raises the exit-status bar above the default `:error`-only reading for CI gates that want it, without changing `--format json`'s `success` / `error_count` fields. |
 | `--treat-all-as-inline-rbs` | Force-load `rigor-rbs-inline` with `require_magic_comment: false`, so every analysed file is treated as inline-RBS without the `# rbs_inline: enabled` comment (ADR-32). |
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
@@ -52,7 +53,9 @@ the `paths:` list from the configuration file.
 | `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
-any are reported, `64` on a usage error.
+any are reported, `64` on a usage error. `--fail-on` raises that
+bar to `warning` or `info` for callers (CI gates, `make check`)
+that want the stricter reading.
 
 ### Editor mode scope
 
@@ -135,6 +138,17 @@ 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`.
 
+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
+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)
+`rigor check` builds is meant to be identical, and Rigor gates
+the two builds against each other — but if you are chasing a
+disagreement between a probe and a `check` run, comparing
+against `rigor check --no-cache` removes that variable.
+
 ## `rigor trace`
 
 Replay HOW the engine typed a file, step by step, as a
@@ -429,6 +443,12 @@ rigor explain [rule]
 or a family wildcard (`call`, `flow`, `def`, `assert`, `dump`).
 `--format=json` is available. 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
+sig.skipped.untyped-return` says what the skip means and what to do
+instead. Those are not diagnostic rules, so they are rendered without
+a severity or a suppression line.
+
 ## `rigor diff`
 
 Compare the current diagnostics against a saved baseline JSON
@@ -481,6 +501,8 @@ not overwrite) is never a silent absence: under `--format=json`
 it is a `skipped` row of the `candidates` array with its
 `sig.skipped.*` identifier in `skip_reason`, and in text mode a
 one-line stderr summary counts the skipped methods per reason.
+`rigor explain sig.skipped.untyped-return` (or any of the other skip
+identifiers) explains what the reason means and what to do about it.
 
 ## `rigor lsp`
 
@@ -577,6 +599,12 @@ see. That is why this is a separate command and never a `rigor check`
 diagnostic — see
 [ADR-102](../adr/102-unused-code-reachability-report.md).
 
+`rigor unused` refuses `--incremental` and exits non-zero rather
+than quietly running a full pass. Reachability is only sound over a
+whole-project run: with files served from the incremental cache a
+constant would be reported as unused merely because the file that
+references it was not re-scanned. Re-run without the flag.
+
 Reachability is computed from **roots**, not by counting references,
 so a cluster of classes that only reference each other is still
 reported. Roots are the declarations in files matching
@@ -1112,7 +1140,7 @@ operational knobs read the environment instead.
 | `RIGOR_RACTOR_WORKERS=N` | Worker count for parallel analysis. Sits between the CLI flag and the config key in precedence: `--workers=N` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > `0` (sequential). |
 | `RIGOR_POOL_BACKEND=ractor` | Opt back into the (off-by-default) Ractor worker pool instead of the active fork-based pool ([ADR-15](../adr/15-ractor-concurrency.md)). Only relevant with a non-zero worker count; the fork pool is the supported backend. |
 | `RIGOR_LSP_POOL_MIN_BATCH=N` | Fewest buffers an [`rigor lsp`](#rigor-lsp) batch must carry before analysis is dispatched across the worker pool rather than run in-process (default `16`). Lower it if your project's per-file analysis is expensive enough that pooling pays off sooner. |
-| `RIGOR_PLUGIN_ISOLATION=none\|process\|ruby_box` | How a plugin's direct calls into its target library are isolated. Default `process`. See [Using plugins § Isolation strategy](07-plugins.md). `RIGOR_BOX` is a legacy alias for `ruby_box`. |
+| `RIGOR_PLUGIN_ISOLATION=none\|process\|ruby_box` | How a plugin's direct calls into its target library are isolated. Overrides the `plugins_isolation:` configuration key. Default `process`. See [Using plugins § Isolation strategy](07-plugins.md). `RIGOR_BOX` is a legacy alias for `ruby_box`. |
 | `RIGOR_STRICT_VALIDATION=1` | Force full-content cache validation for one run (the same as `cache.validation: digest`, and winning over it) — re-hash every file's content instead of trusting its stat metadata. Use it if a filesystem's timestamps or inode numbers cannot be trusted. See [Caching § How a file is checked for changes](12-caching.md#how-a-file-is-checked-for-changes). |
 | `RIGOR_DISABLE_YJIT=1` | Opt out of Rigor's deferred YJIT enablement. Rigor turns YJIT on partway through any long run so short runs never pay the JIT warm-up; this variable leaves it off entirely. Diagnostics and allocations are identical either way — the effect is wall-time only. |
 | `RIGOR_YJIT_DEADLINE=<seconds>` | Advanced: tune how long a run must last before deferred YJIT enables (default `5.0`). Lower it if your runs are long and you want the JIT sooner; raise it to protect short runs. Ignored when `RIGOR_DISABLE_YJIT=1` is set or YJIT is unavailable. |
@@ -1126,8 +1154,8 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Success — no error-severity diagnostics. |
-| `1` | Diagnostics found, or a per-command failure (parse error, missing file, new diagnostics on `diff`, effect drift on `effects check`). |
+| `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. |
 
 `rigor triage` is the exception: it is advisory and always

data/docs/manual/03-configuration.md

@@ -93,6 +93,16 @@ rigor: severity_overrides: "flow.bogus" is not a recognized rule id; the overrid
 rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
 ```
 
+One warning covers the mirror-image mistake — a path that loads, but only
+half of what you wanted. A bundled plugin ships its RBS *and* a manifest
+recording which of those classes it declares only partially; `plugins:`
+loads both, while pointing `signature_paths:` at the plugin's `sig/` loads
+only the RBS, so calls your own code defines get reported as undefined:
+
+```
+rigor: signature_paths: "…/plugins/rigor-activerecord/sig" loads the signatures of the bundled plugin "rigor-activerecord", which `plugins:` does not name — … Add "rigor-activerecord" to `plugins:` instead of naming its `sig/` in `signature_paths:`.
+```
+
 The unrecognised-key check covers **top-level** keys, and skips
 the namespaces reserved for other implementations (see below).
 A typo *inside* a group — `cache: { pth: … }` — is caught by
@@ -170,6 +180,7 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 | `cache.max_bytes` | Integer or `null` | `268435456` (256 MB) | LRU eviction cap for the cache directory; `null` disables eviction. See [Caching § Size and eviction](12-caching.md#size-and-eviction). |
 | `cache.validation` | String | `"auto"` | How the cache checks whether a file is unchanged: `auto` behaves as `digest` when a CI environment is detected and as `stat` otherwise; `stat` compares size + nanosecond timestamps + inode and only re-hashes a file whose stat moved; `digest` re-hashes every file's content every run. Both keep the content hash as the sole change authority — `stat` just skips the hash when the stat proves a file untouched. See [Caching § How a file is checked for changes](12-caching.md#how-a-file-is-checked-for-changes). The `RIGOR_STRICT_VALIDATION=1` environment variable forces `digest` for one run and wins over this key; `RIGOR_CI_DETECT=0` disables the CI detection. |
 | `parallel.workers` | Integer | `0` | Parallel worker processes for per-file analysis (fork-based pool today; ADR-15); `0` is sequential. CLI `--workers` and `RIGOR_RACTOR_WORKERS` take precedence. Applies to `--incremental` re-checks as well as full runs. |
+| `plugins_isolation` | String | `null` | How a plugin's call into its target library is isolated — `process` (default) or `none`. `RIGOR_PLUGIN_ISOLATION` overrides it for one invocation; `ruby_box` is that variable only. See [Using plugins](07-plugins.md). |
 | `plugins_io.network` | String | `"disabled"` | Plugin network policy — `disabled` or `allowlist`. |
 | `plugins_io.allowed_paths` | Array | `[]` | Filesystem paths plugins may read. |
 | `plugins_io.allowed_url_hosts` | Array | `[]` | URL hosts plugins may fetch from when `network: allowlist`. |

data/docs/manual/04-diagnostics.md

@@ -85,6 +85,17 @@ carries no `documentation_url`.
 Plugins may contribute further families and rules; `rigor
 explain` lists whatever the active configuration loads.
 
+`flow.unreachable-branch` and `flow.always-truthy-condition` fold
+version guards — `RUBY_VERSION` / `RUBY_ENGINE` comparisons, and
+`X::VERSION` for a default gem of the running Ruby — against the
+Ruby interpreter running `rigor`, never `target_ruby`. The
+diagnostic set is therefore host-dependent: the same file can fold
+a different arm on Ruby 3.3 than on Ruby 4.0, and a project whose
+CI pins a different Ruby than your workstation should expect the CI
+run's result, not yours. See
+[Version-guard condition folding](../type-specification/control-flow-analysis.md#version-guard-condition-folding)
+for the exact foldable set.
+
 ## Evidence tier
 
 Every rule in the catalogue above carries an **evidence tier** —

data/docs/manual/07-plugins.md

@@ -74,23 +74,33 @@ A plugin may want to read a file (a schema dump) or reach the
 network. Those are gated by the `plugins_io:` config keys —
 the network is `disabled` by default, and a plugin can read
 only the paths you list. See
-[Configuration](03-configuration.md).
+[Configuration](03-configuration.md). If a plugin's read falls
+outside every configured path — a path spelled through a symlink
+alias where the read roots hold the real path (macOS' `/tmp` is
+one), or a genuinely out-of-tree file — Rigor surfaces a
+`plugin_trust.read-refused` `:info` diagnostic naming the plugin,
+the refused path and the nearest read root instead of failing
+silently. Spell the path the way the diagnostic's read root spells
+it, or add it under `plugins_io.allowed_paths:`.
 
 ### Isolation strategy
 
 A few plugins call into their target library directly (for
 example to ask ActiveSupport's real inflector how to pluralise a
 class name). That call runs under an **isolation strategy**, set
-with the `RIGOR_PLUGIN_ISOLATION` environment variable:
+with the `plugins_isolation:` configuration key or the
+`RIGOR_PLUGIN_ISOLATION` environment variable:
 
 | Value | Behaviour |
 | --- | --- |
 | `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. |
+| `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. **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 legacy `RIGOR_BOX` environment variable is a back-compat
-alias for `RIGOR_PLUGIN_ISOLATION=ruby_box`. The default
+The environment variable wins over `plugins_isolation:`, so you can
+override a project's committed choice for one invocation. The legacy
+`RIGOR_BOX` environment variable is a back-compat alias for
+`RIGOR_PLUGIN_ISOLATION=ruby_box`. The default
 (`process`) is the right choice for almost everyone; the variable
 exists for the rare platform where forking is unavailable or
 where you want stronger containment.

data/docs/manual/08-skills.md

@@ -8,9 +8,9 @@ agent works inside a project that has Rigor available.
 Skills are optional. Everything they do, you can do by hand with the
 commands in this manual; a skill drives the workflow end to end.
 
-## Start here — two skills to remember
+## Start here — three skills to remember
 
-You only ever need to remember two skills; the rest are reached through
+You only ever need to remember three skills; the rest are reached through
 them.
 
 - **`rigor-next-steps`** — *"what should we do next?"* The single entry
@@ -31,6 +31,20 @@ them.
   code, runs `rigor check` / `annotate` / `type-of` — then answers from
   the page or the inferred type. You never have to remember the command,
   just the question. Available at any point.
+- **`rigor-type-oracle`** — *"before you write a type, ask Rigor."* The
+  one to remember while **writing** rather than while planning. Any time
+  a type is about to be written or asserted — RBS under `sig/`, an inline
+  `#:` / `# @rbs` annotation, a Sorbet `sig`, a YARD `@param` /
+  `@return`, a type named in a doc sentence or a review comment, a nil
+  check justified by "this should be an `X`" — the type comes from
+  [`rigor type-of`](02-cli-reference.md#rigor-type-of) /
+  [`annotate`](02-cli-reference.md#rigor-annotate) /
+  [`sig-gen`](02-cli-reference.md#rigor-sig-gen), not from reading the
+  code. A type nobody obtained from Rigor is a guess, and where Rigor has
+  no answer (`Dynamic[top]`, `untyped`, a skipped method) the gap is
+  reported rather than filled in. It also ships the paragraph to keep in
+  your `AGENTS.md` / `CLAUDE.md`, so the rule holds in every agent
+  session and not only when the skill triggers.
 
 If you do not know which skill you need, start with `rigor-next-steps`.
 
@@ -72,6 +86,13 @@ 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-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
+  the *event* of a type being about to be written, so `rigor skill
+  describe` lists it but never routes to it — reach for it (or install
+  its `AGENTS.md` paragraph) whenever an agent documents or annotates
+  your code. Introduced above under "Start here".
 
 ### Integration and operations
 

data/docs/manual/11-ci.md

@@ -187,6 +187,15 @@ Rigor's severities map per format ([ADR-51](../adr/51-ci-diagnostic-output-forma
 The exit code is unchanged by `--format` — `0` when there are no errors,
 `1` otherwise — so the job still gates the pipeline. `--format json`
 remains available for any other tool that wants the raw diagnostic stream.
+A job that wants warnings (or `info` notes) to gate the pipeline too, not
+just errors, raises the bar with `rigor check --fail-on=warning` (or
+`--fail-on=info`) instead of parsing the diagnostic stream itself.
+
+A third status, `70`, means Rigor itself died mid-run — a
+`SystemStackError` or `NoMemoryError` inside the analysis — and the report
+it left behind (an empty `triage.json`, say) is not an account of your
+code. Treat it as a failed job and report it as a Rigor defect, never as a
+clean check.
 
 ## Gating effect drift
 

data/docs/manual/15-type-protection-coverage.md

@@ -337,6 +337,14 @@ ones a type actually catches.
 > point Rigor at it with `bundler.bundle_path:`. Until you do, these
 > holes keep the generic `engine_gap` cause instead of `add_rbs` —
 > the label is missing, never wrong.
+>
+> A project with **no `Gemfile.lock`** is not left out: Rigor falls
+> back to the gems it can see installed — the project's Bundler
+> install tree if one resolves, otherwise the running Ruby's gems —
+> and attributes constants against those. Ownership is still
+> established by reading the gem's own entry file, so the fallback
+> widens which gems can be claimed and never whether an unowned
+> constant is.
 
 Provenance is precision-additive only: it never changes a type, fires
 no diagnostic, and never affects severity or the protection ratio.

data/docs/manual/16-rbs-extended-annotations.md

@@ -122,7 +122,12 @@ The right-hand side of `return:`, `param:`, `assert*`, and
 
 Refinement payloads support the parameterised forms
 `non-empty-array[Integer]`, `non-empty-hash[Symbol, Integer]`,
-and the bounded-integer form `int<min, max>`. Type-argument
+and the bounded numeric forms `Integer[1..10]` and
+`Float[0.0...1.0]`, written with a Ruby range literal (`1...10`,
+`1..`, `..10`; the PHPStan-style `int<1, 10>` still parses but is
+deprecated and reports `dynamic.rbs-extended.deprecated-form` with
+the spelling to write), plus the Float names `non-nan-float` and
+`finite-float`. Type-argument
 positions also accept Symbol / String literal tokens and unions
 of them — `pick_of[T, :name | :email]`,
 `Pick[T, "name" | "email"]` — each lifted to a `Constant<value>`.

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

@@ -80,14 +80,16 @@ partition `declared` — they sum to 1497. **`reachable only from tests`
 is a subset of `reachable`**, not a fifth bucket, so do not add it in.
 
 Read `roots` first. A root is a declaration something outside your code
-reaches — an entry point, a route, a framework convention.
-Reachability is computed *from* roots, so a thin root set inflates
-everything below it. The pathological case is a Rails application with
-`0 from plugins`: nothing in Ruby source names a controller, so every
-controller you own appears dead. There is no published healthy ratio
-to compare against; what you are checking is whether the number is
-plausible for your framework, and `0 from plugins` on a framework app
-never is.
+reaches — an entry point, a route, a framework convention. The
+`(… from plugins, …)` parenthetical is omitted entirely when no plugin
+contributed a root, so a bare `roots: N` with no such note is itself
+the signal. Reachability is computed *from* roots, so a thin root set
+inflates everything below it. The pathological case is a Rails
+application with no `from plugins` note at all: nothing in Ruby source
+names a controller, so every controller you own appears dead. There is
+no published healthy ratio to compare against; what you are checking
+is whether the number is plausible for your framework, and a missing
+`from plugins` note on a framework app never is.
 
 ## Getting the number down
 

data/docs/manual/plugins/rigor-actionpack.md

@@ -93,6 +93,24 @@ so *can* fold a condition — and `Mime::NullType`, the value `format`
 returns when there is no format, answers `nil?` with `true` while
 being a real object. Typing it needs a nil-aware answer.
 
+## Framework constants resolve
+
+The plugin ships a small bundled signature naming the
+`ActionController` namespace and the errors controllers rescue —
+`ParameterMissing`, `UnpermittedParameters`, `RoutingError`,
+`BadRequest`, `UnknownFormat`, `InvalidAuthenticityToken` and their
+siblings. A `rescue ActionController::ParameterMissing => e` now types
+`e` as that class instead of leaving it opaque.
+
+The signature names **only** those. `ActionController::Base` and
+`ActionController::API` are left undeclared on purpose: every
+controller in the app inherits from one of them, and an incomplete
+declaration of a superclass turns every member it omits — `render`,
+`before_action`, `head` — into a report on working code. For the same
+reason `ActionController::Parameters` and the `ActionDispatch` readers
+above stay undeclared; their leniency is what makes the `params`
+typing safe.
+
 ## Limitations
 
 - **Implicit-self helpers only.** `*_path` / `*_url` calls with an

data/docs/manual/plugins/rigor-activerecord.md

@@ -76,6 +76,19 @@ Chained query methods keep the element type, and iteration
 scope invoked on a typed relation (`User.where(...).published`)
 never surfaces a false `call.undefined-method`.
 
+If the project also installs `activerecord` through
+`rbs collection install`, the collection declares
+`ActiveRecord::Relation` without a type parameter while the
+plugin declares `ActiveRecord::Relation[Elem]`, and RBS cannot
+hold both. The plugin's declaration stands down: relation call
+sites still type as `ActiveRecord::Relation[Model]`, but calls
+into a relation resolve against the collection's declaration,
+so the plugin's element typing (`.first` as `Model?`, for
+example) is unavailable, and the run reports one
+`rbs.coverage.plugin-signature-stood-down` info row naming both
+files. Nothing is broken; the plugin's typing returns only when
+the collection stops declaring the class.
+
 `User.table_name` types as `String`, and as the exact string
 only when your source says the name: a literal
 `self.table_name = "people"` on the class or on an STI ancestor,
@@ -118,6 +131,21 @@ than none, so `Blog::Post`'s column, alias and association checks
 stand down entirely rather than run against a table that might not
 be the real one.
 
+## Framework constants resolve
+
+The bundled signatures also name Active Record's exception hierarchy
+(`ActiveRecordError` and the classes apps rescue: `RecordNotFound`,
+`RecordInvalid`, `RecordNotSaved`, `StatementInvalid`,
+`RecordNotUnique`, `StaleObjectError`, …), the `ActiveModel`
+namespace, and `Arel`. `rescue ActiveRecord::RecordNotFound => e` types
+`e` instead of leaving it opaque.
+
+None of them declares a method surface — the declaration buys constant
+resolution and asserts nothing else, so `e.record` and every other
+member left out stays lenient rather than reported.
+`ActiveRecord::Base` is deliberately **not** declared: closing it would
+close every model in the project.
+
 ## Limitations
 
 - **Direct-superclass match only.** `class Admin < User` where

data/docs/manual/plugins/rigor-activesupport-core-ext.md

@@ -129,8 +129,29 @@ singletons `.days_in_month`, `.days_in_year`, `.rfc3339`, `.use_zone`,
 `.find_zone` / `.find_zone!` and `.zone_default`.
 
 Where a return cannot honestly be named it is widened rather than
-guessed: `#in_time_zone` answers an `ActiveSupport::TimeWithZone`, which
-this bundle does not model, so it reads `untyped`.
+guessed: `#in_time_zone` answers an `ActiveSupport::TimeWithZone` under a
+zone and the receiver's own class when none is configured, so it reads
+`untyped` rather than picking one of the two.
+
+`ActiveSupport::TimeWithZone` itself **is** modelled, as a subclass of
+`Time` — which is what `Time.current` and the whole `1.hour.ago` family
+answer:
+
+```ruby
+Time.current.time_zone       # the zone (untyped)
+Time.current.comparable_time # Time
+Time.current.to_fs(:db)      # String — Time's own surface, inherited
+1.hour.ago.time_zone         # the same class from the Duration family
+Time.now.time_zone           # still call.undefined-method — a plain
+                             # Time really does not have it
+```
+
+Rails overrides `TimeWithZone#is_a?` to answer true for `::Time` and
+forwards everything it does not define to the wrapped `Time`, so the
+subclass says what a `Time` return said and adds the four readers a TWZ
+has of its own. A `Time | TimeWithZone` union was measured instead and
+rejected: it fires nothing, but types the whole downstream chain
+`Dynamic[top]`.
 
 What is left out is twelve names, measured against a real
 `require "active_support/all"`: ten instance and two singleton, every one
@@ -145,6 +166,15 @@ code that does will see them reported.
 `Date` and `DateTime` are extended by the same ActiveSupport modules and
 do **not** carry this yet — `Date.current.past?` still reports.
 
+## `ActiveSupport::Concern` resolves
+
+`extend ActiveSupport::Concern` is the first line of every concern in a
+Rails app, and the constant used to resolve to nothing. The bundle now
+names the module, along with the three members `extend` puts on the
+extender — `included`, `prepended` and `class_methods` — so
+`included do … end` keeps resolving rather than becoming a report on the
+newly-named module. Everything else `Concern` responds to stays lenient.
+
 ## No diagnostics, no config
 
 The plugin emits no diagnostics and has no configuration knobs. It

data/docs/manual/plugins/rigor-rbs-inline.md

@@ -45,7 +45,48 @@ plugin id/version + config), so an unchanged second run skips the parse.
 | Rule | Severity | Fires when |
 | --- | --- | --- |
 | `plugin.rbs-inline.source-rbs-synthesis-failed` | info | rbs-inline could not parse a file; analysis falls back to no inline-RBS contribution and the diagnostic carries the upstream error |
-| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Today this means the `# @rbs module-self: Foo` spelling; see below |
+| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Two causes: a member your `sig/` also declares (see [Precedence](#precedence)), and the `# @rbs module-self: Foo` spelling (see below) |
+
+## Precedence
+
+When a method is declared **both** in `sig/` and by an inline
+annotation, **the `.rbs` wins, per member.** The inline signature for
+that one method is dropped; every other annotation in the file still
+binds, and the class keeps its method surface.
+
+```ruby
+# lib/demo.rb                  # sig/demo.rbs
+class Demo                     # class Demo
+  # @rbs (Integer) -> String   #   def shared: (String) -> Integer  ← this one wins
+  def shared(v) = v.to_s       #   def only_sig: () -> String
+                               # end
+  # @rbs (Integer) -> Integer
+  def only_inline(v) = v + 1   # ← inline-only: still binds
+end
+```
+
+Each dropped member is reported once as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured`, naming the
+member and the `.rbs` that won. Delete one of the two declarations to
+make the inline annotation take effect.
+
+`sig/` wins because it is the reviewed artefact — the one you diff in
+review and the one `rigor sig-gen --diff` reasons about. There is no
+upstream rule to defer to: rbs merges an inline `.rb` declaration and a
+`.rbs` one into a single class entry and ranks neither, so Steep reports
+the same overlap as a signature error and the class still fails to
+build. Rigor keeps the reporting and drops the degradation
+([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD13) — left to
+collide, one duplicated method costs the class every other method, and
+each call on it, real methods and typos alike, reads `Dynamic[top]`.
+
+Two overlaps this does **not** cover: a `.rbs` that collides with
+*bundled* RBS (Ruby core, stdlib, a gem's signatures) is quarantined
+file-by-file instead, reported as `rbs.coverage.quarantined-signature`;
+and two `.rbs` files declaring the same member still fail the class's
+definition build and surface as `rbs.coverage.definition-build-failed` —
+neither side of that pair is more reviewed than the other, so there is
+nothing to prefer.
 
 ## Which inline-RBS dialect Rigor reads
 

data/lib/rigor/analysis/baseline.rb

@@ -236,9 +236,9 @@ module Rigor
       # Walk the current diagnostic stream and report bucket-level drift. Each baseline bucket becomes one
       # DriftRow regardless of whether the current run still matches it.
       #
-      # @param diagnostics [Array<Diagnostic>] current run's diagnostic stream (PRE-filter — pass the raw
+      # @param diagnostics — current run's diagnostic stream (PRE-filter — pass the raw
       #   `result.diagnostics` from `Runner#run`, not the post-baseline surface).
-      # @return [Array<DriftRow>] one entry per baseline bucket, in baseline-file order.
+      # @return one entry per baseline bucket, in baseline-file order.
       def audit(diagnostics)
         counts = Hash.new(0)
         diagnostics.each do |diag|

data/lib/rigor/analysis/check_rules/always_truthy_condition_collector.rb

@@ -53,7 +53,7 @@ module Rigor
         NODE_CLASSES = [Prism::IfNode, Prism::UnlessNode].freeze
         RULE_WALK_GATES = [:loop_or_block].freeze
 
-        # @return [Array<Result>] one entry per qualifying predicate. Empty when the tree carries no firing
+        # @return one entry per qualifying predicate. Empty when the tree carries no firing
         #   predicates.
         def initialize(scope_index)
           @scope_index = scope_index

data/lib/rigor/analysis/check_rules/dead_version_guard_arms.rb

@@ -30,9 +30,6 @@ module Rigor
       module DeadVersionGuardArms
         module_function
 
-        # @param diagnostics [Array<Rigor::Analysis::Diagnostic>]
-        # @param root [Prism::Node]
-        # @return [Array<Rigor::Analysis::Diagnostic>]
         def filter(diagnostics, root)
           # The scan is a whole-file walk, so it is paid only when there is something to drop. A file with
           # no diagnostics — the overwhelming majority — never walks.
@@ -44,8 +41,7 @@ module Rigor
           diagnostics.reject { |diagnostic| arms.any? { |arm| covers?(arm, diagnostic) } }
         end
 
-        # @param root [Prism::Node]
-        # @return [Array<Prism::Location>] the source ranges of every dead version-guard arm
+        # @return the source ranges of every dead version-guard arm
         def scan(root)
           arms = []
           collect(root, arms)

data/lib/rigor/analysis/check_rules/ivar_write_collector.rb

@@ -2,6 +2,7 @@
 
 require "prism"
 
+require_relative "rule_walk"
 require_relative "../../source/constant_path"
 require_relative "../../source/node_children"
 
@@ -17,7 +18,11 @@ module Rigor
       #
       # Skipped on purpose:
       #
-      # - Singleton-method bodies (`def self.foo`). Their ivars live on the class object, not on instances.
+      # - Singleton-method bodies, in either spelling: `def self.foo`, and (issue #909) any `def` lexically
+      #   inside a `class << self` body. Their ivars live on the class object, not on instances.
+      # - Bodies of an anonymous-class factory block (`Class.new do … end`, `Module.new`, `Struct.new`,
+      #   `Data.define`). The class they define is not the enclosing one, so its ivars are a third store
+      #   again (issue #909).
       # - Class-body ivar writes outside any def — the `Module#@var` surface is a separate slice the engine
       #   doesn't yet model.
       # - Nested classes / modules / defs inside a method body are barriers, mirroring the indexer's
@@ -33,7 +38,7 @@ module Rigor
         # shared full DFS that prune becomes the `:inside_def` gate; the enclosing class / module name stack
         # the legacy walk threaded as `qualified_prefix` is now `context.qualified_prefix`.
         NODE_CLASSES = [Prism::DefNode].freeze
-        RULE_WALK_GATES = [:inside_def].freeze
+        RULE_WALK_GATES = %i[inside_def detached_ivar_facet].freeze
 
         # Returns `Hash[class_name (String) => Hash[ivar_name (Symbol) => Array<{node:, type:}>]]`. Empty
         # when the tree has no qualifying writes.
@@ -66,6 +71,9 @@ module Rigor
 
         def walk(node, qualified_prefix)
           return unless node.is_a?(Prism::Node)
+          # The legacy walk's mirror of {RuleWalk}'s `detached_ivar_facet` context (issue #909); the two
+          # walks share the predicate so the permanent equivalence spec keeps holding.
+          return if RuleWalk.detached_ivar_facet?(node)
 
           case node
           when Prism::ClassNode, Prism::ModuleNode

data/lib/rigor/analysis/check_rules/main_pass_collector.rb

@@ -25,7 +25,7 @@ module Rigor
           Prism::CallNode, Prism::DefNode, Prism::IfNode, Prism::UnlessNode
         ].freeze
 
-        # @param node_diagnostics [#call] maps a `Prism::Node` to the array of diagnostics the main pass emits
+        # @param node_diagnostics — maps a `Prism::Node` to the array of diagnostics the main pass emits
         #   for it.
         def initialize(node_diagnostics)
           @node_diagnostics = node_diagnostics