rigortype 0.3.8 → 0.3.9

data/lib/rigor/cli/check_command.rb

@@ -32,14 +32,21 @@ module Rigor
     # The class-length budget is relaxed (as on `Rigor::CLI` itself) because `check` aggregates several independent
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
-      # @return [Integer] CLI exit status.
+      # Issue #812 — `--fail-on=SEVERITY` raises the exit-status bar above the default (`:error`-only).
+      # Orders the three severities a diagnostic can carry once it survives {SeverityStamp} (`:off` rows are
+      # dropped upstream and never reach a `Result`, so they are not a member here).
+      FAIL_ON_RANK = { info: 0, warning: 1, error: 2 }.freeze
+
+      # @return CLI exit status.
       #
       # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
       # one included, before any analysis work runs.
-      def run # rubocop:disable Metrics/AbcSize
+      def run # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         # ADR-87 WD4 — parse options + resolve config WITHOUT the inference engine, so the run-cache hit probe
         # can run first. The heavy engine (`load_check_dependencies`) loads only on a miss / non-cacheable run.
         options = parse_check_options
+        return CLI::EXIT_USAGE unless valid_fail_on_option?(options)
+
         buffer = Options.resolve_buffer_binding(options, err: @err)
         return CLI::EXIT_USAGE if buffer == :usage_error
 
@@ -68,7 +75,8 @@ module Rigor
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
-        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings)
+        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings,
+                                                     fail_on: options.fetch(:fail_on))
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -77,11 +85,34 @@ module Rigor
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
+        exit_code = 1 if fail_on_violation?(result.diagnostics, options)
         exit_code
       end
 
       private
 
+      # True when `diagnostics` (already baseline-filtered and severity-resolved — the same list
+      # `Result#success?` reads) carries a row at or above the `--fail-on` threshold. With the default
+      # `:error` threshold this is exactly `!diagnostics.any?(&:error?)`, i.e. a no-op over the existing exit
+      # code — `--fail-on` only ever makes a run *stricter*, never masks an `:error` the old exit code caught.
+      def fail_on_violation?(diagnostics, options)
+        threshold = FAIL_ON_RANK.fetch(options.fetch(:fail_on))
+        diagnostics.any? { |diagnostic| FAIL_ON_RANK.fetch(diagnostic.severity, FAIL_ON_RANK[:error]) >= threshold }
+      end
+
+      # True when `options[:fail_on]` (an arbitrary user-typed Symbol at this point — parsing only lower-cases
+      # and interns it, see `parse_check_options`) is one of {FAIL_ON_RANK}'s keys; writes a usage note to
+      # `@err` and returns false otherwise. Validated as a plain post-parse check rather than raised from
+      # inside the `opts.on` block: OptionParser rescues a `ParseError` raised from a switch's own block and
+      # rebuilds it as a generic `"invalid argument: --fail-on=<value>"`, discarding any custom message — this
+      # way the usage note actually names the accepted values.
+      def valid_fail_on_option?(options)
+        return true if FAIL_ON_RANK.key?(options.fetch(:fail_on))
+
+        @err.puts("rigor: invalid --fail-on value: #{options.fetch(:fail_on)} (expected error, warning, or info)")
+        false
+      end
+
       # ADR-87 WD4 — attempt the boot-slimming run-cache hit. Returns the cached {Analysis::Result} (severity
       # profile applied, no stats — matching a cache-served `Runner#run`) on a hit, or nil to fall through to
       # the full engine path. Only an ordinary sequential check whose result IS cache-served the same way is
@@ -129,11 +160,13 @@ module Rigor
       # gate reads the same diagnostics the full path would.
       def finalize_cache_hit(raw_result, configuration, options, config_warnings)
         result = apply_baseline_filter(raw_result, configuration, options)
-        write_result(result, options.fetch(:format), config_warnings: config_warnings)
+        write_result(result, options.fetch(:format), config_warnings: config_warnings,
+                                                     fail_on: options.fetch(:fail_on))
         emit_ci_detected_output(result, options)
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
+        exit_code = 1 if fail_on_violation?(result.diagnostics, options)
         exit_code
       end
 
@@ -233,8 +266,8 @@ module Rigor
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
-        write_result(result, options.fetch(:format))
-        result.success? ? 0 : 1
+        write_result(result, options.fetch(:format), fail_on: options.fetch(:fail_on))
+        !result.success? || fail_on_violation?(result.diagnostics, options) ? 1 : 0
       end
 
       # Editor mode option B (#146) — `--incremental` plus an editor buffer. The whole project is in scope with
@@ -260,8 +293,8 @@ module Rigor
         filtered = apply_baseline_filter(
           Analysis::Result.new(diagnostics: result.diagnostics, stats: nil), configuration, options
         )
-        write_result(filtered, options.fetch(:format))
-        filtered.success? ? 0 : 1
+        write_result(filtered, options.fetch(:format), fail_on: options.fetch(:fail_on))
+        !filtered.success? || fail_on_violation?(filtered.diagnostics, options) ? 1 : 0
       end
 
       # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
@@ -439,6 +472,10 @@ module Rigor
           baseline: :unset,
           # ADR-22 slice 5 — `--baseline-strict` CI gate: fail the run on any baseline drift, in either direction.
           baseline_strict: false,
+          # Issue #812 — `--fail-on=SEVERITY` raises the exit-status bar: the run exits non-zero when a
+          # diagnostic AT OR ABOVE this severity survives baseline filtering and severity resolution, not only
+          # on `:error` (today's default and behaviour). See `FAIL_ON_RANK`.
+          fail_on: :error,
           # ADR-32 WD10 carry-over — `--treat-all-as-inline-rbs` forces the `rigor-rbs-inline` plugin into the loaded
           # plugin set with `require_magic_comment: false` so a single ad-hoc `rigor check` invocation treats every
           # analysed file as inline-RBS without the user editing `.rigor.yml`. Intended for single-file / ad-hoc CI use;
@@ -508,6 +545,12 @@ module Rigor
                   "fail the run on any baseline drift (CI gate)") do
             options[:baseline_strict] = true
           end
+          opts.on("--fail-on=SEVERITY",
+                  "exit non-zero on a diagnostic at or above SEVERITY: error (default), warning, or info") do |value|
+            # Validated post-parse (`valid_fail_on_option?`, called from `run`) rather than here — see its
+            # comment for why an unrecognised value is not raised from inside this block.
+            options[:fail_on] = value.to_s.downcase.to_sym
+          end
           opts.on("--treat-all-as-inline-rbs",
                   "force-load rigor-rbs-inline with require_magic_comment: false") do
             options[:treat_all_as_inline_rbs] = true
@@ -661,7 +704,6 @@ module Rigor
         @err.puts("  body evals:      #{counts[bt::MEMO_BODY_EVALS]}")
         @err.puts("  non-stored:      on-stack #{counts[bt::MEMO_REFUSE_ON_STACK]}  " \
                   "unroll-in-flight #{counts[bt::MEMO_REFUSE_UNROLL]}  " \
-                  "consult-tainted #{counts[bt::MEMO_REFUSE_CONSULT_TAINTED]}  " \
                   "transient-tainted #{counts[bt::MEMO_REFUSE_TRANSIENT]}")
         write_memo_signature_table
       end
@@ -841,10 +883,15 @@ module Rigor
         format == "text" ? @out : @err
       end
 
-      def write_result(result, format, coverage: nil, config_warnings: [])
+      def write_result(result, format, coverage: nil, config_warnings: [], fail_on: :error)
         case format
         when "json"
           payload = enrich_json(result.to_h)
+          # Issue #812 — the exit code can be stricter than `payload["success"]` (which stays the `:error`-only
+          # reading `Result#success?` always gave, per the other consumers already reading it); a JSON
+          # consumer that wants to know WHY a run exited non-zero reads this alongside it rather than
+          # re-deriving `--fail-on`'s value from the invocation.
+          payload["fail_on"] = fail_on.to_s
           payload["coverage"] = coverage_payload(coverage) if coverage
           payload["config_warnings"] = config_warnings.map(&:to_h) unless config_warnings.empty?
           @out.puts(JSON.pretty_generate(payload))

data/lib/rigor/cli/check_invocation.rb

@@ -22,7 +22,7 @@ module Rigor
       # The outcome of {.attempt} — the best-effort variant. Exactly one of the two is non-nil, so a caller can never
       # read "the check could not run" as "the check ran clean": `result` is nil precisely when `error` is set.
       Outcome = Data.define(:result, :error) do
-        # @return [Boolean] true when an analysis actually completed.
+        # @return true when an analysis actually completed.
         def ran?
           !result.nil?
         end
@@ -42,12 +42,9 @@ module Rigor
 
       # Runs the analysis the way `rigor check` does and returns the runner + its raw result.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param options [Hash] at least `:no_cache`, `:explain`, `:stats`, `:workers` (see {CheckRunnerFactory.build}).
-      # @param paths [Array<String>, nil] analysed paths; nil falls back to the configuration's `paths:`.
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      # @param cache_root [String, nil] nil falls back to the configuration's cache path.
-      # @return [Invocation]
+      # @param options — at least `:no_cache`, `:explain`, `:stats`, `:workers` (see {CheckRunnerFactory.build}).
+      # @param paths — analysed paths; nil falls back to the configuration's `paths:`.
+      # @param cache_root — nil falls back to the configuration's cache path.
       def run(configuration:, options:, paths: nil, buffer: nil, cache_root: nil)
         require_relative "check_runner_factory"
         runner = CheckRunnerFactory.build(
@@ -68,10 +65,8 @@ module Rigor
       # routing hint is outside the false-positive envelope, but a crash in it is not — `describe` must stay a command
       # an agent can run freely.
       #
-      # @param config_path [String, nil] path to the config file; nil uses {Configuration.discover}.
-      # @param options [Hash] runner options (defaults to {DEEP_OPTIONS}).
-      # @param paths [Array<String>, nil]
-      # @return [Outcome]
+      # @param config_path — path to the config file; nil uses {Configuration.discover}.
+      # @param options — runner options (defaults to {DEEP_OPTIONS}).
       def attempt(config_path: nil, options: DEEP_OPTIONS, paths: nil)
         require_relative "../configuration"
         configuration = Configuration.load(config_path)

data/lib/rigor/cli/check_runner_factory.rb

@@ -14,12 +14,8 @@ module Rigor
 
       # Builds a runner matching the configuration/plugin/cache resolution that `rigor check` itself uses.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param options [Hash] parsed CLI options (must contain at least
+      # @param options — parsed CLI options (must contain at least
       #   `:no_cache`, `:explain`, `:stats`, `:workers`)
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      # @param cache_root [String]
-      # @return [Rigor::Analysis::Runner]
       def build(configuration:, options:, buffer:, cache_root:)
         cache_store = if options.fetch(:no_cache)
                         nil

data/lib/rigor/cli/coverage_command.rb

@@ -53,7 +53,7 @@ module Rigor
       # `--test-command`.
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       #
       # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
       # one included: a scan long enough to amortize JIT compile cost enables mid-flight; a short one

data/lib/rigor/cli/coverage_mutation.rb

@@ -48,8 +48,6 @@ module Rigor
       # Both measurement-integrity warnings, and the escalation rule between them, live in
       # {MeasurementIntegrityWarning}. Only the floor stays here: it is this command's policy, and
       # `coverage_command_spec` reads it off this module.
-      #
-      # @param report [MutationProtectionReport, FusedProtectionReport]
       def warn_harness_errors(report)
         MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
@@ -113,10 +111,21 @@ module Rigor
             cache_store: context.cache_store, workers: workers
           ),
           seed_bundles: Protection::DiscoverySeed.bundles(paths: paths),
-          discovery_seed: seed
+          discovery_seed: seed,
+          rebuild_session: -> { rebuilt_session(context) }
         )
       end
 
+      # Issue #790 — how the oracle replaces an Environment a mutant degraded. {LanguageServer::ProjectContext}
+      # already has the operation: `invalidate!` drops the cached environment AND the project scan together,
+      # which is the pair the oracle measures over, and the next reader rebuilds both. Under
+      # {MutationForkScan} this runs in a forked child against its copy-on-write context, so one file's
+      # defect never costs the parent or its siblings a rebuild.
+      def rebuilt_session(context)
+        context.invalidate!
+        [context.environment, context.project_scan]
+      end
+
       # The scope {Protection::Mutator} judges a mutation site's receiver against, derived from the same seed
       # the oracle gets. nil (the gate off, or an empty seed) keeps the bare `Scope.empty` per file.
       def mutation_base_scope(seed, environment)

data/lib/rigor/cli/coverage_scan.rb

@@ -21,9 +21,7 @@ module Rigor
     module CoverageScan
       module_function
 
-      # @param files [Array<String>] explicit `.rb` file paths to scan.
-      # @param configuration [Rigor::Configuration]
-      # @return [Rigor::CLI::CoverageReport]
+      # @param files — explicit `.rb` file paths to scan.
       #
       # Issue #513 — the environment is PLUGIN-AWARE (`LanguageServer::ProjectContext`, the same builder
       # `--protection` uses), not the bare RBS environment this path carried until 2026-09-01. Without the
@@ -57,8 +55,6 @@ module Rigor
       # the precision lens must mirror the walk it describes (`check` leaves the table empty unless
       # `parameter_inference:` is on, ADR-67 WD6a), while `--protection` seeds it unconditionally by ADR-67's own
       # wiring — it only ever reclassifies sites it already counted.
-      #
-      # @return [Rigor::Scope]
       def discovery_seeded_scope(files:, configuration:, environment:, parameter_inference:, workers: nil)
         base = Scope.empty(environment: environment)
         seed = Protection::DiscoverySeed.discovery_tables(files).dup

data/lib/rigor/cli/diff_command.rb

@@ -26,7 +26,7 @@ module Rigor
     class DiffCommand < Command
       USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
 

data/lib/rigor/cli/doc_links.rb

@@ -36,9 +36,9 @@ module Rigor
 
       module_function
 
-      # @param body [String] the page as it is stored.
-      # @param from [String] its absolute path, so relative targets resolve.
-      # @return [String] the page with every relative link turned into a `rigor docs` key.
+      # @param body — the page as it is stored.
+      # @param from — its absolute path, so relative targets resolve.
+      # @return the page with every relative link turned into a `rigor docs` key.
       def rewrite(body, from:)
         dir = File.dirname(from)
         body.gsub(MARKDOWN_LINK) do

data/lib/rigor/cli/docs_command.rb

@@ -52,7 +52,7 @@ module Rigor
       HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
       LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         case @argv.first
         when nil
@@ -136,7 +136,7 @@ module Rigor
       # Resolve a query to a single doc. Exact relative-path and prefixed-basename aliases are unique; a short
       # (prefix-stripped) name is accepted only when one category owns it.
       #
-      # @return [Hash, Integer] the doc entry, or an error exit status
+      # @return the doc entry, or an error exit status
       #   after the error has been written to `@err`.
       def resolve_doc(query)
         # A key printed by a rendered page may carry the section it pointed at; resolve the page and say

data/lib/rigor/cli/doctor_command.rb

@@ -7,9 +7,11 @@ require_relative "../configuration"
 require_relative "../config_audit"
 require_relative "../analysis/baseline"
 require_relative "../analysis/result"
+require_relative "../environment/bundle_sig_discovery"
 require_relative "../plugin"
 require_relative "../plugin/loader"
 require_relative "../plugin/services"
+require_relative "../plugin_gap_advisory"
 require_relative "../reflection"
 require_relative "../type/combinator"
 require_relative "check_invocation"
@@ -33,17 +35,12 @@ module Rigor
       CHECK_RBS = "rbs_environment"
       CHECK_PLUGINS = "plugins"
       CHECK_BASELINE = "baseline"
-      CHECK_RAILS = "rails_plugins"
+      CHECK_PLUGIN_GAP = "plugin_gap"
       CHECK_GEMFILE = "gemfile_install"
       CHECK_PLUGIN_SKEW = "plugin_skew"
+      CHECK_BUNDLE_LAYOUT = "bundle_layout"
 
-      RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
-      RAILS_PLUGIN_MARKERS = %w[
-        rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
-        rigor-rails-routes rigor-rails-i18n rigor-actioncable rigor-activestorage rigor-rails
-      ].freeze
-
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         configuration = Configuration.load(options.fetch(:config))
@@ -70,8 +67,8 @@ module Rigor
         # 5. Baseline drift check.
         findings.concat(check_baseline(configuration, result))
 
-        # 6. Rails locked but no Rails plugins.
-        findings.concat(check_rails_plugins(configuration))
+        # 6. Gems locked that a bundled plugin models, with that plugin not enabled (ADR-96 WD2).
+        findings.concat(check_plugin_gap(configuration))
 
         # 7. Rigor itself resolved as a project dependency.
         findings.concat(check_gemfile_install)
@@ -79,6 +76,9 @@ module Rigor
         # 8. A bundled plugin loaded from a different rigortype installation than the engine (#194 slice 3).
         findings.concat(check_plugin_skew(registry))
 
+        # 9. The project's gems are installed somewhere Rigor cannot see (ADR-25 carry-over).
+        findings.concat(check_bundle_layout(configuration))
+
         report(findings, options.fetch(:format))
         findings.any? { |f| f[:status] == :fail } ? 1 : 0
       rescue OptionParser::InvalidArgument => e
@@ -249,6 +249,46 @@ module Rigor
         File.expand_path(path)
       end
 
+      # ADR-25 carry-over — the plain `bundle install` layout. {Environment::BundleSigDiscovery} detects a
+      # bundle root only from paths the PROJECT records: `.bundle/config`'s `BUNDLE_PATH`, an in-tree
+      # `vendor/bundle`, or the user-global Bundler config. The default layout records none of those — the
+      # gems live in the active Ruby's `GEM_HOME`, which is a property of the project's toolchain, and
+      # ADR-27 keeps Rigor from running that toolchain to ask. So detection is not a bounded probe Rigor can
+      # add; what it CAN do is stop the state being silent. Without this the user sees gem-shipped `sig/`
+      # simply not taking effect, with nothing anywhere naming the reason.
+      #
+      # Warn, never fail: the layout is the Ruby default and is perfectly correct — only ~3% of gems ship
+      # `sig/` at all, so most projects lose nothing by it.
+      def check_bundle_layout(configuration)
+        return [] unless File.file?(File.join(Dir.pwd, "Gemfile.lock"))
+        return [] if resolved_bundle_root(configuration)
+
+        [
+          {
+            check: CHECK_BUNDLE_LAYOUT,
+            status: :warn,
+            message: "Gems are installed in the active Ruby's default gem home, which Rigor cannot locate — " \
+                     "no gem-shipped `sig/` is being discovered",
+            hint: "Rigor reads your project as data and never runs its toolchain, so it can only find a " \
+                  "bundle whose location the project records (`.bundle/config`'s `BUNDLE_PATH`, an in-tree " \
+                  "`vendor/bundle`, or your global Bundler config). Point it at the install root with " \
+                  "`bundler.bundle_path:` in `.rigor.yml`, run `bundle config set --local path vendor/bundle` " \
+                  "and reinstall, or supply signatures with `rbs collection install` instead."
+          }
+        ]
+      end
+
+      def resolved_bundle_root(configuration)
+        Environment::BundleSigDiscovery.resolve_bundle_path(
+          bundle_path: configuration.bundler_bundle_path,
+          project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect
+        )
+      rescue StandardError
+        # A doctor check must never be the thing that breaks the command it is diagnosing.
+        nil
+      end
+
       def check_baseline(configuration, result)
         path = configuration.baseline_path
         return [] if path.nil? || !File.exist?(path)
@@ -287,38 +327,45 @@ module Rigor
         parts.join(", ")
       end
 
-      def check_rails_plugins(configuration)
-        return [] unless rails_unconfigured?(configuration)
-
-        [
-          {
-            check: CHECK_RAILS,
-            status: :fail,
-            message: "Rails detected but no Rails plugins enabled",
-            hint: "Add Rails plugins (e.g. rigor-activerecord, rigor-actionpack) to " \
-                  "`.rigor.yml` `plugins:` so framework calls resolve."
-          }
-        ]
+      # ADR-96 WD2 — the plugin-gap advisory, read off each bundled plugin's `target_gems:` rather than the
+      # Rails-only tables it replaces. Per plugin, so a Rails app that enabled only `rigor-activerecord` now
+      # hears about the other seven; `:warn`, because declining a plugin is a legitimate choice and must not
+      # fail the command forever. The one `:fail` is today's behaviour generalised: the project depends on
+      # gems Rigor models and enables none of the plugins that model them, which is genuinely unconfigured.
+      # Both branches read the lockfile's `DEPENDENCIES` section, never its resolved graph: a transitive
+      # `minitest` or `i18n` rides along in nearly every Rails lock, and failing `doctor` on one would fail a
+      # correctly configured project.
+      def check_plugin_gap(configuration)
+        return [] if Configuration.discover.nil?
+
+        gaps = PluginGapAdvisory.gaps(project_root: Dir.pwd, plugins: configuration.plugins)
+        return [] if gaps.empty?
+
+        if PluginGapAdvisory.unconfigured?(project_root: Dir.pwd, plugins: configuration.plugins)
+          [unconfigured_plugin_finding(gaps)]
+        else
+          gaps.map { |gap| plugin_gap_finding(gap) }
+        end
       end
 
-      # True when Rails is in Gemfile.lock but the config enables no Rails plugin — the same probe {ProjectStateProbe}
-      # uses.
-      def rails_unconfigured?(_configuration)
-        config_path = Configuration.discover
-        return false if config_path.nil?
-        return false unless File.file?(config_path)
-
-        lock = File.join(Dir.pwd, "Gemfile.lock")
-        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
-
-        !file_mentions_any?(config_path, RAILS_PLUGIN_MARKERS)
+      def unconfigured_plugin_finding(gaps)
+        {
+          check: CHECK_PLUGIN_GAP,
+          status: :fail,
+          message: "#{gaps.size} bundled plugin(s) model gems this project depends on and none is enabled " \
+                   "(#{gaps.map(&:plugin_gem).join(', ')})",
+          hint: "Add the plugins for your stack to `.rigor.yml` `plugins:` so framework calls resolve."
+        }
       end
 
-      def file_mentions_any?(path, markers)
-        content = File.read(path)
-        markers.any? { |marker| content.include?(marker) }
-      rescue StandardError
-        false
+      def plugin_gap_finding(gap)
+        {
+          check: CHECK_PLUGIN_GAP,
+          status: :warn,
+          message: "#{gap.locked_gems.join(', ')} #{gap.locked_gems.one? ? 'is a dependency' : 'are dependencies'} " \
+                   "of this project and #{gap.plugin_gem} models it, but it is not enabled",
+          hint: "Add `#{gap.plugin_gem}` to `.rigor.yml` `plugins:`, or leave it out deliberately."
+        }
       end
 
       # Rigor is a tool, not a library (ADR-27): resolving it as one of the project's own dependencies pins the

data/lib/rigor/cli/effects_command.rb

@@ -41,7 +41,7 @@ module Rigor
     class EffectsCommand < Command
       USAGE = "Usage: rigor effects [options] [paths]"
 
-      # @return [Integer] CLI exit status: 0 on success, 1 on `check` drift, 64 on a usage error.
+      # @return CLI exit status: 0 on success, 1 on `check` drift, 64 on a usage error.
       def run
         verb = @argv.first
         return run_verb(verb) if EffectsSnapshotCommand::VERBS.include?(verb)
@@ -231,7 +231,7 @@ module Rigor
       # project does — still analyses it. Inside a project the argument is already under `paths:` and the
       # union is the configured set unchanged.
       #
-      # @return [Array(Rigor::Effects::EffectTable, Hash{String=>Array<String>})] the table, and which
+      # @return the table, and which
       #   file each unit was defined in — the map {EffectsReport} needs to answer a path argument.
       def analyze(configuration, scope)
         require_relative "../analysis/runner"

data/lib/rigor/cli/effects_diff_renderer.rb

@@ -50,12 +50,12 @@ module Rigor
       REGENERATION_CLOSING_LINE = "Run `rigor effects update` to regenerate the record under the current " \
                                   "rules."
 
-      # @param sources [Hash{String=>Array<String>}] `Runner#effect_sources` — where each unit is defined.
+      # @param sources — `Runner#effect_sources` — where each unit is defined.
       #   A drift row names `file:line` so a reviewer does not have to search for the method (#435). The
       #   file rides the cached summary entry and is free; the line is resolved by parsing the row's own
       #   file ({Effects::DefinitionLines}), which is why a fresh report — no rows — still parses nothing
       #   and the whole-project parse ADR-104 removed from this command stays removed.
-      # @param lines [Effects::DefinitionLines] seam for the specs; the default parses on demand.
+      # @param lines — seam for the specs; the default parses on demand.
       def initialize(out:, path:, sources: nil, lines: Effects::DefinitionLines.new)
         @out = out
         @path = path
@@ -121,7 +121,7 @@ module Rigor
       # method that no longer exists was not defined by it. Such a row renders exactly as it did before
       # this suffix existed.
       #
-      # @return [Array<Array(String, Integer)>] `[relative path, line]` per file, the line nil when that
+      # @return `[relative path, line]` per file, the line nil when that
       #   file spells the key with no `def` — an accessor, or a definition the nesting cannot name.
       def sources_of(symbol)
         Array(@sources[symbol]).map do |path|

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -51,7 +51,7 @@ module Rigor
         @verb = verb
       end
 
-      # @return [Integer] 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
+      # @return 0 fresh / written, 1 on drift under `check`, 64 on a usage error.
       def run
         options = parse_options
         return usage_error("unsupported format: #{options.fetch(:format)}") unless

data/lib/rigor/cli/explain_command.rb

@@ -4,6 +4,7 @@ require "json"
 require "optionparser"
 
 require_relative "../analysis/rule_catalog"
+require_relative "../sig_gen/skip_reason_catalog"
 require_relative "command"
 
 module Rigor
@@ -18,7 +19,7 @@ module Rigor
     class ExplainCommand < Command
       USAGE = "Usage: rigor explain [options] [<rule>]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
 
@@ -28,6 +29,12 @@ module Rigor
         end
 
         token = @argv.shift
+        skip_reason = SigGen::SkipReasonCatalog.resolve(token)
+        if skip_reason
+          render_skip_reason(skip_reason, options.fetch(:format))
+          return 0
+        end
+
         entries = Analysis::RuleCatalog.resolve(token)
         if entries.empty?
           @err.puts("Unknown rule: #{token}")
@@ -68,6 +75,32 @@ module Rigor
         @out.puts("")
         @out.puts("Run `rigor explain <rule>` for the full description.")
         @out.puts("Family wildcards (`call`, `flow`, `assert`, `dump`, `def`) print every rule under that prefix.")
+        @out.puts("")
+        @out.puts("`rigor sig-gen` skip reasons:")
+        @out.puts("")
+        SigGen::SkipReasonCatalog.all.each do |entry|
+          @out.puts("  #{entry.id.ljust(33)} #{entry.summary}")
+        end
+      end
+
+      def render_skip_reason(entry, format)
+        if format == "json"
+          @out.puts(JSON.pretty_generate(entry.to_h))
+          return
+        end
+
+        @out.puts(entry.id)
+        @out.puts("=" * entry.id.length)
+        @out.puts("")
+        @out.puts(entry.summary)
+        @out.puts("")
+        @out.puts("A `rigor sig-gen` skip reason, not a diagnostic rule: it reports a signature that was NOT")
+        @out.puts("written, so it has no severity and nothing to suppress.")
+        @out.puts("")
+        @out.puts(entry.explanation)
+        @out.puts("")
+        @out.puts("What to do:")
+        @out.puts("  #{entry.next_step}")
       end
 
       def render_entries(entries, format)

data/lib/rigor/cli/fused_protection_report.rb

@@ -12,7 +12,13 @@ module Rigor
     # Framing (ADR-63 / ADR-62 Criterion A, extended): the payload is the **attribution** — which protection axis is
     # missing — never raw survival. An unprotected site is "add protection here", never "your code is broken".
     # `harness_errors` (#264) — see {Rigor::CLI::FileEffectiveness}; defaults to 0 for the same reason.
-    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio, :harness_errors) do
+    # A `class ... < Data.define(...)` body, not the `Data.define(...) do ... end` shorthand: Steep
+    # resolves a `def` inside the shorthand block against the *lexically enclosing* class (here,
+    # `Rigor::CLI`, which declares its own differently-shaped `initialize`) rather than the anonymous
+    # Data subclass being defined — a `sig/` declaration for `FusedFileProtection` cannot fix this,
+    # since the misattribution happens before any signature is consulted. The explicit `class` keyword
+    # is a real namespace boundary Steep's block walker respects; behaviour is identical either way.
+    class FusedFileProtection < Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio, :harness_errors)
       def initialize(path:, type_killed:, test_killed:, unprotected:, ratio:, harness_errors: 0)
         super
       end

data/lib/rigor/cli/lsp_command.rb

@@ -15,7 +15,7 @@ module Rigor
     class LspCommand < Command
       USAGE = "Usage: rigor lsp [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options == :usage_error

data/lib/rigor/cli/mcp_command.rb

@@ -17,7 +17,7 @@ module Rigor
     class McpCommand < Command
       USAGE = "Usage: rigor mcp [options]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options == :usage_error