rigortype 0.3.8 → 0.4.0

data/docs/handbook/appendix-java-csharp.md

@@ -292,7 +292,7 @@ class refinement carriers, produced automatically by narrowing.
 | --- | --- | --- |
 | `non-empty-string` | a `NonEmptyString` value class wrapping validation | Rigor produces it from `unless s.empty?`, no wrapper type. |
 | `positive-int` | a `PositiveInt` value object, or a runtime guard | Rigor narrows from `n > 0`. |
-| `int<1, 9>` | an `enum` of nine constants, or a range check | Rigor's range carrier handles arbitrary bounds without enumerating them. |
+| `Integer[1..9]` | an `enum` of nine constants, or a range check | Rigor's range carrier handles arbitrary bounds without enumerating them. |
 | `numeric-string` | `string` + `int.TryParse` discipline | No type-level analogue in either language. |
 | `non-empty-array[T]` | a non-empty-collection value class | Rigor produces it from `unless arr.empty?`. |
 
@@ -379,7 +379,7 @@ longer than you might expect, because neither has literal types:
   `Constant<"FOO">`, not `String`. Rigor catalogues which
   built-in methods are pure and folds through them.
 - **First-class refinements.** `non-empty-string`, `positive-int`,
-  `int<1, 9>`, `numeric-string` — invariants on ordinary types,
+  `Integer[1..9]`, `numeric-string` — invariants on ordinary types,
   no value-class wrapper.
 - **Structural facets without a declaration.** A Ruby object that
   has the right methods satisfies an RBS `interface` (a

data/docs/handbook/appendix-mypy.md

@@ -71,7 +71,7 @@ features one at a time (`Literal`, `LiteralString`, `TypeIs`,
 | `non-empty-string` | (no built-in; PEP 675's `LiteralString` is closest in spirit but different in semantics) |
 | `literal-string` | `LiteralString` (PEP 675) — provably built from source-code literals. **Direct match.** |
 | `positive-int` | (no built-in; convention is `Annotated[int, Gt(0)]` with third-party validators) |
-| `int<min, max>` | (no built-in; same `Annotated[int, Range(...)]` convention) |
+| `Integer[min..max]` | (no built-in; same `Annotated[int, Range(...)]` convention) |
 | `numeric-string` | (no built-in) |
 | `non-empty-array[T]` | (no built-in; some libraries use `tuple[T, *tuple[T, ...]]`) |
 | `Constant<42>` | `Literal[42]` |
@@ -286,7 +286,7 @@ draws the distinction in full.
   `Hash`.
 - **First-class refinement carriers with narrowing.**
   `non-empty-string`, `positive-int`, `numeric-string`,
-  `int<min, max>` — values restricted by predicate, narrowed
+  `Integer[min..max]` — values restricted by predicate, narrowed
   by the corresponding Ruby predicate methods.
 - **No-false-positives stance.** mypy will warn about dynamic
   code unless `--no-warn-unused-ignores` or `--ignore-missing-imports`

data/docs/handbook/appendix-phpstan.md

@@ -53,7 +53,7 @@ is the closest match of any peer.
 | `numeric-string` | `numeric-string` | Identical. |
 | `lowercase-string` | `lowercase-string` | Identical. |
 | `class-string` | `Singleton[T]` | Equivalent shape. |
-| `int<1, 9>` | `int<1, 9>` | **Identical syntax.** |
+| `int<1, 9>` | `Integer[1..9]` | Same carrier; Rigor spells the bound as the Ruby range literal `Range#cover?` reads (`Integer[1..]`, `Integer[..9]`). |
 | `positive-int` | `positive-int` | Identical. |
 | `negative-int` | `negative-int` | Identical. |
 | `non-zero-int` | `non-zero-int` | Identical. |

data/docs/handbook/appendix-rust.md

@@ -274,7 +274,7 @@ by narrowing.
 | --- | --- | --- |
 | `non-empty-string` | `struct NonEmptyString(String)` newtype | Rigor produces it from `unless s.empty?`, no wrapper. |
 | `positive-int` | `struct PositiveInt(u32)` newtype | Rigor narrows from `n > 0`. |
-| `int<1, 9>` | newtype + range check, or const generics gymnastics | Rigor's range carrier handles arbitrary bounds directly. |
+| `Integer[1..9]` | newtype + range check, or const generics gymnastics | Rigor's range carrier handles arbitrary bounds directly. |
 | `numeric-string` | newtype wrapping validated parse | No type-level analogue. |
 | `non-empty-array[T]` | newtype over `Vec<T>` | Rigor produces it from `unless arr.empty?`. |
 

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,39 @@ 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 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
+`self`, locals and instance variables, and `LINE:COL` are the
+template's own. A column answers only when it lies in Ruby the
+compiler copied verbatim — the `@user.name` in
+`<%= @user.name %>` — and denotes exactly one compiled
+expression. A column in HTML text, in code the plugin rewrote
+(a layout's `<%= yield %>`), or in bytes copied to more than
+one place prints `no expression found at …` with the reason
+and exits `1`; the command never answers about a nearby
+node instead. Two tags that name the same thing (`<%= v %>`
+beside `<% if "a" <= v %>`, or `<%= v %> <%= v.to_s %>`)
+decline for that reason as well; a name repeated inside ONE
+tag still answers. A bare `FILE:LINE` lists only the expressions
+that map back to a template column. `--trace` fallbacks are
+reported at the template line, and a JSON fallback carries a
+`column` only when its position maps back to one. A template
+the plugin declined to compile prints
+`plugin declined the template; probing its bytes as Ruby`
+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
+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 +465,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
@@ -457,13 +499,52 @@ rigor sig-gen [paths]
 | `--print` | Write RBS to stdout. Default. |
 | `--diff` | Write a unified diff against existing RBS. |
 | `--write` | Write RBS to `sig/<path>.rbs` files. |
-| `--overwrite` | Allow tighter-return updates to replace user-authored RBS. |
+| `--check` | Write nothing; print what `--write` with the same options would change, and exit `1` if anything would. The CI freshness gate. |
+| `--overwrite` | Allow tighter-return updates, and inline declarations that disagree with `sig/`, to replace user-authored RBS. |
 | `--include-private` | Emit private and protected methods too. |
 | `--params=untyped\|observed\|observed-strict` | Parameter-typing policy. Default `untyped`. |
-| `--observe=PATH` | Scan `PATH` for call-site observations. Repeatable. |
+| `--observe=PATH` | Scan `PATH` for call-site observations. Repeatable. Default: the configured `test_paths:` (unset: whichever of `spec/` and `test/` exist). |
 | `--new-files` / `--new-methods` / `--tighter-returns` | Emit only that classification. |
+| `--effect-envelopes` | Also emit `%a{rigor:v1:effect …}` for effectful methods. Needs the `effects:` opt-in. |
+| `--no-cache` | Do not read or write the analysis cache. Only effect collection uses it. |
 | `--format=text\|json` | Output format. |
 
+`--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).
+
+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,
+and `initialize` is always `-> void`. When `sig/` already declares
+the method (a `def` or an `attr_*`) and the two disagree as types —
+parameter names and union spelling do not count, overload order
+does — sig-gen changes neither: the method is refused
+(`sig.skipped.inline-differs`, listed under `refused` in `--format=json`),
+and `--write` / `--check` exit `1` until you make them agree or pass
+`--overwrite`, which replaces the whole `sig/` member with the inline
+declaration. For a parameter-only annotation only the parameters are
+compared; the return follows the ordinary proposal rules. A class
+made generic inline is not written unless `sig/` declares it with the
+same type parameters. A project whose Steep reads the same
+annotations sets `sig_gen.inline_declared: skip` in `.rigor.yml` to
+keep those methods out of `sig/`. See
+[handbook chapter 11](../handbook/11-sig-gen.md#methods-declared-inline).
+
+When `.rigor.yml` carries an `effects:` block, sig-gen also writes
+`%a{pure}` above a method whose effect summary is **exhaustive**
+(every call it reaches was resolved), **undischarged** (nothing in
+its footprint is only invisible because `effects.tolerated:` says
+so), **claimed** (every callee is described by a catalogue row, a
+plugin, an envelope or a project definition), carries no authored
+bound of its own, and is free of surviving labels in the `≤` lane. Nothing else is annotated, and
+`--effect-envelopes` adds Rigor's own labelled spelling for methods
+that do have a footprint. With no `effects:` block the output is
+byte-for-byte what it was before. See
+[handbook chapter 11](../handbook/11-sig-gen.md#emitting-effect-annotations).
+
 Every signature is parsed before it is emitted. A method whose
 generated RBS does not parse is **skipped** (`sig.skipped.unrenderable-rbs`)
 and reported on stderr rather than written — an unparseable
@@ -481,6 +562,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 +660,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 +1201,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 +1215,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

@@ -60,6 +60,7 @@ cache:
 | `target_ruby` | String | `"4.0"` | The Ruby version *your* project runs — `"X.Y"`, `"X.Y.Z"`, or `"latest"`. Independent of the Ruby Rigor itself runs on. |
 | `paths` | Array | `["lib"]` | Directories or files to analyse. |
 | `exclude` | Array | `[]` | Glob patterns to skip. `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. |
 | `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`. |
@@ -73,6 +74,12 @@ cache:
 | `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
+### Signature generation
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sig_gen.inline_declared` | String | `"write"` | What `rigor sig-gen` does with a method already declared inline by `# @rbs` / `#:`. `write` copies the inline declaration into `sig/`, so the generated signature is the complete contract a gem ships, and refuses (exit 1) a `sig/` declaration that later disagrees with the inline one until the two agree or `--overwrite` replaces it. `skip` leaves every method the inline reader declares out of `sig/` (`sig.skipped.inline-declared`): set it when Steep reads the same annotations (`inline: true` beside `signature "sig"`), where a copy would declare each method twice (`DuplicatedMethodDefinition`). The cost of `skip`: a consumer reading only your shipped `sig/` never sees those methods, and an annotation on one — a Rigor refinement included — takes effect only where the source itself is analysed. Any other value, or any other key under `sig_gen:`, is a load error. Only `rigor sig-gen` reads this key, and changing it invalidates no cache. See [handbook chapter 11](../handbook/11-sig-gen.md#methods-declared-inline). |
+
 ### Config validation warnings
 
 `rigor check` warns on STDERR when a configured value silently resolves to
@@ -93,6 +100,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 +187,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

@@ -16,6 +16,7 @@ Every rule has a two-segment `family.rule` identifier:
 | `call` | Call sites — undefined methods, arity, argument types, nil receivers. |
 | `flow` | Control-flow proofs — always-raises, dead branches, constant conditions. |
 | `def` | Method definitions — return types, ivar writes, visibility. |
+| `global` | Writes to special globals — a value the setter rejects, a read-only variable. |
 | `assert` | `assert_type` checks. |
 | `dump` | `dump_type` notices. |
 
@@ -70,11 +71,14 @@ carries no `documentation_url`.
 | <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 |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
+| <a id="rule-global-write-type-mismatch"></a>`global.write-type-mismatch` | A special global is assigned a literal its setter rejects, so the write raises `TypeError` every time it runs. `$/`, `$-0`, `$,` and `$\` take only a String or nil (`$/ = 1` and `$/ = /x/` report). `$;` and `$-F` take a String, a Regexp, nil, or an object with `to_str`. `$~` takes a MatchData or nil. `$0` and `$PROGRAM_NAME` take a String or an object with `to_str`, so `$0 = nil` and `$0 = :name` report. `$.` takes an Integer, a Float, or an object with `to_int`, so `$. = "3"` reports and `$. = 3r` does not. `$-i` takes a String, nil, false, or an object with `to_str`. `$stdout`, `$>` and `$stderr` take anything that responds to `write`: `$stdout = 1` reports, `$stdout = StringIO.new` does not. Ruby's setter decides, not the global's RBS type. Only a value written as a literal is judged — a number, a string, a symbol, an array, a hash or a regexp literal (interpolated or not), or `nil`, `true` or `false` — so a variable, a method call or a constant never reports, whatever its type. A literal stays silent when your program defines the method the setter asks for (`write`, `to_str`, `to_int`) or a `method_missing` / `respond_to_missing?` / `respond_to?` anywhere, in any spelling and on any class — Rigor cannot always tell which objects such a definition reaches, so it does not try — or when a top-level `include` / `extend` or an ancestor's `include` names a module Rigor has no RBS for. For `$stdout`, `$>` and `$stderr` it also stays silent where a `using` is in effect for a refinement that may add `write`. `$/`, `$-0`, `$,`, `$\` and `$~` accept only their classes, so none of that silences them. A write to `$stdin` is never checked, and a special any file aliases (`alias $stdout $out`, including a `pre_eval:` file) is exempt. `warning` under `lenient`. | high |
+| <a id="rule-global-readonly-write"></a>`global.readonly-write` | A read-only special global is written — `$!`, `$$`, `$?`, `$<`, `$FILENAME`, `$*`, `$:` / `$LOAD_PATH` / `$-I`, `$"` / `$LOADED_FEATURES`, `$-W`, `$-p`, `$-l` or `$-a` — which raises `NameError` whatever the value. Covers `$g = value`, `$g += value` and a multiple-assignment target. `$LOAD_PATH ||= []` never writes and `$LOAD_PATH << dir` is a method call, so neither fires. A special any file aliases (`alias $! $err`) is exempt. An error in every profile. | high |
 | <a id="rule-static-value-use-void"></a>`static.value-use.void` | A value recovered from an author-declared `-> void` return is used in value context (an assignment right-hand side, a call receiver, or a call argument). Off by default; reaches a run only through the `use-of-void-value` bleeding-edge feature (ADR-100). A bare-statement `void` call and a legitimate `top` value both stay silent. | high |
 | <a id="rule-effect-envelope-exceeded"></a>`effect.envelope-exceeded` | A method performs an effect its declared envelope does not admit — its proven effect labels (its own body plus everything it calls) are not covered by the `%a{pure}` or `%a{rigor:v1:effect …}` bound written on it or on its class. Opt-in twice over: it needs an `effects:` block in `.rigor.yml` and an envelope you wrote. Positioned at the Ruby `def`. Unproven ("and possibly more") effects never fire, and `mutate.local` is tolerated by every envelope. | high |
 | <a id="rule-effect-liskov-widened"></a>`effect.liskov-widened` | An override escapes the envelope written on the method it overrides. A `PgRepo` is usable wherever a `Repo` is, so a `%a{rigor:v1:effect io.db}` on `Repo#find` binds `PgRepo#find` too: an implementation may be purer than the bound it inherits, never less pure. Either what the override *does* exceeds the inherited bound, or the envelope the override *declares for itself* is wider than it. Both sides must be authored — nothing fires unless someone wrote an envelope on the ancestor — and only subclassing counts, not `include`. Positioned at the override's `def`. Needs an `effects:` block. | high |
 | <a id="rule-effect-unknown-label"></a>`effect.unknown-label` | An effect declaration names a label the registry does not know — a typo in an envelope (`%a{rigor:v1:effect io.bd}`), or a member of `effects.tolerated:`. The whole tag then reads as unbounded, so the declaration quietly stops doing anything; this says so. Positioned at the declaration: the `.rbs` line, the `.rb` line for an rbs-inline annotation, or `.rigor.yml` for a config value. `# rigor:disable` comments are not read out of `.rbs` or `.rigor.yml`, so use `disable:` or the baseline there. Only fires where the spelling is evidently meant to be a label (close to a known one, next to a known one, dotted, or retired) — a word nothing resembles stays silent, because you may be opening your own vocabulary. Needs an `effects:` block. | high |
 | <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — on every run, a warm `--incremental` with nothing changed included. | — |
+| <a id="rule-rbs-contradicting-signature"></a>`rbs.contradicting-signature` | A method is declared both in your `sig/` and by an inline `# @rbs` / `#:` annotation, and the two provably contradict — no value or call satisfies both: in the return or a parameter every call must pass, the two types share no value (`::String` against `::Integer`). Only absolutely written Ruby core or stdlib classes count: a module such as `Comparable`, a class your project declares, a gem's class, or a relative name like plain `String` never does, or two keyword-free declarations accept positional counts that cannot meet, or one requires a keyword the other cannot take in any form. Overloads are paired by correspondence, not order. Also fires when a member-level `%a{rigor:v1:return: …}` / `%a{rigor:v1:param: …}` refinement shares no value with the type its own member declares. Positioned at the `.rbs` member; Rigor reads that declaration. A stale generated signature is the usual cause: regenerate it, or fix the annotation. Two declarations where one refines the other merge to the more precise one without a word, and a pair Rigor cannot rank drops the inline side with a `source-rbs-annotation-not-honoured` `:info` instead ([Precedence](plugins/rigor-rbs-inline.md#precedence)). An error in every profile. | high |
 | <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
 | <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
 | <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |
@@ -85,6 +89,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. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
 
-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/10-mcp-server.md

@@ -358,8 +358,9 @@ Generate RBS skeleton signatures inferred from Ruby source files.
 | `params` | `"untyped"` \| `"observed"` | no | `"untyped"` |
 | `config` | `string` | no | session default |
 
-`params: "observed"` harvests call-site argument types from `spec/`
-(or a directory named via `--observe=PATH` in the underlying CLI).
+`params: "observed"` harvests call-site argument types from the
+project's test roots: the configured `test_paths:`, or whichever of
+`spec/` and `test/` exist.
 
 **Returns:** JSON — the same as `rigor sig-gen --print --format json`.
 

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

@@ -22,25 +22,56 @@ The plain `() -> String` stays the compatibility contract; the
 annotation tells Rigor the return is a non-empty string.
 
 You may also write any of them **in a `.rb` file**, as an
-rbs-inline `# @rbs %a{…}` comment — `%a{}` is rbs-inline's own
-upstream grammar, and the annotation reaches Rigor on the same
-path the generated signature does:
+inline-RBS comment — `%a{}` is RBS's own annotation grammar, and
+the annotation reaches Rigor on the same path the generated
+signature does. Rigor reads three spellings:
 
 ```rb
 # rbs_inline: enabled
 
 class Reader
+  # Own line: the annotation, then the type on its own tag.
   # @rbs %a{rigor:v1:return: non-empty-string}
   # @rbs return: String
   def read_name = "x"
+
+  # Same line, `@rbs` method type.
+  # @rbs %a{rigor:v1:return: non-empty-string} () -> String
+  def title = "x"
+
+  # Same line, `#:` method type.
+  #: %a{rigor:v1:return: non-empty-string} () -> String
+  def label = "x"
 end
 ```
 
+Several annotations may stand before the method type
+(`#: %a{pure} %a{rigor:v1:return: non-empty-string} () -> String`).
+The other inline-RBS readers do not accept all three:
+
+| spelling | rbs's built-in inline parser, Steep with `inline: true` | the `rbs-inline` gem's own `--output` |
+| --- | --- | --- |
+| own line | syntax error (`expected a token pARROW`), annotation lost | annotation kept |
+| same line | annotation and method type kept | annotation kept, method type **dropped** |
+
+Rigor keeps both halves of every row. If you also run Steep in
+inline mode, use the same-line spelling. The measurement is in
+[ADR-111](../adr/111-inline-refinement-carrier.md). If the method type after a same-line annotation
+does not parse, the method is left untyped and Rigor reports it as
+[`plugin.rbs-inline.source-rbs-annotation-not-honoured`](plugins/rigor-rbs-inline.md#same-line-annotations).
+
 This needs the `rbs-inline` library installed; Rigor ingests
 inline annotations by default when it is
-([ADR-93](../adr/93-default-rbs-inline-ingestion.md)). There is
-no Rigor-only comment dialect: `# rigor:` comments remain
-suppression-only.
+([ADR-93](../adr/93-default-rbs-inline-ingestion.md)). `# rigor:`
+comments remain suppression-only.
+
+A dedicated `# @extrbs` comment for what RBS cannot spell is
+accepted in [ADR-112](../adr/112-extrbs-comment-channel.md) but
+not implemented yet ([#1073](https://github.com/rigortype/rigor/issues/1073)).
+Until it ships, the `%a{}` forms above are the inline route. A type
+plain RBS can spell, such as `:asc | :desc`, belongs in `# @rbs` or
+`#:` either way.
+
 This page is the *operational* reference — the directives you can
 write and their syntax. For the normative rules (conflict
 handling, merging, provenance) see
@@ -122,7 +153,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>`.
@@ -178,7 +214,9 @@ class UserRepository
 end
 ```
 
-The same two work as rbs-inline comments in a `.rb` file:
+The same two work as rbs-inline comments in a `.rb` file, in any of
+the three spellings shown above — the own-line
+one here:
 
 ```rb
 # rbs_inline: enabled