rigortype 0.3.9 → 0.4.1

data/docs/install.md

@@ -10,19 +10,42 @@ skill (`rigor-project-init` for a project that has never run Rigor).
 **Do not add Rigor to the project's `Gemfile`** — Rigor is a
 standalone tool, not a library.
 
+**Install the latest release, not whatever is already on the
+machine.** A `rigor` already on PATH, or a version manager that
+resolves to an older release, is not a reason to stop early: Rigor
+changes quickly, and the skills this guide hands off to are written
+for the current release. Step 1 looks up the latest version; Step 2
+installs it and Step 3 checks it.
+
 ---
 
 ## Step 1 — Detect the environment
 
-Run these four checks and note which tools are available:
+Run these checks and note which tools are available:
 
 ```sh
 which mise    # preferred — see Step 2A
 which asdf    # fallback — see Step 2B
 ruby --version 2>/dev/null | head -1   # is Ruby 4.0 already on PATH?
-which docker  # last resort — see Step 2D
+which docker  # last resort — see "Last resort — Docker"
+rigor --version 2>/dev/null            # an existing install, if any
+```
+
+Then look up the latest Rigor release on RubyGems:
+
+```sh
+curl -fsS https://rubygems.org/api/v1/versions/rigortype/latest.json
 ```
 
+It prints `{"version":"X.Y.Z"}`. Below, `<LATEST>` stands for that
+`X.Y.Z`: replace it with the version you got, never type `<LATEST>`
+literally. Without `curl`, `gem search --remote --exact rigortype`
+gives the same answer once Ruby is available. If neither works, tell
+the user you could not determine the latest version instead of
+guessing one.
+
+An existing `rigor` older than `<LATEST>` still goes through Step 2;
+tell the user which version they have and which you are installing.
 Then proceed to the **first** matching case below.
 
 ---
@@ -40,23 +63,51 @@ that can be committed alongside the code. Other contributors — and CI
 — run `mise install` to restore those versions with no `Gemfile`
 involvement.
 
-Run in the project root:
+First ask mise which Rigor version it would pick:
+
+```sh
+mise latest gem:rigortype
+```
+
+If that is older than `<LATEST>`, mise is holding the newer release
+back — usually its `minimum_release_age` quarantine, which hides
+releases for a while after they are published (`mise ls-remote
+gem:rigortype` then warns `1 newer gem:rigortype release hidden by
+minimum_release_age` on stderr). A bare `mise use gem:rigortype`
+would install the older version with no error, so this is the step where agents
+silently end up on a stale Rigor. The quarantine is a supply-chain
+safeguard, so do not bypass it on your own: tell the user both
+versions and ask which to install. `mise settings get
+minimum_release_age` tells you whose choice it is: an error ("not
+set") means mise's built-in default is in effect and you can recommend
+`<LATEST>`; a value means the user configured it, so recommend
+respecting it.
+
+Then run in the project root, with the version the user agreed to:
 
 ```sh
 mise use ruby@4.0
-mise use --pin gem:rigortype
+mise use --pin gem:rigortype@<LATEST>
 ```
 
 `mise use` installs the tools and writes their versions to `mise.toml`
-in one step. Commit `mise.toml` so the version is shared.
+in one step. Commit `mise.toml` so the version is shared. Name the
+version explicitly, as above: an explicit version is installed even
+while the quarantine hides it from `mise latest`.
 
-`--pin` records the exact Rigor version (`"gem:rigortype" = "0.2.9"`).
+`--pin` records the exact Rigor version (`"gem:rigortype" = "X.Y.Z"`).
 Without it mise writes `"gem:rigortype" = "latest"`, which every
 machine re-resolves to whatever is newest when it first installs — so
 a committed `latest` does not give the team one shared version. The
 trade-off: a pin will not move on its own, and `mise outdated` cannot
-report a pinned tool as behind. Upgrade with `mise upgrade --bump
-gem:rigortype`.
+report a pinned tool as behind. Upgrade by running `mise use --pin
+gem:rigortype@<version>` again with the newer version; `mise upgrade
+--bump gem:rigortype` goes through the same quarantine as a bare
+`mise use`.
+
+A user-wide `~/.config/mise/config.toml` entry for `gem:rigortype`
+keeps applying outside this project. Mention it if it names an older
+version, but do not edit global config without the user's consent.
 
 Then verify:
 
@@ -88,7 +139,8 @@ gem is installed with `gem install` after setting the Ruby version.
 ```sh
 asdf install ruby latest:4.0
 asdf local ruby latest:4.0
-gem install rigortype
+gem install rigortype -v <LATEST>
+asdf reshim ruby
 ```
 
 Verify:
@@ -108,7 +160,7 @@ pinning; see <https://mise.jdx.dev/getting-started.html>.
 If `ruby --version` reports `ruby 4.0.*`, install the gem directly:
 
 ```sh
-gem install rigortype
+gem install rigortype -v <LATEST>
 ```
 
 Verify:
@@ -152,6 +204,11 @@ and does not integrate well with editor LSP. Use it only when a
 host-side Ruby 4.0 is genuinely unavailable (for example, Windows
 without WSL). For all other environments, prefer Case A–D above.
 
+With Docker there is no `rigor` on the host PATH, so Step 3 checks the
+image instead: `docker run --rm ghcr.io/rigortype/rigor:latest rigor
+--version`. The image can trail RubyGems by a release; report its
+version to the user rather than treating a mismatch as a failure.
+
 ---
 
 ## Step 3 — Verify the installation
@@ -160,8 +217,23 @@ without WSL). For all other environments, prefer Case A–D above.
 rigor --version
 ```
 
-A version string like `rigor 0.2.x` confirms a successful install.
-If the command is not found, revisit Step 2 for your case.
+The reported version should be the one you installed in Step 2
+(normally `<LATEST>`). If it is older, you are running a different
+`rigor` than the one just installed. With mise, first check what the
+project resolves to:
+
+```sh
+mise exec -- rigor --version
+mise which rigor
+```
+
+If `mise exec` reports the new version, the shell's PATH is stale (a
+non-interactive shell does not re-run mise's activation after `mise
+use`); run `eval "$(mise hook-env)"`, or use `mise exec -- rigor` for
+the remaining steps. Otherwise run `which -a rigor` to find the older
+install. Do not uninstall anything to fix this without asking, and do
+not continue on the older version without telling the user. If the
+command is not found, revisit Step 2 for your case.
 
 ---
 
@@ -192,6 +264,6 @@ project is set up, re-run `rigor skill describe` for the step after
 that.
 
 If `rigor skill describe` is not recognised, your Rigor version predates
-it. Run `rigor --version` and upgrade with `mise upgrade --bump
-gem:rigortype` (or `gem update rigortype` for Case B/C); on an older
-version, run `rigor skill rigor-project-init` directly.
+it: you are not on the version Step 1 found. Go back to Step 3. If
+you are staying on an older version with the user's agreement, run
+`rigor skill rigor-project-init` directly.

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

@@ -34,8 +34,8 @@ the `paths:` list from the configuration file.
 | `--format=FORMAT` | Output format. Default `text`. Also `json` (structured stream), plus the CI-native renderings `sarif`, `github`, `gitlab`, `checkstyle`, `junit`, and `teamcity` — see [Running Rigor in CI](11-ci.md). |
 | `--no-ci-detect` | Disable CI auto-detection — by default `text` output also emits the running CI's native annotations / hint (`RIGOR_CI_DETECT=0` does the same). See [Running Rigor in CI § auto-detection](11-ci.md). |
 | `--explain` | Surface fail-soft fallback events as `info` diagnostics. |
-| `--no-cache` | Skip the persistent cache for this run. |
-| `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. See [Caching](12-caching.md). |
+| `--no-cache` | Skip the persistent cache for this run. With `--incremental` it is a cold full analysis: the incremental snapshot and the run-result cache are neither read nor written, so the next plain `--incremental` run still uses the snapshot it had before. |
+| `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. A run with nothing changed is answered from the cache without starting the analyzer. See [Caching](12-caching.md). |
 | `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics are byte-identical, then exit (0 on match, 1 with the differing diagnostics on mismatch). Used in CI to guarantee `--incremental` never serves a stale result. |
 | `--clear-cache` | Delete the cache directory before running. |
 | `--cache-stats` | Print the on-disk cache inventory when finished — on stdout under `--format text`, on stderr under every other format, so machine-readable output stays a parseable document. `--clear-cache`'s and `--verify-incremental`'s notes follow the same rule. |
@@ -138,6 +138,28 @@ 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
@@ -477,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

data/docs/manual/03-configuration.md

@@ -21,6 +21,11 @@ discovery entirely.
 
 All relative paths in a config file resolve against that
 file's own directory.
+A leading `~/` (or a bare `~`) in a path setting expands to your home directory; `~name` is an ordinary
+directory called `~name`, not another user's home. This covers `paths:`, `signature_paths:`, `test_paths:`,
+`pre_eval:`, `plugins_io.allowed_paths:`, `includes:`, `bundler.bundle_path:`, `bundler.lockfile:` and
+`rbs_collection.lockfile:`. It does not apply to `cache.path:`, `baseline:` or `effects.snapshot.path:`, which stay
+literal and relative to the working directory.
 
 ## Editor validation
 
@@ -60,6 +65,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 +79,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

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 |

data/docs/manual/07-plugins.md

@@ -95,7 +95,7 @@ with the `plugins_isolation:` configuration key or the
 | --- | --- |
 | `process` (default) | Run the call in a forked, crash-contained worker, so the target library's monkey-patches and any crash never contaminate Rigor. Falls back to `none` where `fork` is unavailable (Windows / JRuby). |
 | `none` | Load the library into Rigor's own process and call it directly. |
-| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
+| `ruby_box` | Run inside an experimental `Ruby::Box` sandbox. This needs the `RUBY_BOX=1` start flag, so the `rigor` launcher re-execs itself with it set when you select this strategy. It also needs a Ruby that fixes [Ruby Bug #22260](https://bugs.ruby-lang.org/issues/22260), which no release up to 4.0.7 does. The launcher checks for the fix first, and without it prints a warning and uses the configured strategy instead. **Environment variable only** — the configuration file is read long after Ruby has booted, so `plugins_isolation: ruby_box` is reported as a configuration error instead. |
 
 The environment variable wins over `plugins_isolation:`, so you can
 override a project's committed choice for one invocation. The legacy

data/docs/manual/08-skills.md

@@ -60,9 +60,10 @@ is not repeated here.)
 - **`rigor-project-init`** — onboards a project from a cold start. It
   detects the stack (Rails, RSpec, dry-rb, …), proposes the matching
   [plugins](07-plugins.md), picks an adoption mode — a
-  [baseline](06-baseline.md) snapshot for an existing codebase or a
-  zero-diagnostic gate for a clean one — writes a `.rigor.dist.yml`, and
-  generates the first baseline. Reach for it when setting Rigor up for
+  [baseline](06-baseline.md) snapshot by default, new projects
+  included, or an opt-in zero-diagnostic gate for users fluent in type
+  theory and RBS — writes a `.rigor.dist.yml`, and generates the first
+  baseline. Reach for it when setting Rigor up for
   the first time.
 - **`rigor-rbs-setup`** — installs community RBS for your gems
   (`rbs collection install`) so RBS-less dependencies stop typing as

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/12-caching.md

@@ -135,7 +135,7 @@ CI detection that `auto` relies on.
 
 | Flag | Effect |
 | --- | --- |
-| `rigor check --no-cache` | Run without reading or writing the persistent cache. |
+| `rigor check --no-cache` | Run without reading or writing the persistent cache. With `--incremental` this includes the snapshot: every file is analysed and the snapshot on disk is left untouched. |
 | `rigor check --clear-cache` | Delete the cache directory, then run. |
 | `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes (on stderr under every `--format` but `text`, so the document on stdout stays parseable). |
 | `rigor check --incremental` | Re-analyse only what changed; serve the rest from the incremental snapshot (see below). |
@@ -144,9 +144,12 @@ There is no config key to disable caching permanently — the
 flags are per-run toggles. To run without a persistent cache
 habitually, point `cache.path` at a disposable directory.
 
+With `--incremental --no-cache` and an editor buffer (`--tmp-file` with `--instead-of`), the buffer is analysed on its own, as it is when no snapshot exists, and the note says that `--no-cache` skipped the snapshot rather than suggesting `rigor check --incremental`.
+
 ## Size and eviction
 
-A project's active cache set is small (around 2 MB). Entries
+A project's active cache set is a few megabytes (about 10 MB
+for a Rails application the size of Mastodon). Entries
 are content-keyed, so events like a gem upgrade or an `.rbs`
 edit write fresh entries and leave the old ones *orphaned* —
 nothing references them, and no run would otherwise delete
@@ -219,9 +222,45 @@ dependents of removed ones.) As with the rest of the cache, a
 missing or corrupt snapshot is simply a full run; it can never
 wedge analysis.
 
+When nothing has changed since the last `--incremental` run, the
+answer comes straight from the cache, without starting the
+analyzer at all. Rigor first checks the inputs that answer was
+computed from — your source files and view templates, your RBS,
+your configuration and the files your plugins read — and runs the
+ordinary incremental re-check the moment any of them differs. On
+a Rails application the size of Mastodon, an unchanged
+`--incremental` run takes about a quarter of a second. An
+unchanged plain `rigor check` skips the analyzer the same way,
+except when a plugin compiles your view templates, as
+rigor-actionpack does.
+
+The shortcut stands aside under `--workers=N` (or
+`parallel.workers:`), `--explain`, `--cache-stats`, `--coverage`,
+an editor buffer, and an `effects:` block, and when the cache
+directory is on a different filesystem from the project; those
+runs re-check as before. It also switches itself off, silently:
+
+- when an input changes that the ordinary re-check does not look
+  at itself: an auto-detected `sig/` directory (one you did not
+  list under `signature_paths:`), a file a narrower
+  `rigor check --incremental DIR` only discovers from the rest of
+  your configured `paths:`, or a `pre_eval:` file outside the
+  analysed paths. The re-check may keep printing the answer from
+  before that change; the shortcut does not repeat it;
+- when an `--incremental` run cannot record its answer safely:
+  after a run with `--workers=N` that re-analysed files, when a file or directory changes while a run is reading
+  it, after a CI cache is restored onto a fresh checkout, or when
+  two runs race.
+
+Either way it stays off, and every run is an ordinary re-check,
+until the next full analysis. The ordinary re-check never starts
+one by itself: only a configuration, `Gemfile.lock` or Rigor
+version change does, or `--clear-cache`. So the shortcut can stay
+off indefinitely; run `rigor check --incremental --clear-cache`
+once to turn it back on.
+
 `--incremental` is most useful for fast local re-checks and CI
-on a changed branch. For a one-shot run on an unchanged project,
-the ordinary cache already serves the whole result in one step.
+on a changed branch.
 
 ## Concurrency
 

data/docs/manual/14-rails-quickstart.md

@@ -90,8 +90,9 @@ It runs eight phases in order:
 2. **Choose an adoption mode** — proposes either *acknowledge*
    (snapshot today's diagnostics into a baseline; catch
    regressions going forward) or *strict* (drive the project to
-   zero and keep it there). It recommends acknowledge for
-   codebases with more than ~100 initial diagnostics.
+   zero and keep it there). It recommends acknowledge for every
+   project, new ones included; strict is an opt-in for users
+   fluent in type theory and RBS.
 3. **Select plugins** — proposes the plugin set matching your
    detected stack; you confirm or trim the list.
 4. **Write `.rigor.dist.yml`** — the committed shared config,
@@ -151,14 +152,19 @@ source-of-truth copy is
 
 | Mode | When | What happens |
 | --- | --- | --- |
-| **Acknowledge** | Existing codebase with many diagnostics | Record today's diagnostics in a baseline; surface only new ones on each PR. |
-| **Strict** | New or small project | Zero outstanding diagnostics; no baseline. |
+| **Acknowledge** | Recommended for every project, new ones included | Record today's diagnostics in a baseline; surface only new ones on each PR. |
+| **Strict** | Opt-in, for users fluent in type theory and RBS | Zero outstanding diagnostics; no baseline. |
 
-If your first `rigor check` reports more than ~100 diagnostics,
-acknowledge mode is the natural starting point. You can tighten
-it later. In `.rigor.dist.yml` (Step 3) the mode maps to a
-`severity_profile:` — acknowledge → `lenient`, strict → `strict`
-(omit the key for the default `balanced`).
+Start with acknowledge mode even on a brand-new project. Rigor's
+inference still has gaps, so a zero-diagnostic gate meets
+diagnostics on correct code, and clearing those means fixing
+signatures or RBS rather than your code. Choose strict only if
+you are comfortable doing that yourself. You can tighten later.
+
+In `.rigor.dist.yml` (Step 3) the mode maps to a
+`severity_profile:`. Acknowledge mode uses the default `balanced`
+(omit the key), or `lenient` when the first `rigor check` reports
+more than ~100 diagnostics; strict mode uses `strict`.
 
 ### Step 3 — Write .rigor.dist.yml
 
@@ -198,7 +204,7 @@ plugins:
   - rigor-rspec
   - rigor-factorybot
 
-severity_profile: lenient   # "strict" for strict mode; omit for "balanced"
+# severity_profile: lenient   # only for >100 initial diagnostics; "strict" for strict mode
 
 # baseline: .rigor-baseline.yml   # uncomment after Step 6 (acknowledge mode only)
 ```
@@ -288,7 +294,9 @@ first, then large clusters to record in a baseline.
 
 ### Step 6 — Generate a baseline (acknowledge mode)
 
-*Skip this step if you chose strict mode.*
+*Skip this step if you chose strict mode.* Settle `severity_profile:`
+first: changing it afterwards changes which rules fire and leaves the
+baseline out of step.
 
 ```sh
 rigor baseline generate

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

data/docs/manual/19-effect-labels.md

@@ -214,6 +214,16 @@ rigor effects --pure
 436 methods on Redmine, and they are your `%a{pure}` candidates — the on-ramp to
 the last section of this chapter.
 
+You do not have to write them all out by hand. With the `effects:` block in
+place, `rigor sig-gen` annotates the methods in this set whose signature it is
+proposing anyway: `%a{pure}` above every method that is exhaustive, undischarged,
+free of surviving `≤` labels, not already carrying a bound you wrote, and calling
+nothing the analyzer had no description for; and, under `--effect-envelopes`, the labelled spelling for the methods that
+do have a footprint. A method that is clean only because `effects.tolerated:`
+says so is deliberately left bare — the annotation would travel to readers who
+do not share your tolerated list. See
+[handbook chapter 11](../handbook/11-sig-gen.md#emitting-effect-annotations).
+
 ### Asking it a question
 
 **By label.** The question this chapter opens with, in one command:

data/docs/manual/plugins/README.md

@@ -54,6 +54,9 @@ The full catalogue, with a one-line scope for every plugin, is
   `Result` / `Option` unwrap types and synthesises `Enum` variants.
 - [rigor-pundit](rigor-pundit.md) — policy-class existence and
   `authorize(record, :action)` predicate validation.
+- [rigor-active-model-serializers](rigor-active-model-serializers.md) —
+  types the `object` reader inside a serializer as the serializer's
+  model (no diagnostics).
 - [rigor-sidekiq](rigor-sidekiq.md) — Sidekiq `Worker.perform_*`
   argument arity against the discovered `#perform`.
 - [rigor-actioncable](rigor-actioncable.md) — `broadcast_to` channel
@@ -62,6 +65,10 @@ The full catalogue, with a one-line scope for every plugin, is
   through Minitest / Test::Unit assertions and spec matchers.
 - [rigor-graphql](rigor-graphql.md) — GraphQL-Ruby type / enum / input
   / mutation table publication (cross-plugin facts, no diagnostics).
+- [rigor-grape](rigor-grape.md) — types the `Grape::API` endpoint DSL
+  (`params`, `namespace`, verb macros, `desc`, `route_setting`) and
+  `Grape::Entity` `expose` declarations, including the `instance_eval`'d
+  block `self` bindings.
 - [rigor-rspec-rails](rigor-rspec-rails.md) — `have_http_status`
   argument validation (out-of-range codes, unknown status symbols).
 - [rigor-shoulda-matchers](rigor-shoulda-matchers.md) — shoulda matcher