rigortype 0.3.8 → 0.4.0

data/sig/rigor/source.rbs

@@ -4,11 +4,11 @@ module Rigor
       class OutOfRangeError < StandardError
       end
 
-      def self.at_position: (source: String, root: untyped, line: Integer, column: Integer) -> untyped?
-      def self.at_offset: (root: untyped, offset: Integer) -> untyped?
+      def self.at_position: (source: String, root: untyped, line: Integer, column: Integer) -> ::Prism::Node?
+      def self.at_offset: (root: untyped, offset: Integer) -> ::Prism::Node?
       def initialize: (source: String, root: untyped) -> void
-      def at_position: (line: Integer, column: Integer) -> untyped?
-      def at_offset: (Integer offset) -> untyped?
+      def at_position: (line: Integer, column: Integer) -> ::Prism::Node?
+      def at_offset: (Integer offset) -> ::Prism::Node?
     end
 
     module Literals

data/sig/rigor/testing.rbs

@@ -1,9 +1,15 @@
 module Rigor
   module Testing
-    def self?.dump_type: (untyped value) -> untyped
-    def self?.assert_type: (String expected, untyped value) -> untyped
+    # Both helpers return `value` unchanged (lib/rigor/testing.rb); the type variable carries the
+    # argument's type through so a probed expression stays typed downstream instead of widening to
+    # `Dynamic[top]`. `A` binds only on a dispatch that carries a scope — a `Rigor.` /
+    # `Rigor::Testing.` receiver, or an including class that is RBS-known. A bare `dump_type(x)` after
+    # `include Rigor::Testing` in a discovered-only class still reaches the ancestor fallback without a
+    # scope and answers `Dynamic[top]`, as it did under `-> untyped` (#303 follow-up).
+    def self?.dump_type: [A] (A value) -> A
+    def self?.assert_type: [A] (String expected, A value) -> A
   end
 
-  def self.dump_type: (untyped value) -> untyped
-  def self.assert_type: (String expected, untyped value) -> untyped
+  def self.dump_type: [A] (A value) -> A
+  def self.assert_type: [A] (String expected, A value) -> A
 end

data/sig/rigor/type.rbs

@@ -1,6 +1,6 @@
 module Rigor
   module Type
-    type t = Top | Bot | Dynamic | Constant | IntegerRange | Nominal | Singleton | Union | Difference | Refined | Intersection | Tuple | HashShape | DataClass | DataInstance | StructClass | StructInstance | BoundMethod | Result | Maybe | App
+    type t = Top | Bot | Dynamic | Constant | IntegerRange | FloatRange | Nominal | Singleton | Union | Difference | Refined | Intersection | Tuple | HashShape | DataClass | DataInstance | StructClass | StructInstance | BoundMethod | Result | Maybe | App
 
     type accepts_mode = :strict | :gradual | :loose
 
@@ -115,7 +115,30 @@ module Rigor
       def inspect: () -> String
     end
 
+    class FloatRange
+      ALIAS_NAMES: Hash[[Float, Float], String]
+      attr_reader min: Float
+      attr_reader max: Float
+      def initialize: (Float min, Float max, ?exclude_end: bool) -> void
+      def exclude_end?: () -> bool
+      def canonical_max: () -> Float
+      def universal?: () -> bool
+      def covers?: (untyped value) -> bool
+      def describe: (?Symbol verbosity) -> String
+      def generic_description: () -> String
+      def erase_to_rbs: () -> "Float"
+      def top: () -> Trinary
+      def bot: () -> Trinary
+      def dynamic: () -> Trinary
+      def accepts: (Type::t other, ?mode: accepts_mode) -> AcceptsResult
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+
     class Nominal
+      EMPTY_TYPE_ARGS: Array[Type::t]
       attr_reader class_name: String
       attr_reader type_args: Array[Type::t]
       def initialize: (String class_name, ?Array[Type::t] type_args) -> void
@@ -406,8 +429,14 @@ module Rigor
       attr_reader trinary: Trinary
       attr_reader mode: accepts_mode
       attr_reader reasons: Array[String]
+      # sig-gen gap: #1155 — the memoized `||=` return is an honest union with an
+      #   untyped arm (the slot read cannot prove the memoized value), so sig-gen
+      #   skips it (sig.skipped.untyped-return); the runtime result is always
+      #   AcceptsResult and the row is hand-written.
       def self.yes: (?mode: accepts_mode, ?reasons: (Array[String] | String)?) -> AcceptsResult
+      # sig-gen gap: #1155 — same memoized `||=` untyped-return gap as `self.yes`.
       def self.no: (?mode: accepts_mode, ?reasons: (Array[String] | String)?) -> AcceptsResult
+      # sig-gen gap: #1155 — same memoized `||=` untyped-return gap as `self.yes`.
       def self.maybe: (?mode: accepts_mode, ?reasons: (Array[String] | String)?) -> AcceptsResult
       def initialize: (Trinary trinary, ?mode: accepts_mode, ?reasons: (Array[String] | String)?) -> void
       def yes?: () -> bool
@@ -460,6 +489,9 @@ module Rigor
       def self?.negative_int: () -> IntegerRange
       def self?.non_positive_int: () -> IntegerRange
       def self?.universal_int: () -> IntegerRange
+      def self?.float_range: (Float min, Float max, ?exclude_end: bool) -> FloatRange
+      def self?.non_nan_float: () -> FloatRange
+      def self?.finite_float: () -> FloatRange
       def self?.tuple_of: (*Type::t elements) -> Tuple
       def self?.hash_shape_of: (?Hash[untyped, Type::t]? pairs, **untyped options) -> HashShape
       def self?.data_class_of: (members: Array[Symbol], ?class_name: String?) -> DataClass

data/sig/rigor.rbs

@@ -24,6 +24,7 @@ module Rigor
 
   class CLI
     EXIT_USAGE: Integer
+    EXIT_INTERNAL_ERROR: Integer
 
     def self.start: (?Array[String] argv, ?out: untyped, ?err: untyped) -> Integer
 
@@ -123,32 +124,50 @@ module Rigor
       attr_reader buffer: untyped
       attr_reader file_dependencies: Hash[String, untyped]
       attr_reader analyzed_files: Array[String]
-      def initialize: (configuration: Configuration, ?explain: bool, ?cache_store: untyped, ?plugin_requirer: untyped, ?workers: Integer, ?collect_stats: bool, ?buffer: untyped, ?prebuilt: untyped, ?environment: untyped, ?record_dependencies: bool, ?analyze_only: untyped) -> void
+      def initialize: (configuration: Configuration, ?explain: bool, ?cache_store: untyped, ?plugin_requirer: untyped, ?workers: Integer, ?collect_stats: bool, ?buffer: untyped, ?prebuilt: Analysis::ProjectScan?, ?environment: untyped, ?record_dependencies: bool, ?analyze_only: untyped) -> void
       def run: (?Array[String] paths) -> Result
       def run_source: (source: String, ?path: String) -> Result
       def analysis_file_set: (?Array[String] paths) -> Array[String]
       def file_dependents: () -> Hash[String, untyped]
-      def prepare_project_scan: (?paths: Array[String]) -> untyped
+      def prepare_project_scan: (?paths: Array[String]) -> Analysis::ProjectScan
       # ADR-103 — the propagated effect graph and the merged per-file collections behind it. A report
-      # surface: never a diagnostic, empty when the configuration carries no `effects:` block. Typed
-      # `untyped` for the same reason `cache_store` is — `Rigor::Effects` is not sig-covered yet
-      # (`spec/rigor/public_api_drift_spec.rb`), and a named reference would raise `RBS::UnknownTypeName`.
-      def effect_table: () -> untyped
-      def effect_collection: () -> untyped
-      # #381 — `{ "Class#m" => [path] }`, which the snapshot's `reach:` globs match against. Same
-      # `untyped` reasoning as its two siblings above.
-      def effect_sources: () -> untyped
-      # #387 — the loaded plugins' compiled effect contributions, read by `rigor effects` so the snapshot's
-      # vocabulary is the one the collection window scanned under. Same `untyped` reasoning again.
-      def effect_plugin_facts: () -> untyped
+      # surface: never a diagnostic, empty when the configuration carries no `effects:` block.
+      def effect_table: () -> Effects::EffectTable
+      def effect_collection: () -> Effects::FileCollection
+      # ADR-103 WD9 (#391): the resolved envelope index `rigor sig-gen`'s annotation emission
+      # consults, built on demand so a warm-cache run still serves the same strata.
+      def effect_envelopes: () -> Effects::EnvelopeIndex
+      # #381 — `{ "Class#m" => [path] }`, which the snapshot's `reach:` globs match against.
+      def effect_sources: () -> Hash[String, Array[String]]
+      # #387 — the loaded plugins' compiled effect contributions, read by `rigor effects` so the
+      # snapshot's vocabulary is the one the collection window scanned under.
+      def effect_plugin_facts: () -> Effects::PluginFacts
+      # The run's as-written superclass table — what `effect.liskov-widened` reads.
+      def effect_ancestry: () -> Hash[String, String]
+      # `{ "lib/a.rb" => FileCollection, … }` — the per-file collections the caches persist (#382).
+      def effect_collections_by_path: () -> Hash[String, Effects::FileCollection]
+      # Issue #382 — adopt persisted collections as this run's own (the warm-hit half of the
+      # whole-run effects slot).
+      def adopt_effect_collections: (Hash[String, Effects::FileCollection] collections,
+                                     ?table: Effects::EffectTable?) -> void
+      # #482 — adopt the served run's small summary entry, collections left behind a loader.
+      def adopt_effect_summary: (table: Effects::EffectTable, sources: Hash[String, Array[String]],
+                                 ancestry: Hash[String, String], collections_loader: untyped) -> void
+      # Whether this run's effect collections came from the whole-run effects slot (#382).
+      def effects_served_from_cache?: () -> bool
       # The incremental session's read surface (ADR-46 / ADR-67 / ADR-103) — `IncrementalSession`
-      # drives a live Runner through these between rechecks. Typed `untyped` like the cache / effects
-      # readers above until their namespaces are sig-covered.
-      def return_summaries: () -> untyped
-      def param_inferred_types: () -> untyped
-      def effect_collections_by_path: () -> untyped
-      def collect_param_inference_table: (untyped files) -> untyped
-      def evaluate_return_types: (untyped paths, untyped specs) -> untyped
+      # drives a live Runner through these between rechecks.
+      # sig-gen gap: #1008 — `result` is populated by `collect_return_summaries` mutating it by
+      # reference from a sibling method; sig-gen folds only the `{}` seed and the empty-memo early
+      # return, so it proposes the seed shape instead of the honest, usually-non-empty contract.
+      # Keys are `[path, "Class#method"]` pairs; values are `{ keys:, returns:, effects: }` bundles.
+      def return_summaries: () -> Hash[[String, String], Hash[Symbol, untyped]]
+      # ADR-67 — `[class_name, method_name, kind] => { param_name => Type }`.
+      def param_inferred_types: () -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+      def collect_param_inference_table: (untyped files) -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+      # `{ class_name:, method_name:, singleton: }` spec triple => the per-key return descriptors
+      # (`describe(:short)` strings; nil for a missing/bodyless def).
+      def evaluate_return_types: (untyped paths, untyped specs) -> Hash[[String, Symbol, bool], Array[String?]]
     end
   end
 

data/skills/rigor-ask/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-ask
-description: |
-  Answer any question about Rigor by investigating, not from memory — Rigor is niche and version-specific, so run its tools and read its bundled docs, then answer from what you saw. Use `rigor docs` (handbook + manual, offline and version-matched) and `rigor explain <rule>`; for the user's own code, `rigor check` / `annotate` / `type-of`. Covers: why a line is flagged or whether it's a false positive; the type model (narrowing, refinements, `Dynamic`, RBS); config keys, flags, baselines; comparisons to Sorbet, Steep, mypy, PHPStan; whether Rigor handles Rails, RSpec, or a given gem; how to type a method; "what is Rigor / why use it / is it right for us?". Trigger on any Rigor question seeking understanding — even casual, comparative, or grumbling. Skip only when it's purely "set it up / fix / reduce it for me" (use rigor-next-steps).
+description: >-
+  Answer a question about Rigor from version-matched bundled docs and tool output. Use when the user
+  asks why a diagnostic fired, how a type/config/flag works, or how Rigor compares with another tool; not
+  when they ask you to set up, fix, or reduce something.
 license: MPL-2.0
 metadata:
   version: 0.2.0
@@ -30,11 +32,12 @@ Two things make that easy, and you have both offline:
   `type-of` / `triage` / `coverage` answer from what Rigor inferred. A
   concrete inferred type beats any abstract explanation.
 
-This is the user's shortcut: they only ever need to remember two skills —
-**`rigor-next-steps`** ("what should we do next?") and **`rigor-ask`**
-("answer this about Rigor"). They ask in plain language; *you* turn it
-into the right lookup or analysis so they never have to remember the
-command.
+This is the user's shortcut: they only ever need to remember three
+skills — **`rigor-next-steps`** ("what should we do next?"),
+**`rigor-ask`** ("answer this about Rigor"), and **`rigor-type-oracle`**
+("before you write a type, ask Rigor"). They ask in plain language; *you*
+turn it into the right lookup or analysis so they never have to remember
+the command.
 
 ## Prefer the live map over this skill's tables
 
@@ -50,8 +53,9 @@ rigor --help                   # the live command + flag list
 rigor skill --full rigor-ask   # the current version of this skill itself
 ```
 
-Never cite a page, flag, or rule id you have not just seen in one of these
-— that is this skill's whole discipline. If `rigor` is not installed, you
+Cite a page, flag, or rule id only after you have seen it in this
+install — `rigor docs`, `rigor --help`, `rigor explain`, or the gem's own
+files (see "If the docs don't cover it"). If `rigor` is not installed, you
 can still answer high-level "what is Rigor?" questions from the web
 <https://rigor.typedduck.fail/llms.txt>, but for anything version-specific
 install it first (see `rigor-next-steps`).
@@ -79,7 +83,7 @@ Everything here is read-only and needs no network.
 | `rigor triage` | Cluster the project's diagnostics by rule / receiver / method — for "what's the shape of my errors?". |
 | `rigor coverage [--protection]` | Type / type-protection coverage — for "how well-typed is this?" and "where are the holes?". |
 | `rigor plugins` | Which plugins are installed and enabled *here* — the honest answer to "does Rigor support <gem/framework>?". |
-| `rigor sig-gen <path>` | Generate RBS for code — for "how do I type this?". Offer it and show the result; this project prefers sig-gen over hand-written RBS. |
+| `rigor sig-gen <path>` | Generate RBS for code — for "how do I type this?". Offer it and show the result — generated RBS is derived; hand-written RBS is a guess until `rigor check` agrees (see `rigor-type-oracle`). |
 
 ## Where the answer lives
 
@@ -125,8 +129,9 @@ A good hand-off is two or three sentences of orientation plus the pointer:
 - CI → **`rigor-ci-setup`** · editor → **`rigor-editor-setup`** · MCP agent → **`rigor-mcp-setup`**
 - baseline reduction → **`rigor-baseline-reduce`** · coverage holes → **`rigor-protection-uplift`**
 - a missing gem/DSL → **`rigor-plugin-author`** · monkey-patch clusters → **`rigor-monkeypatch-resolve`**
+- about to *write* a type (RBS, `#:`, a Sorbet `sig`, a YARD tag, a doc sentence) → **`rigor-type-oracle`**
 
-When in doubt, give less and point — it respects the user's "two skills
+When in doubt, give less and point — it respects the user's "three skills
 to remember" promise and keeps each answer to the part only `rigor-ask`
 can give.
 

data/skills/rigor-baseline-reduce/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-baseline-reduce
-description: |
-  Work a Rigor project's `.rigor-baseline.yml` down rule by rule: prioritise with `rigor triage`, sample call sites, classify each as real bug / stylistic-safe / false positive, then fix, `# rigor:disable`, or open a Rigor issue — and regenerate the baseline. Triggers: "reduce the rigor baseline", "fix some baseline diagnostics", "what rigor issue should I fix next?". NOT for first-time setup (use rigor-project-init) or authoring a plugin (use rigor-plugin-author).
+description: >-
+  Reduce an existing `.rigor-baseline.yml` rule by rule by triaging sites, fixing or intentionally
+  suppressing them, and regenerating the baseline. Use for baseline diagnostics already acknowledged by a
+  project; not for first-time setup or plugin authoring.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -37,10 +39,6 @@ header names). If `rigor` is not on `PATH`, this task needs it: run
 
 ## Phase 0 — When to use this skill
 
-Trigger when the user says "reduce the rigor baseline", "fix some
-baseline diagnostics", "what should I fix next in rigor?", or asks to
-work down the diagnostics a previous onboarding parenthesised.
-
 **Precondition: the project is in acknowledge mode.** This skill
 operates on a `.rigor-baseline.yml` that `.rigor.yml` /
 `.rigor.dist.yml` declares via `baseline:`. A strict-mode project

data/skills/rigor-ci-setup/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-ci-setup
-description: |
-  Wire Rigor type-checking into a project's CI pipeline: run it in its own isolated Ruby-4.0 job and surface diagnostics inline on the pull / merge request via a CI-native output format (SARIF, GitHub Actions annotations, GitLab Code Quality, Checkstyle, JUnit) or through reviewdog. Triggers: "add Rigor to CI", "run rigor in GitHub Actions / GitLab CI", "show Rigor errors on the PR", "set up reviewdog for rigor". NOT for first-time project configuration (use rigor-project-init to create `.rigor.yml` first) or reducing a baseline (use rigor-baseline-reduce).
+description: >-
+  Set up Rigor in a project's CI and surface diagnostics on pull or merge requests. Use when adding or
+  changing GitHub Actions, GitLab CI, SARIF, or reviewdog wiring; not for first-time Rigor configuration
+  or baseline reduction.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -31,7 +33,6 @@ Rigor is installed:
 ```sh
 rigor skill --full rigor-ci-setup   # this skill's current workflow, in one call
 rigor docs ci                       # the manual's CI chapter — the actual templates
-rigor docs --list manual | grep ci-templates   # ready-to-copy template files
 ```
 
 If you already loaded this skill *via* `rigor skill` you have the current
@@ -61,7 +62,7 @@ these markers from the project root and let them drive the platform choice:
 | `bitbucket-pipelines.yml` / `azure-pipelines.yml` / `.drone.yml` | that platform (generic recipe) |
 | none of the above | no CI yet — **ask** the user which platform they use |
 
-Concretely (the agent has file tools — use them):
+Concretely:
 
 - List `.github/workflows/*.yml` and `.gitlab-ci.yml`. **If
   `.github/workflows/rigor.yml` already exists, read it** — this is an
@@ -108,10 +109,8 @@ this is the *decision*:
 ## Phase 2 — Apply the matching template
 
 Take the template for your (platform, surface) choice from `rigor docs ci`
-— or copy a ready file listed by `rigor docs --list manual | grep
-ci-templates` (GitHub annotations / SARIF / reviewdog, and GitLab). Copy it
-in, adjust nothing but the trigger unless asked, and pin the version next
-(Phase 3).
+(GitHub annotations / SARIF / reviewdog, and GitLab). Copy it in, adjust
+nothing but the trigger unless asked, and pin the version next (Phase 3).
 
 **reviewdog is platform-specific.** It reads Rigor's `checkstyle`
 (preferred — light, no code scanning) or `sarif`, but the `-reporter` must
@@ -142,14 +141,11 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
 - **Determinism.** Add `--no-cache` in CI if you want each run independent
   of any persisted `.rigor/cache`.
 - **Cache persistence (opposite trade).** When the Rigor job's runtime
-  matters, persist `.rigor/cache` with the CI's cache facility. Current
-  Rigor detects CI and validates the restored cache by content hash
-  automatically (`cache.validation: auto`); on versions before the
-  `auto` default, **also set `RIGOR_STRICT_VALIDATION=1` on the job** —
-  without it a fresh checkout's regenerated stat tuples make the plugin
-  watch-glob cache slots read as stale on every run. A self-hosted
-  runner that reuses its workspace opts back into the faster stat check
-  with `cache.validation: stat`. Snippets: `rigor docs ci`
+  matters, persist `.rigor/cache` with the CI's cache facility. Rigor
+  detects CI and validates the restored cache by content hash
+  automatically (`cache.validation: auto`). A self-hosted runner that
+  reuses its workspace opts back into the faster stat check with
+  `cache.validation: stat`. Snippets: `rigor docs ci`
   § "Persisting the analysis cache across runs".
 
 ## Verify
@@ -165,12 +161,12 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
 
 - Manual: `rigor`'s CI chapter — the authoritative templates, severity
   mapping, and pinning recipe, **offline and version-matched** with
-  `rigor docs ci` (ready files: `rigor docs --list manual | grep
-  ci-templates`). Web fallback, before Rigor is installed:
-  <https://github.com/rigortype/rigor/blob/master/docs/manual/11-ci.md>.
-- [ADR-51](../../docs/adr/51-ci-diagnostic-output-formats.md)
+  `rigor docs ci`. Web fallback, before Rigor is installed:
+  <https://github.com/rigortype/rigor/blob/master/docs/manual/11-ci.md>
+  (ready-to-copy files in `docs/manual/ci-templates/` beside it).
+- [ADR-51](https://github.com/rigortype/rigor/blob/master/docs/adr/51-ci-diagnostic-output-formats.md)
   — the output-format surface (the severity / identifier contract).
-- [ADR-27](../../docs/adr/27-tool-distribution-model.md)
+- [ADR-27](https://github.com/rigortype/rigor/blob/master/docs/adr/27-tool-distribution-model.md)
   — why Rigor installs standalone and runs in its own job.
 - [reviewdog](https://github.com/reviewdog/reviewdog) /
   [action-setup](https://github.com/reviewdog/action-setup).

data/skills/rigor-doctor/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-doctor
-description: |
-  Validate that a project's Rigor setup is actually healthy — config parses with no silently-inert values, every configured plugin loads, the baseline is not stale, and the bundled paths resolve — by running Rigor's existing validators and interpreting them. Triggers: "is my Rigor setup correct?", "check my rigor config", "rigor diagnostics look wrong / suspicious", "validate rigor setup", "why is rigor reporting nothing / everything?". NOT for first-time setup (use rigor-project-init) or for working real diagnostics down (use rigor-baseline-reduce).
+description: >-
+  Validate that a project's Rigor configuration, plugins, paths, and baseline are actually healthy. Use
+  when diagnostics are suspicious or setup behavior is wrong; not for first-time onboarding or reducing
+  ordinary diagnostics.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -11,12 +13,13 @@ metadata:
 # Rigor Doctor
 
 `rigor skill describe` reports what *exists* (presence checks). This skill
-goes a level deeper: it *runs* Rigor's own validators to confirm the setup
-is actually working — the difference between "a `.rigor.yml` is present"
-and "it parses, loads its plugins, and analyses the right files." Reach for
-it when the diagnostics look wrong (suspiciously zero, or suspiciously
-many) or after editing the config. It needs no special command — it
-orchestrates checks Rigor already ships and interprets the results.
+goes a level deeper: `rigor doctor` *runs* Rigor's own setup validators
+(config audit, RBS environment, plugin loading, baseline drift, plugin
+gaps, install layout) and this skill interprets the result — the
+difference between "a `.rigor.yml` is present" and "it parses, loads its
+plugins, and analyses the right files." Reach for it when the diagnostics
+look wrong (suspiciously zero, or suspiciously many) or after editing the
+config.
 
 ## First: load the version-current copy
 
@@ -44,25 +47,24 @@ header names). If `rigor` is not on `PATH`, this task needs it: run
 
 ## What it validates
 
-Four validators, each a check Rigor already ships. The exact commands and
-how to read each output live in the version-current
+`rigor doctor` runs the setup checks in one pass (`--format json` gives
+each finding's `checks[].id` and `status`) and exits non-zero when any
+check fails. It does not check whether the analysis sees the right
+files; that is a separate look at `stats.target_files` in
+`rigor check --format json`. What each check id means and how to act on
+it live in the version-current
 [`references/01-checks.md`](references/01-checks.md) (loaded per the
-directive above):
-
-1. **Config resolves with nothing silently inert** — no `config_warnings`.
-2. **Every configured plugin loads** — `rigor plugins --strict` is clean.
-3. **The baseline is not stale** (if one exists) — no large drift.
-4. **The analysis is actually seeing your code** — the source-file count
-   matches the project.
+directive above).
 
 ## Interpreting the result
 
-- **All clean** → the setup is healthy; any diagnostics are about the
-  code, not the configuration. Move on to `rigor-baseline-reduce` or
+- **All clean** (no `fail` or `warn` finding, and the file count matches
+  the project) → the setup is healthy; any diagnostics are about the code,
+  not the configuration. Move on to `rigor-baseline-reduce` or
   `rigor-protection-uplift`.
-- **A `config_warning` or a plugin failure** → that is the real problem;
-  fixing it usually clears a whole cluster of confusing downstream
-  diagnostics at once.
+- **A `config_audit`, `rbs_environment`, or `plugins` failure** → that is
+  the real problem; fixing it usually clears a whole cluster of confusing
+  downstream diagnostics at once.
 
 For deeper symptoms (hover shows `untyped` everywhere, completion empty,
 LSP silent) read the manual's troubleshooting chapter — offline and

data/skills/rigor-doctor/references/01-checks.md

@@ -1,52 +1,116 @@
-# 01 — The four checks
+# 01 — The checks
 
-Each check runs a validator Rigor already ships and interprets its
-output. Run them in order; the first failure is usually the root cause of
-a cluster of confusing downstream diagnostics.
-
-## 1. Config resolves with nothing silently inert
+## Run `rigor doctor`
 
 ```sh
-rigor check --format json   # read the `config_warnings` array
+rigor doctor                 # human-readable: [FAIL] / [WARN] / [PASS] lines
+rigor doctor --format json   # machine-readable
 ```
 
-`rigor check` audits the config and emits `config_warnings` for the typo
-class whose only symptom is a confusing downstream error: a
-`signature_paths:` that is missing / not a directory / holds no `.rbs`
-(which would turn every covered call into a false `call.undefined-method`
-at `evidence_tier: high`), a `libraries:` name RBS does not recognise, a
-`disable:` / `severity_overrides:` id naming no real rule, or a missing
-`bundler` / `rbs_collection` path. **Each warning here is a real
-misconfiguration — fix it.** None appearing is the healthy state.
-
-## 2. Every configured plugin loads
+It runs one scoped analysis, audits the config, loads the plugins, and
+checks baseline drift in a single pass, then prints a finding per
+problem with a hint. The JSON shape:
 
-```sh
-rigor plugins --strict
+```json
+{ "status": "issues_found",
+  "checks": [ { "id": "plugins", "status": "fail",
+                "message": "Plugin load errors: 1",
+                "hint": "Run `rigor plugins --strict` for the full per-plugin report." } ] }
 ```
 
-Reports the activation status of each plugin in `plugins:`; `--strict`
-exits non-zero on any failure. A failure is usually a misspelled id or a
+- Top-level `status` is `issues_found` when any check has `status: "fail"`,
+  otherwise `clean` — a run with only `warn` findings still reads `clean`,
+  so read the `checks` array too.
+- `checks[].status` is `fail`, `warn`, or `pass`. A check with nothing to
+  report is usually **absent**, not `pass`; only `rbs_environment` reports
+  a `pass` line.
+- The command exits non-zero when any check fails.
+
+Fix `fail` findings first, in the order below: an early failure is usually
+the root cause of a cluster of confusing downstream diagnostics.
+
+## The check ids
+
+### `config_audit` — config resolves with nothing silently inert
+
+`fail` with a count of configuration warnings. Doctor gives only the
+count; the individual warnings are in `rigor check --format json` under
+`config_warnings`. They cover the typo class whose only symptom is a
+confusing downstream error: a `signature_paths:` that is missing / not a
+directory / holds no `.rbs` (which would turn every covered call into a
+false `call.undefined-method` at `evidence_tier: high`), a `libraries:`
+name RBS does not recognise, a `disable:` / `severity_overrides:` id
+naming no real rule, or a missing `bundler` / `rbs_collection` path.
+**Each warning is a real misconfiguration — fix it.**
+
+### `rbs_environment` — the type universe loaded
+
+- `fail` — the RBS environment is empty (zero classes). It failed to build
+  or loaded no signatures: look for duplicate declarations across
+  `signature_paths:`, or run `rbs collection install` for gem signatures.
+- `warn` — degraded: one or more `signature_paths:` files did not parse
+  and were skipped. The run is quieter, not cleaner — the types those
+  files declare are gone. Run `rbs validate` on the `sig/` set and fix
+  the parse error.
+- `pass` — healthy, with the class count.
+
+### `plugins` — every configured plugin loads
+
+`fail` with a count of plugin load errors. Run `rigor plugins --strict`
+for the per-plugin report. A failure is usually a misspelled id or a
 plugin whose `signature_paths:` did not resolve. Fix it, or the plugin's
 type knowledge is silently absent.
 
-## 3. The baseline is not stale (if one exists)
+### `plugin_skew` — a bundled plugin came from another installation
 
-```sh
-rigor baseline drift
-```
+`warn` when a bundled plugin was loaded from a different `rigortype`
+installation than the engine. The engine and its bundled plugins are
+versioned together, so a mismatched copy can produce wrong diagnostics.
+Make sure a single `rigortype` is on the load path.
+
+### `baseline` — the baseline is not stale (if one exists)
+
+- `fail` — drift: some baseline buckets are over their recorded count,
+  cleared, or reducible. The hint is `rigor baseline regenerate`; before
+  regenerating, run `rigor baseline drift` to see which buckets moved, so
+  a regeneration does not bury a new catch (often after an upgrade — see
+  `rigor-upgrade`).
+- `warn` — the baseline file failed to load. Check the `baseline:` path
+  in the config.
+
+### `plugin_gap` — the stack has a plugin that is not enabled
+
+Read from the `DEPENDENCIES` section of `Gemfile.lock`.
+
+- `fail` — the project depends on gems that bundled plugins model, and
+  **none** of those plugins is enabled: framework calls will not resolve.
+  Add the plugins for the stack to `plugins:` (the `rigor-plugin-tune`
+  skill does this).
+- `warn` — one per plugin that models a direct dependency but is not
+  enabled. Enable it, or leave it out deliberately; declining a plugin is
+  a legitimate choice.
+
+### `gemfile_install` — Rigor is a project dependency
+
+`fail` when `rigortype` is resolved from a gem source in the project's
+`Gemfile.lock`. Rigor is a tool, not a library: remove it from the
+`Gemfile` and install it standalone (`rigor docs manual/01-installation`).
+
+### `bundle_layout` — gem-shipped signatures are not discovered
 
-Shows whether the live diagnostics have drifted from `.rigor-baseline.yml`
-— entries the baseline ignores that no longer occur (safe to prune) and
-new diagnostics outside the envelope. A large drift means the baseline
-needs regenerating (often after an upgrade — see `rigor-upgrade`).
+`warn` when a `Gemfile.lock` exists but Rigor cannot locate the installed
+bundle (the gems live in the active Ruby's default gem home). Gems that
+ship their own `sig/` are then not loaded. Point Rigor at the install
+root with `bundler.bundle_path:`, install into `vendor/bundle`, or supply
+signatures with `rbs collection install` instead.
 
-## 4. The analysis is actually seeing your code
+## Not covered by `rigor doctor`: is the analysis seeing your code?
 
 ```sh
-rigor check --format json   # check the "Ruby source files" count
+rigor check --no-cache --format json | jq '.stats.target_files'
 ```
 
-If the file count is `0` or far below your project size, `paths:` /
-`exclude:` are mis-scoped, or the command is running from the wrong
+`--no-cache` matters: a result served from the run cache carries no
+`stats`. If the file count is `0` or far below your project size, `paths:`
+/ `exclude:` are mis-scoped, or the command is running from the wrong
 directory. The analysis is only as good as the files it reads.

data/skills/rigor-editor-setup/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-editor-setup
-description: |
-  Wire Rigor's bundled language server (`rigor lsp`) into the developer's editor for live diagnostics, hover-to-type, outline, and type-aware completion. The per-editor config snippets live in the manual; this skill identifies the editor, applies the right one, and verifies the server attaches. Triggers: "set up Rigor in my editor", "rigor LSP / language server", "live Rigor diagnostics in VS Code / Neovim / Helix / Emacs", "hover types in my editor". NOT for CI integration (use rigor-ci-setup) or first-time project setup (use rigor-project-init).
+description: >-
+  Set up Rigor's bundled language server for live diagnostics, hover, outline, and completion in a
+  developer's editor. Use when wiring `rigor lsp` into VS Code, Neovim, Helix, Emacs, or another LSP
+  client; not for CI or first-time project setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -24,7 +26,7 @@ rigor docs editor-integration
 ```
 
 (Web fallback, only before Rigor is installed:
-**[Rigor LSP — Editor Integration](../../docs/manual/09-editor-integration.md)**.)
+**[Rigor LSP — Editor Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/09-editor-integration.md)**.)
 This skill is the *workflow* around it (identify the editor → apply the
 manual's snippet → verify), so it does not duplicate (and cannot
 stale-out) the config details.
@@ -62,7 +64,7 @@ Every editor snippet simply launches **`rigor lsp`** (stdio) and needs
 **`rigor` on the editor's `PATH`** — the same executable `rigor check`
 uses. For GUI editors that do not inherit your shell, the `mise` shim
 path is the most reliable channel (see `rigor docs install`, or
-[Installing Rigor](../../docs/install.md)
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
 on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
 is a tool, not a library.