rigortype 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d38773edf003d6de8ea6ec3de2f19aac4c2d74e404c56f39d1ed9595f388a648
-  data.tar.gz: beb2b7aea30bf74f4cc8d22e66d441d63ecb906689d6a22c6ca647a7a087a719
+  metadata.gz: 7cea93d0b50519bad210f33907d4135c61043d910618153ad76f1f25b0163b4d
+  data.tar.gz: 45cba56af68f2ee34c7e8674310fb35bb74e366a3fc67bc89262ad8cb9556cc7
 SHA512:
-  metadata.gz: 1c33b18e310c956f9cc9bbd4806228a095bcf95a137efba50affd49ffca17decac9107006e4a7fd350a9783f289e7d9e336ebc99755e7d69ce321d60b21c731b
-  data.tar.gz: c9f7286bc00f3419083ced2e35678062e8508dfe03b6064fe6c9f4cf4ad752479ca8801cce059cb3fc6bc0ee0eaaa216824a9d43cc93332feb7e267ab988253c
+  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.8`** (2026-07-06) — 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/data/core_overlay/csv.rbs

@@ -0,0 +1,28 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- CSV::MalformedCSVError.new(message, line_number) ---
+#
+# The pinned `rbs` gem's `csv.rbs` never declares `MalformedCSVError`'s own
+# constructor, so it falls back to the inherited `StandardError#initialize`
+# (arity 0..1). But the `csv` gem's real, documented constructor takes two
+# arguments — the message and the 1-based line number:
+#
+#   raise CSV::MalformedCSVError.new("Unquoted fields...", line)
+#
+# Without the two-arg form a raise like GitLab's
+# `import_csv/base_service.rb` false-fires `call.wrong-arity`
+# ("expected 0..1, got 2"). The line number is optional here so the
+# inherited single-arg form still type-checks.
+
+# `CSV` is a CLASS in Ruby / RBS (a `module CSV` wrapper collides with upstream
+# once the `csv` stdlib is in scope). It must be declared EXPLICITLY here — the
+# overlay loads unconditionally, but `csv` is a stdlib library loaded only on
+# demand, so a bare `class CSV::MalformedCSVError` would make RBS *synthesize*
+# the `CSV` parent namespace (ADR-5) in every env that does not load `csv`,
+# polluting `synthesized_namespaces`. Declaring `class CSV` reopens it cleanly
+# when `csv` is loaded and declares it plainly when it is not.
+class CSV
+  class MalformedCSVError
+    def initialize: (String message, ?Integer line_number) -> void
+  end
+end

data/data/core_overlay/psych.rbs

@@ -0,0 +1,22 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Psych.parse / Psych.parse_stream ---
+#
+# The pinned `rbs` gem's `psych.rbs` declares `Psych.load` / `load_file` /
+# `safe_load` / `unsafe_load*` but omits `Psych.parse` — a real, documented
+# stdlib method (`YAML.parse` is the same method, `YAML` being an alias of
+# `Psych`). It parses one YAML document into a `Psych::Nodes::Document` AST
+# (used for structure-preserving inspection) and raises on a syntax error.
+#
+#   YAML.parse(File.read("config.yml"))   # => Psych::Nodes::Document
+#
+# Without the declaration a call like GitLab's
+# `release_highlights/validator.rb` `YAML.parse(...)` false-fires
+# `call.undefined-method`. The return is left `untyped` — the node AST is
+# rarely consumed with per-method precision, and depending on
+# `Psych::Nodes::Document` being present in the pinned RBS would be brittle.
+
+module Psych
+  def self.parse: (String yaml, ?filename: untyped) -> untyped
+  def self.parse_stream: (String yaml, ?filename: untyped) -> untyped
+end

data/docs/handbook/01-getting-started.md

@@ -87,6 +87,14 @@ silent everywhere it cannot prove a narrower type.
 A diagnostic only fires when Rigor has enough static
 information to be confident.
 
+Where a *signature* does appear in this book — like
+`def foo: (String) -> Integer` — that is **RBS**, Ruby's standard
+signature language; read it as "takes a `String`, returns an
+`Integer`." You write none of it to get started; Rigor consumes
+whatever RBS your gems and the standard library already ship.
+[Chapter 7](07-rbs-and-extended.md) covers RBS in full — if you
+have never seen it, skim that chapter first.
+
 ## The smallest working session
 
 Drop into your project root and run:
@@ -191,7 +199,7 @@ assert_type(":int | :str | nil", kind(7))  # union of all case branches
 
 ```ruby
 greeting = "Hello, "                 # Constant<"Hello, ">
-name     = ARGV.first                # String?  (RBS-declared)
+name     = ARGV.first                # String?  (String or nil — RBS-declared)
 hello    = "#{greeting}#{name}!"     # literal-string carrier:
                                      # every interpolated part
                                      # is itself literal-string-

data/docs/handbook/02-everyday-types.md

@@ -42,7 +42,10 @@ this chapter is the carrier zoo.
 One note on notation before the zoo: angle brackets hold a
 concrete value or bound — `Constant<3>`, `int<0, max>` —
 while square brackets hold type parameters, exactly as in RBS
-— `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`.
+— `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`. A type
+parameter names the type of a *part*: `Hash[K, V]` is a Hash
+whose keys are type `K` and values type `V`, just as
+`Array[String]` is "an array of strings."
 
 ## Seeing carriers yourself — `rigor annotate`
 

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
@@ -142,9 +143,9 @@ shipped severities:
 
 | Profile | Behaviour |
 | --- | --- |
-| `lenient` | Most rules → `warning`; uncertain rules drop to `info`. CI-friendly for legacy code. |
-| `balanced` (default) | Most rules → `error`; `dump.type` → `info`. The shipped behaviour. |
-| `strict` | Everything → `error` including the `:warning` rules under `balanced`. Suitable for new projects with no legacy noise. |
+| `lenient` | Only proven rules stay `error` (`call.undefined-method`, `wrong-arity`, `assert.type-mismatch`); uncertain rules drop to `warning`, and several to `off`. For incremental adoption on legacy code. |
+| `balanced` (default) | Most rules → `error`; uncertain rules → `warning`; `dump.type` → `info`. The shipped behaviour. |
+| `strict` | Nearly every rule → `error`. The exceptions: `call.self-undefined-method` stays `off` (opt-in only), and `flow.unreachable-clause` is `warning` (pending its false-positive gate). Suitable for new projects with no legacy noise. |
 
 Set in `.rigor.yml`:
 

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
@@ -291,6 +347,7 @@ side.
 it for the project, then install the gem into that Ruby:
 
 ```sh
+asdf plugin add ruby        # once, if the ruby plugin isn't added yet
 asdf install ruby latest:4.0
 asdf local ruby latest:4.0
 gem install rigortype
@@ -299,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
 
@@ -315,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
@@ -279,6 +290,10 @@ inferring".
 rigor coverage [paths]
 ```
 
+`paths` are files or directories; when omitted, Rigor uses the
+`paths:` list from the configuration file (default `lib`), the same
+as [`rigor check`](#rigor-check).
+
 `--format=text|json` selects the output format and
 `--config=PATH` overrides config discovery. `--threshold=RATIO`
 exits `1` when the precision ratio falls below `RATIO`
@@ -295,7 +310,13 @@ ranked "add a type here" list (the methods most often called on
 an untyped receiver), then the least-protected files;
 `--threshold` and `--format=json` work the same. It is a sound
 upper bound on real protection — a concrete receiver is necessary
-but not sufficient for a diagnostic to fire.
+but not sufficient for a diagnostic to fire. `--workers=N`
+fork-parallelizes the protection scan (both the parameter-inference
+pre-pass and the per-file scan) with output byte-identical to a
+sequential run; it resolves the worker count the same way `check`
+does — `--workers` › `RIGOR_RACTOR_WORKERS` ›
+[`parallel.workers:`](03-configuration.md) › `0` (sequential
+default).
 
 Adding `--mutation` (with `--protection`) switches to the
 **effectiveness** tier: it measures whether Rigor *does* catch a
@@ -390,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]
 ```
@@ -403,7 +429,7 @@ catalogue** ([ADR-37](../adr/37-plugin-interface-segregation.md)):
 a focused, machine-readable map of what each loaded plugin
 contributes — the AST node types its `node_rule`s match, the
 receiver classes its `dynamic_return`s gate on, the methods its
-`narrowing_facts`s narrow, and the facts it `produces` /
+`narrowing_facts` hooks narrow, and the facts it `produces` /
 `consumes`. Combine with `--format=json` for tooling (an AI
 agent can enumerate every plugin's behaviour without reading a
 line of plugin source). The same narrow surfaces also appear in
@@ -464,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`
 
@@ -508,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
@@ -533,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`
 
@@ -557,8 +589,7 @@ rigor doctor [--config PATH] [--format text|json]
 Runs a scoped analysis and audits:
 
 - **Configuration audit** — unresolved `signature_paths:`, unknown
-  `libraries:`, inert `disable:` / `severity_overrides:` tokens
-  ({ConfigAudit}).
+  `libraries:`, inert `disable:` / `severity_overrides:` tokens.
 - **RBS environment health** — whether the RBS class universe built
   successfully (`0` classes means a broken setup).
 - **Plugin load errors** — whether every configured plugin loaded.
@@ -566,9 +597,21 @@ 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
+routed hint (e.g. "Run `rigor baseline regenerate`"). JSON output
 is a stable contract:
 
 ```json
@@ -585,7 +628,7 @@ Exits `1` when any check fails, `0` when all pass.
 ## `rigor upgrade`
 
 Migration command skeleton ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
-WD7).  The real body lands when a concrete backwards-compatibility
+WD7). The real body lands when a concrete backwards-compatibility
 break gives it a target (e.g. re-running `baseline regenerate`
 against a strengthened default profile, surfacing renamed
 suppression ids, reporting `bleeding_edge:` graduations).
@@ -595,7 +638,7 @@ rigor upgrade
 ```
 
 Until then it prints the current version and notes that upgrade is
-queued.  Exits `0`.
+queued. Exits `0`.
 
 ## Environment variables
 
@@ -609,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