rigortype 0.2.8 → 0.3.0

data/lib/rigor/cli/plugins_renderer.rb

@@ -10,9 +10,12 @@ module Rigor
     # The two formats carry the same content; JSON is meant for tooling (SKILLs, CI, editor integrations) while text is
     # for interactive inspection. Rows are printed in the order the loader resolved them.
     class PluginsRenderer # rubocop:disable Metrics/ClassLength
-      def initialize(rows:, configuration_path:)
+      # `inflection:` (ADR-90) is nil, or `{required_by: [ids], available: Boolean}` — the activation-time
+      # `Plugin::Inflector` probe result when a loaded plugin consumes the shared inflection helper.
+      def initialize(rows:, configuration_path:, inflection: nil)
         @rows = rows
         @configuration_path = configuration_path
+        @inflection = inflection
       end
 
       def text
@@ -25,17 +28,23 @@ module Rigor
         end
         lines << ""
         lines << footer
+        lines.concat(inflection_warning_lines)
         lines.join("\n")
       end
 
       def json
-        JSON.pretty_generate(
-          {
-            "configuration" => @configuration_path,
-            "plugins" => @rows.map { |row| row_json(row) },
-            "summary" => summary
+        payload = {
+          "configuration" => @configuration_path,
+          "plugins" => @rows.map { |row| row_json(row) },
+          "summary" => summary
+        }
+        unless @inflection.nil?
+          payload["inflection"] = {
+            "required_by" => @inflection.fetch(:required_by),
+            "available" => @inflection.fetch(:available)
           }
-        )
+        end
+        JSON.pretty_generate(payload)
       end
 
       # ADR-37 § "Machine-readable capability catalogue" — the focused per-plugin extension-protocol dump. Only loaded
@@ -84,7 +93,7 @@ module Rigor
         [
           ["node_rule", row[:node_rule_types]],
           ["dynamic_return receivers", row[:dynamic_return_receivers]],
-          ["type_specifier methods", row[:type_specifier_methods]],
+          ["narrowing_facts methods", row[:narrowing_facts_methods]],
           ["produces", row[:produces]],
           ["consumes", row[:consumes]]
         ].filter_map { |label, values| "#{label}: #{values.join(', ')}" if values.any? }
@@ -97,7 +106,7 @@ module Rigor
           "version" => row[:version],
           "node_rule_types" => row[:node_rule_types],
           "dynamic_return_receivers" => row[:dynamic_return_receivers],
-          "type_specifier_methods" => row[:type_specifier_methods],
+          "narrowing_facts_methods" => row[:narrowing_facts_methods],
           "produces" => row[:produces],
           "consumes" => row[:consumes]
         }
@@ -122,6 +131,22 @@ module Rigor
         end
       end
 
+      # ADR-90 — the text-view degradation warning. Printed only when the probe ran (an Inflector-consuming
+      # plugin is loaded) AND inflection is unavailable; the healthy case stays quiet.
+      def inflection_warning_lines
+        return [] if @inflection.nil? || @inflection.fetch(:available)
+
+        [
+          "",
+          "WARNING: ActiveSupport::Inflector is not loadable — inflection-dependent checks of " \
+          "#{@inflection.fetch(:required_by).join(', ')} will silently produce no diagnostics.",
+          "         Rigor found activesupport neither in its own gem environment nor in the project's " \
+          "bundler install tree.",
+          "         Fix: run `bundle install` in the analyzed project (Rigor reads vendor/bundle or " \
+          ".bundle/config), or install activesupport into Rigor's gem environment."
+        ]
+      end
+
       def row_lines(row)
         marker = row[:status] == :loaded ? "OK " : "ERR"
         head = if row[:status] == :loaded
@@ -131,6 +156,10 @@ module Rigor
                end
         lines = [head]
         lines << "        #{row[:description]}" if row[:description]
+        # #194 slice 1 — the file the plugin gem loaded from, so an engine↔plugin version skew (a stale
+        # installed `rigortype` shadowing a checkout's bundled plugin) is a glance, not a bisect. Shown for
+        # loaded rows and for a require-succeeded-then-failed error row; omitted when unresolvable.
+        lines << "        path: #{row[:path]}" if row[:path]
 
         if row[:status] == :load_error
           lines << "        load error: #{row[:load_error]}"
@@ -170,8 +199,8 @@ module Rigor
         if row[:dynamic_return_receivers].any?
           lines << "        dynamic_return receivers: #{row[:dynamic_return_receivers].join(', ')}"
         end
-        if row[:type_specifier_methods].any?
-          lines << "        type_specifier methods: #{row[:type_specifier_methods].join(', ')}"
+        if row[:narrowing_facts_methods].any?
+          lines << "        narrowing_facts methods: #{row[:narrowing_facts_methods].join(', ')}"
         end
         lines
       end
@@ -213,6 +242,9 @@ module Rigor
           "id" => row[:id],
           "version" => row[:version],
           "description" => row[:description],
+          # #194 slice 1 — additive per-row provenance; null when the resolver could not pin the file (a
+          # require failure, or an entry-file basename differing from the gem name).
+          "path" => row[:path],
           "config" => row[:config],
           "signature_paths" => row[:signature_paths].map do |sp|
             { "path" => sp[:path], "exists" => sp[:exists], "rbs_files" => sp[:rbs_files] }
@@ -231,7 +263,7 @@ module Rigor
           "source_rbs_synthesizer" => row[:source_rbs_synthesizer],
           "node_rule_types" => row[:node_rule_types],
           "dynamic_return_receivers" => row[:dynamic_return_receivers],
-          "type_specifier_methods" => row[:type_specifier_methods],
+          "narrowing_facts_methods" => row[:narrowing_facts_methods],
           "load_error" => row[:load_error]
         }
       end

data/lib/rigor/cli/probe_environment.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../environment"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+
+module Rigor
+  class CLI
+    # Shared construction of the analysis-observing environment for the single-shot probe commands
+    # (`type-of`, `type-scan`, `trace`, `annotate`). Each of these answers "what does the engine infer here?"
+    # for a hand-picked file or position, so the environment they type against MUST match the one `rigor check`
+    # analyses with — otherwise a probe reports a type the real run never computes.
+    #
+    # The gap this closes: the probes historically built their environment with
+    # `Environment.for_project(libraries:, signature_paths:)` only — no plugin registry, no `source_files:`. The
+    # `source_rbs_synthesizer` plugin hook (ADR-32 / ADR-93's auto-wired `rigor-rbs-inline`) therefore never
+    # ran there, so a class whose only signature comes from an inline `#: () -> void` annotation typed as
+    # `Dynamic[top]` under a probe while `check` resolved it through the synthesized RBS. That divergence
+    # misattributed a dispatch tier during the #162 transitive-void design pass (see the 2026-07-19 addendum in
+    # docs/adr/100-static-diagnostic-family-and-void-origins.md).
+    #
+    # This threads the two things that were missing — the plugin registry built by the plugin loader, and the
+    # `source_files:` the synthesizers run over — matching `rigor check`'s `Environment.for_project` call
+    # (built in `Analysis::Runner::PoolCoordinator#build_runner_environment`). A probe legitimately simplifies
+    # relative to check: no synthesis-failure reporter (a probe has no diagnostic pipeline) and no synthesis
+    # cache store (a single-position probe recomputes cheaply). Plugin loading itself matches check — same
+    # `.rigor.yml` `plugins:` config, same ADR-93 auto-wire (already applied by `Configuration.load`), same
+    # `enabled:` / `require_magic_comment` semantics via `Plugin::Loader.load`.
+    #
+    # Fail-soft is the invariant: a project with no plugins, an unresolvable plugin gem, or any error during the
+    # plugin-aware build degrades to the bare environment the probes used before — never a crash. `Plugin::Loader`
+    # already isolates per-entry load failures onto the registry; the `rescue` here is the belt-and-suspenders
+    # around anything the loader or the plugin-aware env build itself might raise.
+    module ProbeEnvironment
+      module_function
+
+      # Builds the plugin-aware {Rigor::Environment} a probe types against.
+      #
+      # @param configuration [Rigor::Configuration] the loaded project configuration (already carries the
+      #   ADR-93 auto-wired `rigor-rbs-inline` entry when the library is resolvable).
+      # @param source_files [Array<String>] the file(s) the probe inspects. Threaded so each loaded plugin's
+      #   `source_rbs_synthesizer` runs over them at env-build time; an empty list contributes no synthesized RBS.
+      # @return [Rigor::Environment]
+      def build(configuration:, source_files:)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths,
+          plugin_registry: load_plugin_registry(configuration),
+          source_files: source_files
+        )
+      rescue StandardError
+        bare(configuration)
+      end
+
+      # Loads the project's configured plugins the same way the plugin-inspection commands (`rigor plugins`,
+      # `rigor doctor`) do: a `Plugin::Services` with no cache store (the probe recomputes) driving
+      # `Plugin::Loader.load`. Returns `nil` — so `Environment.for_project` skips the plugin tier entirely —
+      # when the project declares no plugins.
+      def load_plugin_registry(configuration)
+        return nil if configuration.plugins.empty?
+
+        services = Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: nil
+        )
+        Plugin::Loader.load(configuration: configuration, services: services)
+      end
+
+      # The pre-fix environment: RBS + project signatures only, no plugin tier and no synthesized RBS. The
+      # fail-soft floor — a probe on a project with broken or absent plugin setup lands here and behaves exactly
+      # as it did before this parity fix.
+      def bare(configuration)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
+      end
+    end
+  end
+end

data/lib/rigor/cli/protection_fork_scan.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../inference/fork_map"
+
+module Rigor
+  class CLI
+    # Fork-pool for the `rigor coverage --protection` scan (P3-10). The plugin-aware environment and the
+    # seeded scope are built ONCE on the parent — the expensive part: RBS env, plugin registry, and the
+    # cross-file discovery + parameter-inference seed — and children copy-on-write inherit them (via
+    # {Inference::ForkMap}), each analysing a contiguous slice of paths and returning per-path results the
+    # parent merges in original path order.
+    #
+    # The scan is pure-read (no reporter drains, no plugin-emission merge, no prepare diagnostics), so a
+    # slice payload is just `{path => result}`. Determinism: the parent merges slice payloads in slice order
+    # and the accumulator absorbs in `paths` order, so the fused report is byte-identical to a sequential run
+    # regardless of which worker produced which file.
+    module ProtectionForkScan
+      module_function
+
+      # A parse failure for one file, carrying only the marshalable error count (Prism error objects are not
+      # reliably marshalable, and the accumulator only needs the count).
+      ParseError = Data.define(:count)
+
+      # @param paths [Array<String>] the files to scan, in caller order.
+      # @param scanner [Inference::ProtectionScanner] built on the parent; COW-inherited by workers.
+      # @param environment [Rigor::Environment] the scanner's environment, prewarmed here before forking.
+      # @param configuration [Rigor::Configuration] for the Prism `target_ruby` version.
+      # @param workers [Integer] resolved worker count (≤1 → sequential).
+      # @return [Hash{String => Inference::ProtectionScanner::FileResult, ParseError}] one entry per path.
+      def run(paths:, scanner:, environment:, configuration:, workers:)
+        # Force the full RBS load on the parent so children copy-on-write inherit a warm environment rather
+        # than each rebuilding it after the fork (mirrors the check fork pool's parent-side prewarm). A
+        # no-op on the sequential path but cheap.
+        environment.rbs_loader&.prewarm if Inference::ForkMap.parallel?([workers, paths.size].min)
+
+        payloads = Inference::ForkMap.call(items: paths, workers: workers) do |slice|
+          slice.to_h { |path| [path, scan_path(path, scanner, configuration)] }
+        end
+        payloads.each_with_object({}) { |slice_results, merged| merged.merge!(slice_results) }
+      end
+
+      # Parses one file and returns the scanner's {Inference::ProtectionScanner::FileResult}, or a
+      # {ParseError} when the source does not parse.
+      def scan_path(path, scanner, configuration)
+        source = File.read(path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
+        return ParseError.new(count: parse_result.errors.size) if parse_result.errors.any?
+
+        scanner.scan(parse_result.value)
+      end
+    end
+  end
+end

data/lib/rigor/cli/protection_report.rb

@@ -86,7 +86,13 @@ module Rigor
       end
 
       def record_parse_error(path, errors)
-        @parse_errors << { "path" => path, "errors" => errors.size }
+        record_parse_error_count(path, errors.size)
+      end
+
+      # Count-based variant for the fork-pool path, where a worker carries only the marshalable error count
+      # (see {ProtectionForkScan::ParseError}), not the Prism error objects.
+      def record_parse_error_count(path, count)
+        @parse_errors << { "path" => path, "errors" => count }
       end
 
       def to_report

data/lib/rigor/cli/sig_gen_command.rb

@@ -42,21 +42,43 @@ module Rigor
         paths = @argv.empty? ? configuration.paths : @argv
 
         observations = collect_observations(configuration, options)
-        candidates = SigGen::Generator.new(configuration: configuration, paths: paths,
-                                           observations: observations,
-                                           include_private: options.fetch(:include_private)).run
+        generator = SigGen::Generator.new(configuration: configuration, paths: paths,
+                                          observations: observations,
+                                          include_private: options.fetch(:include_private))
+        candidates = generator.run
         mode = options.fetch(:mode).to_sym
 
-        if mode == :write
-          dispatch_write(candidates, configuration, options)
-        else
-          dispatch_print_or_diff(candidates, mode, options)
-        end
-        0
+        status = if mode == :write
+                   dispatch_write(candidates, configuration, options)
+                 else
+                   dispatch_print_or_diff(candidates, mode, options)
+                   0
+                 end
+        report_unrenderable(generator.unrenderable)
+        status
       end
 
       private
 
+      # A method whose rendered RBS does not parse is a Rigor rendering defect, not a fact about the user's
+      # code — the generator skipped it (so the rest of the signatures are still usable and still valid), but
+      # staying silent would leave the user with a quietly incomplete `sig/` and us with an unreported bug.
+      # Reported on stderr so it never contaminates `--print` output being piped into a file.
+      def report_unrenderable(unrenderable)
+        return if unrenderable.empty?
+
+        @err.puts(
+          "rigor sig-gen: skipped #{unrenderable.size} method(s) whose generated RBS does not parse. " \
+          "This is a bug in Rigor's RBS rendering, not in your code — please report it. " \
+          "The remaining signatures are unaffected."
+        )
+        unrenderable.each do |method|
+          @err.puts("  #{method.path}: #{method.class_name}##{method.method_name}")
+          @err.puts("    rendered: #{method.rbs}")
+          @err.puts("    #{method.error}")
+        end
+      end
+
       def dispatch_print_or_diff(candidates, mode, options)
         SigGen::Renderer.new(out: @out).render(
           candidates: candidates,
@@ -66,6 +88,7 @@ module Rigor
         )
       end
 
+      # @return [Integer] exit status — non-zero when a file the user asked to write could not be written.
       def dispatch_write(candidates, configuration, options)
         layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
         path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)
@@ -74,6 +97,10 @@ module Rigor
         results = writer.write_all(candidates)
 
         SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
+        # An assembled file that does not parse is refused rather than written. The user asked for a write and
+        # did not get one, so the command must not report success — a green `sig-gen --write` in CI would
+        # otherwise mean nothing.
+        results.any? { |result| result.action == :skipped_invalid_rbs } ? 1 : 0
       end
 
       # Slice 3 — collect call-site argument observations when `--params=observed` is set. When `--observe=PATH` is not

data/lib/rigor/cli/skill_command.rb

@@ -37,9 +37,7 @@ module Rigor
     #                                the SKILL. Also spelled `describe`, and
     #                                surfaced top-level as `rigor describe`.
     #
-    # The pre-v0.3.0 verb spellings `rigor skill list` / `print <name>` / `path <name>` still work but emit a stderr
-    # deprecation notice; they are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI deprecations"). `describe` is
-    # a no-argument action, not a name-slot verb, so it stays first-class alongside `--describe`.
+    # `describe` is a no-argument action, not a name-slot verb, so it stays first-class alongside `--describe`.
     class SkillCommand < Command
       USAGE = <<~USAGE
         Usage: rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
@@ -60,30 +58,14 @@ module Rigor
           rigor skill --full rigor-baseline-reduce
           rigor skill --path rigor-baseline-reduce
           rigor skill --describe        (also: rigor describe)
-
-        Deprecated (removed in v0.3.0) — use the forms above:
-          rigor skill list           ->  rigor skill --list
-          rigor skill print <name>   ->  rigor skill <name>
-          rigor skill path <name>    ->  rigor skill --path <name>
       USAGE
 
       # The bundled skills live at `<gem_root>/skills/`. From `lib/rigor/cli/skill_command.rb` that is three directories
       # up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
-      # The verb subcommands the flags superseded keep working with a stderr deprecation notice until this version drops
-      # them. Each maps to the canonical advice printed and the flag it rewrites to.
-      LEGACY_VERB_REMOVAL = "v0.3.0"
-      LEGACY_VERBS = {
-        "list" => { old: "list",         advice: "--list", flag: "--list" },
-        "print" => { old: "print <name>", advice: "<name>", flag: "--print" },
-        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
-      }.freeze
-
       # @return [Integer] CLI exit status.
       def run
-        rewrite_legacy_verb!
-
         case @argv.first
         when nil
           run_list
@@ -112,19 +94,6 @@ module Rigor
 
       private
 
-      # Translate a deprecated verb spelling into its flag form, warning once on stderr, so the dispatch above only
-      # handles canonical forms.
-      def rewrite_legacy_verb!
-        spec = LEGACY_VERBS[@argv.first]
-        return unless spec
-
-        @err.puts(
-          "rigor skill: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
-          "#{LEGACY_VERB_REMOVAL}; use `rigor skill #{spec.fetch(:advice)}` instead."
-        )
-        @argv[0] = spec.fetch(:flag)
-      end
-
       def run_list
         skills = discover_skills
         if skills.empty?

data/lib/rigor/cli/trace_command.rb

@@ -12,6 +12,7 @@ require_relative "../inference/flow_tracer"
 require_relative "../inference/scope_indexer"
 require_relative "command"
 require_relative "trace_renderer"
+require_relative "probe_environment"
 
 module Rigor
   class CLI
@@ -90,13 +91,11 @@ module Rigor
         0
       end
 
-      # Mirrors the single-file path `rigor type-of` takes: a project-aware environment, an empty seed scope, one
-      # statement-level evaluation of the whole program — but recorded under the FlowTracer.
+      # Mirrors the single-file path `rigor type-of` takes: the plugin-aware environment (so a trace replays the
+      # same dispatch `rigor check` would, including plugin-synthesized RBS — see {ProbeEnvironment}), an empty
+      # seed scope, one statement-level evaluation of the whole program — but recorded under the FlowTracer.
       def record_events(root, file, configuration)
-        environment = Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
-        )
+        environment = ProbeEnvironment.build(configuration: configuration, source_files: [file])
         scope = Scope.empty(environment: environment, source_path: file)
         Inference::FlowTracer.record { scope.evaluate(root) }
       end

data/lib/rigor/cli/type_of_command.rb

@@ -13,6 +13,7 @@ require_relative "../inference/scope_indexer"
 require_relative "type_of_renderer"
 require_relative "command"
 require_relative "options"
+require_relative "probe_environment"
 
 module Rigor
   class CLI
@@ -92,14 +93,14 @@ module Rigor
         0
       end
 
-      # Builds a project-aware environment relative to the probed file. Project-RBS auto-detection roots at CWD today;
-      # future work will walk parent directories to find the enclosing `Gemfile`/`*.gemspec` so probes against files
-      # outside the current process's CWD still see the right `sig/` tree.
-      def project_environment(_file, configuration)
-        Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
-        )
+      # Builds the plugin-aware environment relative to the probed file, so the reported type matches what `rigor
+      # check` computes for the same position — including types synthesized from inline RBS annotations by the
+      # ADR-93 auto-wired `rigor-rbs-inline` plugin (see {ProbeEnvironment} for the #162 misattribution this
+      # closes). The probed file is threaded as the synthesizer's `source_files:`. Project-RBS auto-detection
+      # roots at CWD today; future work will walk parent directories to find the enclosing `Gemfile`/`*.gemspec`
+      # so probes against files outside the current process's CWD still see the right `sig/` tree.
+      def project_environment(file, configuration)
+        ProbeEnvironment.build(configuration: configuration, source_files: [file])
       end
 
       def file_exists?(file)

data/lib/rigor/cli/type_scan_command.rb

@@ -11,6 +11,7 @@ require_relative "../scope"
 require_relative "type_scan_renderer"
 require_relative "type_scan_report"
 require_relative "command"
+require_relative "probe_environment"
 
 module Rigor
   class CLI
@@ -69,20 +70,19 @@ module Rigor
 
       def scan_paths(paths, options)
         configuration = Configuration.load(options.fetch(:config))
-        scope = Scope.empty(environment: project_environment(configuration))
+        scope = Scope.empty(environment: project_environment(configuration, paths))
         scanner = Inference::CoverageScanner.new(scope: scope)
         accumulator = ScanAccumulator.new
         paths.each { |path| scan_one(path, scanner, accumulator, configuration) }
         accumulator.to_report(paths, options)
       end
 
-      # Builds a project-aware environment that auto-detects `<cwd>/sig` by default and honours the configuration's
-      # `libraries:` / `signature_paths:` keys when present.
-      def project_environment(configuration)
-        Environment.for_project(
-          libraries: configuration.libraries,
-          signature_paths: configuration.signature_paths
-        )
+      # Builds the plugin-aware environment that auto-detects `<cwd>/sig` by default and honours the
+      # configuration's `libraries:` / `signature_paths:` keys when present. The scanned `paths` are threaded as
+      # the plugin `source_rbs_synthesizer` inputs so coverage reflects the same synthesized RBS `rigor check`
+      # sees (see {ProbeEnvironment}).
+      def project_environment(configuration, source_files)
+        ProbeEnvironment.build(configuration: configuration, source_files: source_files)
       end
 
       def scan_one(path, scanner, accumulator, configuration)

data/lib/rigor/cli.rb

@@ -11,7 +11,7 @@ require_relative "analysis/diagnostic"
 require_relative "analysis/result"
 require_relative "cli/options"
 require_relative "cli/diagnostic_formats"
-require_relative "cli/ci_detector"
+require_relative "ci_detector"
 
 module Rigor
   # The CLI class is a dispatcher: each `run_*` method delegates to a command-specific class once the command grows
@@ -20,6 +20,16 @@ module Rigor
   class CLI # rubocop:disable Metrics/ClassLength
     EXIT_USAGE = 64
 
+    # The published location of `schemas/rigor-config.schema.json`, written into the `.rigor.yml` that
+    # `rigor init` generates so an editor validates the file as the user types.
+    #
+    # This MUST equal the schema's own `$id`, and it MUST resolve. Both are gated
+    # (`spec/rigor/config_schema_spec.rb`) because neither failure has a symptom: an unreachable schema
+    # is indistinguishable from a schema with no complaints, so a stale URL here silently disables
+    # validation for every project that ran `rigor init`. It pointed at a nonexistent org until
+    # 2026-07-17 and nothing noticed. See `docs/internal-spec/config.md`.
+    CONFIG_SCHEMA_URL = "https://github.com/rigortype/rigor/raw/master/schemas/rigor-config.schema.json"
+
     HANDLERS = {
       "check" => :run_check,
       "init" => :run_init,
@@ -138,9 +148,10 @@ module Rigor
     # most likely to want to edit.
     def init_template
       <<~YAML
-        # yaml-language-server: $schema=https://github.com/zenwerk/rigor/raw/master/schemas/rigor-config.schema.json
-        # Rigor configuration. See docs/CURRENT_WORK.md for the
-        # full set of features the analyzer ships in this preview.
+        # yaml-language-server: $schema=#{CONFIG_SCHEMA_URL}
+        # Rigor configuration. The full key reference is
+        # https://github.com/rigortype/rigor/blob/master/docs/manual/03-configuration.md
+        # (or run `rigor docs configuration`).
         #
         # Keys you may want to edit:
         # - target_ruby: minimum Ruby version your project targets.

data/lib/rigor/config_audit.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require "did_you_mean"
+
 require_relative "signature_path_audit"
-require_relative "analysis/check_rules"
+# ADR-87 WD4 — only the pure rule-id table (`ALL_RULES` / `RULE_FAMILIES`) is needed, so require the light
+# `rule_ids.rb` rather than the engine-pulling `check_rules.rb`; keeps `config_audit` (loaded by every check)
+# off the inference engine so the boot-slimming hit path stays engine-free.
+require_relative "analysis/check_rules/rule_ids"
 
 module Rigor
   # Audits a loaded {Configuration} for the class of mistake where a configured value
@@ -36,12 +41,53 @@ module Rigor
     #   paths resolve against (the CLI's CWD), used only by the explicit-path checks.
     # @return [Array<Warning>]
     def self.warnings(configuration, project_root: Dir.pwd)
-      signature_path_warnings(configuration) +
+      unknown_key_warnings(configuration) +
+        signature_path_warnings(configuration) +
         library_warnings(configuration) +
         rule_token_warnings(configuration) +
         explicit_path_warnings(configuration, project_root)
     end
 
+    # Top-level keys the loader does not own. The archetypal case is a typo — `excludee:` for
+    # `exclude:` — which the loader drops in silence, so the exclusion never applies and the run
+    # reports errors from the very files the user meant to skip, with nothing anywhere saying the key
+    # did nothing. That is exactly this module's class of mistake, and it was the one whole-key
+    # instance of it going unwarned.
+    #
+    # A reserved namespace ({Configuration::RESERVED_NAMESPACES}) is unknown *on purpose* — another
+    # implementation reads it from the same file — so it is exempt. {Configuration#unknown_keys}
+    # already applies that exemption; warning here would push users to delete the key their other
+    # tool needs.
+    #
+    # **Top level only, and deliberately.** A nested check would have to name each group's known keys,
+    # and DEFAULTS cannot supply them: `DEFAULTS["dependencies"]` carries `source_inference` and
+    # `budget_per_gem` but not `budget_overrun_strategy`, which is real (`Configuration::Dependencies`
+    # reads it), documented, and schema-declared — so a DEFAULTS-keyed nested check would flag a
+    # working config. `severity_overrides:` is an open map of rule ids besides. Nested unknown keys are
+    # the schema tier's job: every nested object in `schemas/rigor-config.schema.json` is
+    # `additionalProperties: false`, and `config_schema_spec` keeps it complete
+    # ([ADR-99](../../docs/adr/99-config-schema-authority.md), `docs/internal-spec/config.md`).
+    def self.unknown_key_warnings(configuration)
+      configuration.unknown_keys.map do |key|
+        suggestion = suggest_config_key(key)
+        hint = suggestion ? " Did you mean `#{suggestion}`?" : ""
+        Warning.new(
+          kind: :unknown_key,
+          message: "`#{key}` is not a recognized configuration key; it has no effect.#{hint}",
+          fields: { "key" => key, "suggestion" => suggestion }
+        )
+      end
+    end
+
+    # Nearest known key, or nil. Uses `DidYouMean::SpellChecker` — the engine behind Ruby's own
+    # `NoMethodError` hints, and the one `Plugin::Base.suggest` wraps. Called directly rather than
+    # through that helper because `plugin/base.rb` pulls Prism and the diagnostic model in, and
+    # ADR-87 WD4 keeps this file (loaded by every check) off that path; `did_you_mean` is stdlib.
+    def self.suggest_config_key(key)
+      DidYouMean::SpellChecker.new(dictionary: Configuration::KNOWN_KEYS).correct(key.to_s).first
+    end
+    private_class_method :suggest_config_key
+
     # `signature_paths:` entries that resolve to nothing — delegated to {SignaturePathAudit},
     # which mirrors the loader's `directory?` + recursive `**/*.rbs` acceptance test.
     def self.signature_path_warnings(configuration)