rigortype 0.2.9 → 0.3.1

data/docs/handbook/README.md

@@ -56,9 +56,11 @@ up the flag, key, or command that *acts* on it.
    how to nudge it through `.rbs` files and `%a{rigor:v1:…}`
    directives.
 8. [**Understanding errors**](08-understanding-errors.md) —
-   the rule catalogue (`call.undefined-method`,
-   `call.argument-type-mismatch`, `flow.always-raises`, …),
-   severity profiles, and `# rigor:disable` suppression.
+   reading a diagnostic: what each rule family claims, why one
+   fires when you did not expect it (and stays silent when you
+   did), and which layer to reach for when you want it quieter.
+   The catalogue itself is
+   [manual — Diagnostics](../manual/04-diagnostics.md).
 9. [**Plugins**](09-plugins.md) — when to author one,
    pointer to the [examples/](../../examples/README.md)
    landing page.

data/docs/handbook/appendix-liskov.md

@@ -571,8 +571,10 @@ model"](appendix-type-theory.md#what-rigor-does-not-model) records.
   authoring the declared contracts `def.return-type-mismatch` checks
   against.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md) for
-  the `def.return-type-mismatch` / `call.argument-type-mismatch`
-  rules and severity profiles.
+  what the `def.*` family claims, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  `def.return-type-mismatch` / `call.argument-type-mismatch`
+  entries and the severity profiles.
 
 If you want to compare against another *tool* rather than the
 *principle*, the sibling appendices cover

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/handbook/appendix-phpstan.md

@@ -72,8 +72,10 @@ in another tab, almost every advanced refinement transfers.
 ## The `@phpstan-assert` family
 
 PHPStan's assertion-narrowing PHPDoc tags map directly onto
-Rigor's `RBS::Extended` directive grammar. Chapter 7 covers
-the table in depth; here it is again for reference:
+Rigor's `RBS::Extended` directive grammar. This is the mapping;
+[Chapter 7](07-rbs-and-extended.md) works the Rigor side
+through examples, and the directive reference itself is
+[manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md):
 
 | PHPStan PHPDoc | Rigor RBS::Extended | Effect |
 | --- | --- | --- |
@@ -149,7 +151,8 @@ Rigor has two baseline mechanisms: a **managed** baseline
 the next `rigor check` via the `baseline:` config key — the
 closest match to PHPStan's `--baseline`), and a **lightweight**
 ad-hoc snapshot (`rigor diff` over a `--format=json` dump).
-Chapter 8 has the walkthrough.
+[Manual — Baselines](../manual/06-baseline.md) walks through
+both.
 
 The `includes:` semantics also match PHPStan's: declaration
 order, later overrides earlier, the current file's keys win
@@ -322,11 +325,15 @@ You probably do not need to read the rest of this appendix
 section sequentially. Three useful pointers:
 
 - [Chapter 7 — RBS and `RBS::Extended`](07-rbs-and-extended.md)
-  has the full directive grammar, including the PHPStan-mapping
-  table that this page summarises.
+  works the directive grammar through examples; the reference
+  table is
+  [manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md).
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  covers the rule catalogue, severity profiles, baseline
-  diffing — every PHPStan onboarding analogue.
+  explains how to read a diagnostic and which knob to reach
+  for; the catalogue, severity profiles and baselines — every
+  PHPStan onboarding analogue — are
+  [manual — Diagnostics](../manual/04-diagnostics.md) and
+  [manual — Baselines](../manual/06-baseline.md).
 - [Chapter 9 — Plugins](09-plugins.md) for the
   Type-Specifying / Dynamic-Return analogues.
 

data/docs/handbook/appendix-steep.md

@@ -321,8 +321,10 @@ section sequentially. Three useful pointers:
   if you want to see how the directive grammar layers on top
   of the RBS you already write.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue, severity profiles, and baseline
-  diffing — the analogue to Steep's diagnostic config.
+  for how to read a diagnostic, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue and severity profiles — the analogue to
+  Steep's diagnostic config.
 - [`docs/notes/20260503-steep-cross-check-triage.md`](../notes/20260503-steep-cross-check-triage.md)
   for a worked side-by-side run of Steep and Rigor on the
   same project (the project itself).

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

@@ -1651,7 +1651,9 @@ practical companion:
   for the directive grammar that lets you teach Rigor about a
   custom predicate.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue (the user-visible end of the trinary
+  for how a diagnostic reads, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue (the user-visible end of the trinary
   certainty).
 
 If you want to compare against another *tool* rather than the

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]
 ```
@@ -463,6 +479,7 @@ so a skill can never be shadowed by a verb.
 
 ```sh
 rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
+rigor skill describe [--deep]
 ```
 
 | Form | Purpose |
@@ -472,10 +489,38 @@ rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 | `--full <name>` | Print the `SKILL.md` body **followed by every `references/*.md` inline** — the complete, version-current procedure in one call. This is what a skill's "First: load the version-current copy" directive points at, so a copy vendored into a project (e.g. via `npx skills add`) re-fetches its current steps from the installed gem instead of following a frozen copy. |
 | `--path <name>` | Print the single-line absolute `SKILL.md` path, suitable as input to a file-reading tool. |
 | `--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. |
+| `describe --deep` | The same report, except it **runs `rigor check` first** and routes the headline recommendation on the result. Opt-in, because it costs a full analysis and writes `.rigor/cache` — the un-flagged form stays presence-only and side-effect-free. |
+
+### `describe --deep`
+
+By default the recommendation comes from a presence-only probe, so it can
+tell that a project *has* a config but not whether the analysis is
+healthy. `--deep` runs the check for you and lets the result pick the
+headline, using the same routing the `## For the agent` section already
+teaches:
+
+| Deep check result | Headline becomes |
+| --- | --- |
+| RBS environment built to 0 classes, or a `configuration-error` diagnostic | `rigor-doctor` — the analysis is hollow until the setup is fixed. |
+| Call sites resolving to the project's own definitions (reopened core / gem classes), as at least a third of the errors | `rigor-monkeypatch-resolve` — list them in `pre_eval:` and they clear wholesale. |
+| Any remaining error diagnostics | `rigor-baseline-reduce`. Proven monkey-patch sites below that share are still reported here, so the finding survives even when the headline stays on the larger problem. |
+| Clean, or the project has no config yet | Unchanged — the presence-only recommendation stands. |
+
+If the check **cannot run at all** (no config, an unloadable plugin, a
+malformed config) `--deep` does not fail and does not pretend the project
+is clean: it reports what went wrong, falls back to the presence-only
+recommendation, and points you at `rigor doctor`. It deliberately does
+*not* route on weaker signals — "framework calls typing as `Dynamic`" is
+still a judgement call left to you and your agent.
+
+```sh
+rigor skill describe --deep   # also: rigor describe --deep
+```
 
 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`
 
@@ -494,6 +539,10 @@ It reports a presence-only project-state probe (does a `.rigor.yml`,
 recommended next skill. It is read-only and side-effect-free — it never
 runs `rigor check`. Identical output to `rigor skill describe`.
 
+`rigor describe --deep` forwards to
+[`rigor skill describe --deep`](#rigor-skill), which opts into running the
+check first — slow, and it writes the cache.
+
 ## `rigor docs`
 
 Print the documentation bundled inside the `rigortype` gem
@@ -518,8 +567,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 +593,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 +629,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 +684,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