rigortype 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 565d25fe6c480013419e1e7f6d2bcb60512f7cf56c6a34b612e5951dad8b6c62
-  data.tar.gz: c48e0fcde278beb45ac4b8cb0c5acb272540d8bbc5c37111e983ffacee4c772d
+  metadata.gz: 7cea93d0b50519bad210f33907d4135c61043d910618153ad76f1f25b0163b4d
+  data.tar.gz: 45cba56af68f2ee34c7e8674310fb35bb74e366a3fc67bc89262ad8cb9556cc7
 SHA512:
-  metadata.gz: 8859749b0ee71c8dca814c164de8e47bd3004f52773299181f8aeca2bb30b5c96dc47bf46278a3378704f548a30ab68c3cb273b71a2c7346b6bba67bfbfb9365
-  data.tar.gz: 450f2f074e21d3a3fd7cff2e9f7f8971dd838bdfe1fadc0e80300e7c3dc9a98eb13b9890033436b77f5e82196238c91503f598fce78435f9ce9d598c64fd2e87
+  metadata.gz: 626ef3d0d0967cfd0f8e887a7ab2f53ed741a848fd25f90239c69e7a40e84c3b4a658acd945da0fd4d344d9de9cc650c3be8236f107468b70e2d32441ee9d7d3
+  data.tar.gz: e23af83633c18c05dce1a01814f235838143a31f3a34cf719ca35239a40bc854fff8f8e4bd55f4d0c4f39547b4b600c7c543019055576e297fed36ef60a70537

data/README.md

@@ -231,8 +231,8 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.2.9`** (2026-07-11) — the latest cut on the
-`0.2.x` evaluation line opened by `v0.2.0`, the first
+Current release: **`v0.3.0`** (2026-07-19) — the first cut on the
+`0.3.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a
 minor-non-break trial, rehearsing the contract that hard-freezes at

data/docs/handbook/03-narrowing.md

@@ -275,7 +275,8 @@ end
 (Narrowing the truthy edge further to specific refinement
 carriers — so `\d{4}` would produce `decimal-int-string` — is a
 demand-driven follow-up on the regex-pattern → refinement-name
-recogniser track; see [`docs/ROADMAP.md`](../ROADMAP.md).)
+recogniser track, tracked as
+[#164](https://github.com/rigortype/rigor/issues/164).)
 
 ## Negation and `unless`
 

data/docs/handbook/04-tuples-and-shapes.md

@@ -221,9 +221,13 @@ arr = [1, ARGV.first]
 # Array[Constant<1> | String?]
 ```
 
-The same goes for hashes whose keys are not provably symbol /
-string literals — Rigor produces `Hash[K, V]` rather than
-`HashShape`.
+The same goes for hashes whose keys are not provably scalar
+literals (symbols, plain strings, integers, floats, `true` /
+`false` / `nil`) — Rigor produces `Hash[K, V]` rather than
+`HashShape`. Within a shape, key identity follows `Hash#eql?`:
+`1` and `1.0` are distinct keys, and a repeated literal key
+keeps the last entry, exactly like the runtime. Non-symbol,
+non-string keys display in hashrocket form (`{ 1 => 2 }`).
 
 ## Deriving new shapes — `pick_of` / `omit_of` / `partial_of` / `required_of` / `readonly_of`
 

data/docs/handbook/06-classes.md

@@ -170,8 +170,8 @@ discovery composes uniformly across both shapes.
 
 `Struct.new(*Symbol)` produces a positional-arg constructor
 plus the same accessors as `Data.define`. Rigor folds struct
-member reads too, but — because a `Struct` is mutable — only
-where the value cannot have changed:
+member reads too, and — because a `Struct` is mutable — tracks a
+straight-line setter so the read stays precise:
 
 ```ruby
 Coord = Struct.new(:x, :y)
@@ -181,18 +181,27 @@ c = Coord.new(10, 20)
 assert_type("10", c.x)
 assert_type("20", c.y)
 
-# A local that is mutated, aliased, or escapes is not fold-safe —
-# its reads degrade to Dynamic, never a stale value.
+# A straight-line setter re-types the member; the sibling stays precise.
 m = Coord.new(1, 2)
 m.x = 9
-assert_type("Dynamic[top]", m.x)
+assert_type("9", m.x)
+assert_type("2", m.y)
+
+# A local that is aliased, escapes, or is mutated inside a loop or
+# block is not fold-safe — its reads degrade to Dynamic, never a
+# stale value, because a write Rigor cannot see could have changed it.
+a = Coord.new(1, 2)
+alias_ref = a
+a.x = 9
+assert_type("Dynamic[top]", a.x)
 ```
 
 Because `Struct` accessors are also writers, the fold is gated:
-a member read off a freshly constructed instance (`Coord.new(1,
-2).x`) or a local the analysis proves is never written, aliased,
-or passed away folds to the member's type; anything else widens
-to `Dynamic[top]`. `Data` is read-only, so its reads always fold.
+a member read folds off a freshly constructed instance (`Coord.new(1,
+2).x`), off a local the analysis proves is never written, aliased, or
+passed away, or off one whose only writes are straight-line member
+setters (their assigned type flows into the later read); anything else
+widens to `Dynamic[top]`. `Data` is read-only, so its reads always fold.
 
 ## Inheritance and method resolution
 

data/docs/handbook/08-understanding-errors.md

@@ -87,6 +87,7 @@ Fire when the control flow itself is unsound.
 | `flow.always-truthy-condition` | The predicate of an `if` / `unless` / ternary is provably truthy (or falsey) by inferred type, with surgical skips inside loop bodies and on defensive predicate calls. | warning |
 | `flow.unreachable-clause` | A `case <local>; when <Class>` (or bare-class `case`/`in`) clause whose subject narrowing proves it can never match — disjoint from the subject's type, or already exhausted by an earlier clause. | info under `balanced`, warning under `strict`, info under `lenient` |
 | `flow.dead-assignment` | A plain local-variable write whose target name is never read in the same `def` body. | warning |
+| `flow.duplicate-hash-key` | Two entries of one Hash literal carry the same literal key (`{ a: 1, a: 2 }`, `m("x" => 1, "x" => 2)`) — the last entry wins silently at runtime. Literal keys only; `:a` vs `"a"` and `1` vs `1.0` are distinct keys and never compared. | warning |
 
 `flow.unreachable-branch`, `flow.always-truthy-condition`, and
 `flow.unreachable-clause` are the **reachability family** — each

data/docs/handbook/11-sig-gen.md

@@ -93,7 +93,7 @@ states:
 | `equivalent` | The inferred return is not a strict subtype of the declared one — identical, wider, or unrelated — so there is nothing to tighten. Silently skipped. |
 | `skipped` | Disqualified for one of the reasons below. |
 
-The three `sig.skipped.*` reasons are:
+The `sig.skipped.*` reasons are:
 
 - `sig.skipped.complex-shape` — the method has optional, rest,
   keyword, block, or forwarding parameters. The MVP's
@@ -105,6 +105,16 @@ The three `sig.skipped.*` reasons are:
 - `sig.skipped.user-authored` — `--overwrite` was not set
   and the method's existing RBS declaration would have to
   be replaced.
+- `sig.skipped.unrenderable-rbs` — the signature Rigor
+  rendered for this method does not parse as RBS. This one
+  is a **bug in Rigor**, not a property of your code: every
+  generated line is parsed before it is emitted, and a line
+  `rbs` rejects is dropped rather than written, because an
+  unparseable `.rbs` is quarantined *whole* by `rigor check`
+  — one bad line would take every other type in the file
+  down with it. The rest of the signatures are unaffected;
+  the skipped method is reported on stderr, and it is worth
+  reporting to us.
 
 The three `sig.generated.*` identifiers
 (`sig.generated.new-file` / `new-method` / `tighter-return`)

data/docs/handbook/appendix-mypy.md

@@ -345,9 +345,10 @@ def shout: (String s) -> non-empty-string
 
 You gain: `s.empty?` is a recognised refinement narrower (no
 need for `assert s`). `match?(/\A\d+\z/)` does not yet narrow
-to `numeric-string` (this is on the v0.1.1 roadmap — see
-[`docs/ROADMAP.md`](../ROADMAP.md)), but the eventual
-behaviour will mirror `s.isdigit()` narrowing in Pyright.
+to `numeric-string` (queued as
+[#164](https://github.com/rigortype/rigor/issues/164)), but the
+eventual behaviour will mirror `s.isdigit()` narrowing in
+Pyright.
 
 ## What's next
 

data/docs/install.md

@@ -37,19 +37,27 @@ Then proceed to the **first** matching case below.
 and pins language runtimes (Ruby, Node, Python, …) and tool gems
 (like `rigortype`) per project, recording versions in a `mise.toml`
 that can be committed alongside the code. Other contributors — and CI
-— run `mise install` to restore the exact same versions with no
-`Gemfile` involvement.
+— run `mise install` to restore those versions with no `Gemfile`
+involvement.
 
 Run in the project root:
 
 ```sh
 mise use ruby@4.0
-mise use gem:rigortype
+mise use --pin gem:rigortype
 ```
 
 `mise use` installs the tools and writes their versions to `mise.toml`
 in one step. Commit `mise.toml` so the version is shared.
 
+`--pin` records the exact Rigor version (`"gem:rigortype" = "0.2.9"`).
+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`.
+
 Then verify:
 
 ```sh
@@ -184,6 +192,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 use gem:rigortype` (or
-`gem update rigortype` for Case C/B); on an older version, run
-`rigor skill rigor-project-init` directly.
+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.

data/docs/manual/01-installation.md

@@ -244,9 +244,23 @@ A few things worth knowing if you have not used mise before:
   *current directory* recording the chosen versions, and installs
   the tools as part of the same command — there is no separate
   install step. (mise also reads the asdf-style `.tool-versions`.)
-- **Commit the config to share versions.** Check the generated
-  `mise.toml` into Git so every contributor — and every CI run —
-  resolves the same Ruby 4.0 and the same Rigor version.
+- **Commit the config to share versions — and pass `--pin` if you
+  mean it.** Check the generated `mise.toml` into Git so every
+  contributor, and every CI run, resolves the same versions. Note
+  what the two commands above actually record, because they differ:
+  `mise use ruby@4.0` preserves the precision you asked for and
+  writes `ruby = "4.0"` (any 4.0.x), but `mise use gem:rigortype` has
+  no requested version to preserve and writes `"gem:rigortype" =
+  "latest"` — which resolves to whatever is newest *on each machine,
+  whenever that machine first installs it*. A committed `latest` is
+  not a shared version. To share one, pin it:
+
+  ```sh
+  mise use --pin gem:rigortype     # records e.g. "gem:rigortype" = "0.2.9"
+  ```
+
+  Then read [Keeping Rigor up to date](#keeping-rigor-up-to-date):
+  a pin is a version that will not move until you move it.
 - **For a machine-wide install, add `-g`.** `mise use -g
   gem:rigortype` writes mise's global config
   (`~/.config/mise/config.toml`) instead of a project `mise.toml`,
@@ -284,6 +298,48 @@ explicitly with `mise exec gem:rigortype -- rigor`. See
 [Editor integration](09-editor-integration.md) for the editor
 side.
 
+### Keeping Rigor up to date
+
+Rigor ships often. How you upgrade depends on what your config
+records — and in one case, on knowing that mise will not tell you an
+upgrade exists.
+
+- **`"gem:rigortype" = "latest"`** — what a plain `mise use
+  gem:rigortype` writes. `mise upgrade gem:rigortype` moves you to the
+  newest release.
+- **An exact pin** — `"gem:rigortype" = "0.2.9"`, from `--pin` or from
+  `mise use gem:rigortype@0.2.9`. Here `mise upgrade` **will not move
+  it, and `mise outdated` will not report it.** Both compare the
+  installed version against the range the config asks for, and an
+  exact pin is a range containing only itself, so a pinned Rigor
+  reports itself up to date forever, however far behind it has fallen.
+  Use `--bump`, which installs the newest release *and* rewrites the
+  pin:
+
+  ```sh
+  mise upgrade --bump gem:rigortype
+  ```
+
+Neither is a bug to work around — a pin doing nothing is a pin working.
+But it does mean a pinned setup has no passive signal that a new Rigor
+exists: `--bump` is both how you look and how you move.
+
+**After a Ruby change.** mise's `gem:` backend installs each tool
+against the Ruby that was active at install time, and its
+[gem backend docs](https://mise.jdx.dev/dev-tools/backends/gem.html)
+note that "if the ruby version used by a gem package changes, (by mise
+or system ruby), you may need to reinstall the gem". Rigor's pinned
+`ruby@4.0` makes this rare — patch upgrades within 4.0.x are followed
+automatically — but if you remove or replace that Ruby, reinstall:
+
+```sh
+mise install -f gem:rigortype     # or, for every gem-backend tool:
+mise install -f "gem:*"
+```
+
+On a plain `gem install` (below), the equivalent is `gem update
+rigortype`.
+
 ## asdf
 
 `asdf` follows the same model. Install a Ruby 4.0.x with the
@@ -300,7 +356,8 @@ gem install rigortype
 `asdf` has no general-purpose gem backend, so the gem itself is
 installed with `gem install` rather than an `asdf` command. `mise`
 (above) is the more integrated option because its `gem:` backend
-pins the gem the same way it pins Ruby.
+records the gem in the same config that records Ruby, and — as the
+next section explains — keeps the two from interfering.
 
 ## Simple alternative — gem install
 
@@ -316,6 +373,43 @@ quickest path, but it records nothing per project: a version
 manager keeps the Rigor version pinned next to the project, so
 local runs and CI cannot drift apart.
 
+It also leaves Rigor sharing a Ruby with your work, which is the
+deeper reason the version managers are listed first. The executable
+RubyGems installs begins with `#!/usr/bin/env ruby`, so it runs under
+whatever `ruby` is first on `PATH` *at the moment you invoke it* — and
+because Rigor requires Ruby 4.0 while your projects pin their own,
+running `rigor` inside a project on Ruby 3.x fails before it starts.
+mise's `gem:` backend does not have this failure mode: it installs each
+tool into its own private gem directory and points the executable at
+the Ruby the tool was installed with, so a project's Ruby pin cannot
+reach it. A `gem install` under a Ruby 4.0 you never switch away from
+is perfectly fine; one that shares a Ruby with projects you switch
+between is a footgun.
+
+## If you want Bundler to manage the version
+
+The rule at the top of this chapter is about your *application's*
+`Gemfile` — the one Bundler resolves against your app's gems, and whose
+entries `Bundler.require` loads at boot. It is not a rule against
+Bundler. A `Gemfile` holding nothing but Rigor, resolved separately and
+selected with `BUNDLE_GEMFILE`, keeps every property the prohibition
+exists to protect: your application's dependency graph never meets
+Rigor's, and your application's Ruby is never constrained by Rigor's.
+
+That arrangement — a `Gemfile` under `.github/rigor/`, plus the
+Dependabot config that keeps it current — is written up under
+[Pinning Rigor's version](11-ci.md#pinning-rigors-version) in the CI
+chapter. Nothing about it is CI-specific:
+
+```sh
+BUNDLE_GEMFILE=.github/rigor/Gemfile bundle exec rigor check
+```
+
+It is more moving parts than `mise use --pin gem:rigortype`, which
+records the same version in one line and needs no `bundle exec`. Reach
+for it when your team already runs everything through Bundler and wants
+Rigor on the same footing — not as a first choice.
+
 ## Nix
 
 If you use Nix, Rigor's flake exposes the executable as a package,

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

@@ -41,12 +41,12 @@ the `paths:` list from the configuration file.
 | `--cache-stats` | Print the on-disk cache inventory when finished. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
 | `--coverage` | Add a type-precision coverage block to the output (`coverage` object under `--format json`; a one-line summary in text mode). Off by default — it is a second precision pass over the analyzed files, the same scan [`rigor coverage`](#rigor-coverage) runs, so it is opt-in. |
-| `--workers=N` | Dispatch analysis across `N` parallel worker processes (fork-based pool today; ADR-15). Default `0` (sequential). |
+| `--workers=N` | Dispatch analysis across `N` parallel worker processes (fork-based pool today; ADR-15). Default `0` (sequential). Applies to `--incremental` re-checks as well as full runs. |
 | `--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. |
 | `--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. The overlay is empty in this release, so this is currently a no-op. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
+| `--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). |
 | `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. |
 
@@ -183,6 +183,17 @@ rigor sig-gen [paths]
 | `--new-files` / `--new-methods` / `--tighter-returns` | Emit only that classification. |
 | `--format=text\|json` | Output format. |
 
+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
+`.rbs` is quarantined *whole* by `rigor check`, so one bad line
+would take every other type in the file down with it. Under
+`--write`, a file whose assembled content does not parse is
+**refused** (the existing file is left untouched) and the command
+exits `1`: you asked for a write and did not get one. Such a skip
+is a bug in Rigor's RBS rendering, not in your code — please
+report it.
+
 ## `rigor lsp`
 
 Run the Language Server over stdio. See
@@ -400,6 +411,11 @@ Report the activation status of every plugin configured in
 `.rigor.yml` — loaded, load-error (with reason), and each
 plugin's declared extension surfaces. See [Plugins](07-plugins.md).
 
+Each loaded plugin's row also reports the resolved file it
+loaded from (a `path:` line in text, a `"path"` key in JSON), so
+if a stale installed gem is shadowing a newer checkout's bundled
+plugin copy the mismatch is visible at a glance.
+
 ```sh
 rigor plugins [--format=text|json] [--strict] [--capabilities] [--config=PATH]
 ```
@@ -474,8 +490,9 @@ rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 | `--describe` | Probe the project's state (config / baseline / `sig/` / CI — presence only, never runs `rigor check`) and recommend the next skill to run. Also spelled `describe`; surfaced top-level as [`rigor describe`](#rigor-describe) below. |
 
 The verb spellings `rigor skill list` / `print <name>` / `path <name>`
-are **deprecated** (a one-line stderr notice; removed in v0.3.0) — use
-the forms above. `describe` / `--describe` stay first-class.
+were **removed in v0.3.0** — the positional slot is a skill name, so
+they now read as an unknown skill. Use the forms above.
+`describe` / `--describe` stay first-class.
 
 ## `rigor describe`
 
@@ -518,8 +535,9 @@ rigor docs [<name>] [--path <name>] [--list [<category>]]
 | `--path <name>` | Print the single-line absolute path of a doc, suitable as input to a file-reading tool. |
 | `--list [<category>]` | Table of every bundled doc (name + absolute path); pass `manual` or `handbook` to filter. |
 
-The verb spellings `rigor docs list` / `path <name>` are **deprecated**
-(a one-line stderr notice; removed in v0.3.0) — use `--list` / `--path`.
+The verb spellings `rigor docs list` / `path <name>` were **removed in
+v0.3.0** — the positional slot is a doc name, so they now read as an
+unknown doc. Use `--list` / `--path`.
 
 The canonical web copy of the index is
 <https://rigor.typedduck.fail/llms.txt>; `rigor docs` serves the same
@@ -543,12 +561,16 @@ rigor show-bleedingedge [--config PATH] [--format text|json]
 | `--config PATH` | Use this `.rigor.yml` instead of auto-discovery. |
 | `--format text\|json` | Output format. Default `text`. |
 
-The overlay is **empty in this release** — the mechanism is wired and
-ready, but no discipline has been queued for a major yet, so the command
-currently reports an empty set. When a feature is queued it appears here
-with its stable id, the severity it would impose, and whether your config
-adopts it. See [`docs/compatibility.md`](../compatibility.md) for how
-bleeding-edge fits the stability model.
+Each queued feature appears with its stable id, the severity it imposes,
+and whether your configuration adopts it. See
+[`docs/compatibility.md`](../compatibility.md) for how bleeding-edge fits
+the stability model.
+
+Queued today:
+
+| Feature id | What it changes |
+| --- | --- |
+| `reject-unparseable-signatures` | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
 
 ## `rigor doctor`
 
@@ -575,6 +597,18 @@ Runs a scoped analysis and audits:
   from the saved baseline.
 - **Rails plugin gap** — whether `Gemfile.lock` contains Rails gems
   but no Rails plugin is enabled.
+- **Gemfile install** — whether Rigor itself resolves as one of the
+  project's dependencies, which
+  [Installing Rigor](01-installation.md) tells you not to do. Only a
+  `rigortype` resolved from a **GEM** remote counts: a `PATH` or `GIT`
+  source means you are developing or vendoring Rigor deliberately,
+  and Rigor's own repository looks exactly like that.
+- **Plugin installation skew** — whether a plugin Rigor bundles
+  loaded from a different `rigortype` installation than the engine,
+  naming both paths. The engine and its bundled plugins are
+  versioned together, so a copy from another installation can run
+  the engine with a mismatched plugin. A warning, not a failure;
+  third-party plugins from your own bundle are never flagged.
 
 Text output prints `[PASS]`, `[FAIL]`, or `[WARN]` per check plus a
 routed hint (e.g. "Run `rigor baseline regenerate`"). JSON output
@@ -618,6 +652,9 @@ 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_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_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 a long `check` / `coverage` 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. |
 
 Three further variables (`RIGOR_BUDGET_TRACE`,
 `RIGOR_HEAP_PROFILE`, `RIGOR_HEAP_TRACE`) enable developer-facing

data/docs/manual/03-configuration.md

@@ -22,6 +22,24 @@ discovery entirely.
 All relative paths in a config file resolve against that
 file's own directory.
 
+## Editor validation
+
+Rigor ships a JSON Schema for this file. Editors that
+understand the [`yaml-language-server`](https://github.com/redhat-developer/yaml-language-server)
+magic comment — VS Code's YAML extension, the IntelliJ
+family, Helix, Neovim with `yaml-ls` — give you
+autocomplete, hover docs, and structural validation as you
+type:
+
+```yaml
+# yaml-language-server: $schema=https://github.com/rigortype/rigor/raw/master/schemas/rigor-config.schema.json
+```
+
+`rigor init` writes that line for you. The schema is not a
+copy of this page — it is a source of truth in its own
+right, kept in step with the loader by a spec, so a key it
+rejects is a key Rigor does not accept.
+
 ## A minimal config
 
 ```yaml
@@ -44,6 +62,7 @@ cache:
 | `exclude` | Array | `[]` | Glob patterns to skip. `vendor/bundle`, `.bundle`, and `node_modules` are always excluded. |
 | `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`. |
 
 ### Type sources
 
@@ -65,6 +84,7 @@ types it was meant to describe into a high-confidence
 of real type errors. The audit covers:
 
 ```
+rigor: `excludee` is not a recognized configuration key; it has no effect. Did you mean `exclude`?
 rigor: signature_paths: "/path/to/sig" does not exist (no signatures loaded from it)
 rigor: signature_paths: "/path/to/sig" matched 0 signature files
 rigor: libraries: "csb" is not an available RBS library (no signatures loaded from it)
@@ -73,6 +93,11 @@ rigor: severity_overrides: "flow.bogus" is not a recognized rule id; the overrid
 rigor: bundler.lockfile: "./missing/Gemfile.lock" does not exist
 ```
 
+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
+the JSON schema as you type rather than at check time.
+
 These are warnings, not errors — partial or optional bundles and
 forward-looking config are valid setups. The audit only fires on explicit,
 working-setup-safe signals: an unset default (auto-detected `<root>/sig`,
@@ -91,7 +116,7 @@ statically and may resolve at run time. The same findings appear in the
 | `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
 | `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
 | `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |
-| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued diagnostic disciplines early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). The overlay is empty in this release, so every form is currently a no-op. |
+| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued diagnostic disciplines early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
 
 ### Dependency RBS discovery
 
@@ -128,11 +153,18 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 | --- | --- | --- | --- |
 | `cache.path` | String | `.rigor/cache` | Persistent cache directory. See [Caching](12-caching.md). |
 | `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). |
-| `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. |
+| `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_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`. |
 
+### Reserved for other implementations
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `rigor_rs` | Hash | — | **Reserved; this implementation skips it.** Another Rigor implementation reads keys under this namespace, so one `.rigor.yml` can serve both. Rigor validates its shape at the schema level only — it never reads the value, and an invalid one is never a runtime error here. Leave it alone unless the tool that reads it tells you otherwise. |
+
 ## A worked example
 
 ```yaml

data/docs/manual/04-diagnostics.md

@@ -41,18 +41,26 @@ carries no `documentation_url`.
 | <a id="rule-call-wrong-arity"></a>`call.wrong-arity` | The positional-argument count matches no signature. | high |
 | <a id="rule-call-argument-type-mismatch"></a>`call.argument-type-mismatch` | An argument's type provably violates the parameter contract. | high |
 | <a id="rule-call-possible-nil-receiver"></a>`call.possible-nil-receiver` | The receiver is `T \| nil` and the method is not defined on `NilClass`. | high |
+| <a id="rule-call-raise-non-exception"></a>`call.raise-non-exception` | A `raise` / `fail` argument's concrete type is provably not an Exception class, an Exception instance, a String, or an object defining `#exception` — a runtime `TypeError`. | high |
 | <a id="rule-call-unresolved-toplevel"></a>`call.unresolved-toplevel` | A top-level implicit-self call resolves against no same-file `def`, `pre_eval:` patch, or `Kernel` / `Object` method. | low |
 | <a id="rule-flow-always-raises"></a>`flow.always-raises` | The expression provably raises on every reachable path. | high |
 | <a id="rule-flow-unreachable-branch"></a>`flow.unreachable-branch` | An `if` / `unless` / ternary branch is statically dead. | high |
 | <a id="rule-flow-always-truthy-condition"></a>`flow.always-truthy-condition` | A condition is provably always truthy or always falsey. | medium |
 | <a id="rule-flow-dead-assignment"></a>`flow.dead-assignment` | A local is written but never read in the same method. | medium |
 | <a id="rule-flow-unreachable-clause"></a>`flow.unreachable-clause` | A `case`/`when` or `case`/`in` clause is statically dead — its subject type is disjoint with the pattern, or a prior clause already exhausted the subject. | medium |
+| <a id="rule-flow-duplicate-hash-key"></a>`flow.duplicate-hash-key` | A Hash literal repeats a literal key (symbol, plain string, integer, float, `true`/`false`/`nil`) — the last entry silently overwrites the earlier one at runtime. Literal keys only; symbol vs string and `1` vs `1.0` never collide, and interpolated / constant / computed keys are never compared. A `**splat` between two identical literal keys does not rescue the pair. | high |
+| <a id="rule-flow-return-in-ensure"></a>`flow.return-in-ensure` | An explicit `return` inside an `ensure` clause — it overrides the method's in-flight return value and silently swallows any in-flight exception. A `return` in a nested `def`, lambda, or `define_method` block inside the `ensure` does not fire (it exits that inner frame). | high |
+| <a id="rule-flow-shadowed-rescue-clause"></a>`flow.shadowed-rescue-clause` | A `rescue` clause can never run because an earlier clause of the same chain already catches a superclass (or the same class) of every exception class it names. | high |
 | <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
 | <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write. | high |
 | <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
 | <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | 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-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 |
 | <a id="rule-rbs_extended-unsatisfied-conformance"></a>`rbs_extended.unsatisfied-conformance` | A class declares `%a{rigor:v1:conforms-to _Interface}` in its RBS but is missing a method the interface requires. Presence-based: only definitively-absent required methods fire. | — |
 | <a id="rule-assert-type-mismatch"></a>`assert.type-mismatch` | An `assert_type` expectation does not match the inferred type. | high |
 | <a id="rule-dump-type"></a>`dump.type` | A `dump_type` call — informational, prints the inferred type. | — |
@@ -192,6 +200,21 @@ config.merge(extra)  # rigor:disable call.undefined-method
 It accepts qualified IDs, family wildcards (`call`), a
 comma- or space-separated list, or `all`.
 
+A marker that cannot work is flagged rather than silently
+ignored: a token that names no known rule (a typo like
+`call.undefined-metod`) fires
+[`suppression.unknown-rule`](#rule-suppression-unknown-rule),
+a bare marker with no rules at all fires
+[`suppression.empty`](#rule-suppression-empty), and a marker
+word outside Rigor's grammar (the RuboCop reflex
+`# rigor:disable-next-line <rule>`, or `# rigor:enable`)
+fires
+[`suppression.unknown-marker`](#rule-suppression-unknown-marker)
+— all `:warning` in every profile. Tokens under the `plugin.`
+prefix are never flagged (plugin rule vocabularies load
+dynamically), and the surveillance diagnostics are themselves
+suppressible like any other rule.
+
 **In-source, whole file.** `# rigor:disable-file <rules>`
 anywhere in a file suppresses those rules for every line;
 `# rigor:disable-file all` silences the file.

data/docs/manual/07-plugins.md

@@ -40,10 +40,10 @@ each plugin's options — but the families today are:
 - **Rails** — `rigor-activerecord`, `rigor-actionpack`,
   `rigor-rails-routes`, `rigor-rails-i18n`,
   `rigor-actionmailer`, `rigor-activejob`,
-  `rigor-activestorage`, `rigor-actioncable`. The
-  `rigor-rails` meta-gem bundles the Rails set for Gemfile
-  convenience; you still enumerate the individual plugins you
-  want under `plugins:`.
+  `rigor-activestorage`, `rigor-actioncable`. Enumerate the ones
+  you want under `plugins:` — there is no umbrella entry that
+  turns on the Rails set as a group
+  ([ADR-96](../adr/96-plugin-target-gems.md) WD3 proposes one).
 - **Testing** — `rigor-rspec`, `rigor-rspec-rails`,
   `rigor-minitest`, `rigor-shoulda-matchers`,
   `rigor-factorybot`.

data/docs/manual/09-editor-integration.md

@@ -201,8 +201,8 @@ For a legacy bundler-based install, swap the connection list to
   analyzer assigns the receiver.
 - Mid-edit buffer support is best-effort. If parse fails AND the
   cursor isn't right after `.` / `::`, the v1 LSP returns no
-  completions; deeper recovery is queued (see ROADMAP §
-  "Editor / IDE integration").
+  completions; deeper recovery is queued (see the open
+  [`area:editor` issues](https://github.com/rigortype/rigor/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%3Aeditor)).
 
 **Hover shows `untyped` everywhere.**
 
@@ -236,8 +236,8 @@ LSP v1 + v2 landed in v0.1.6 and ship in the `0.1.x` line. Queued
 follow-ups (`textDocument/signatureHelp`, hash-key completion,
 `textDocument/definition`, incremental `didChange` sync, Ractor
 pool dispatch, codeAction / rename / semanticTokens / inlayHint)
-are demand-driven; see ROADMAP § "Editor / IDE integration" for
-the current queue.
+are demand-driven; the current queue is the open
+[`area:editor` issues](https://github.com/rigortype/rigor/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%3Aeditor).
 
 To request a queued feature or report an LSP issue, open a GitHub
 issue with: the editor + version, the Rigor version