rigortype 0.2.9 → 0.3.1

data/lib/rigor/cli/annotate_command.rb

@@ -9,11 +9,13 @@ require_relative "../configuration"
 require_relative "options"
 require_relative "../environment"
 require_relative "../scope"
+require_relative "../source/node_children"
 require_relative "../inference/def_return_typer"
 require_relative "../inference/scope_indexer"
 require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
+require_relative "probe_environment"
 
 module Rigor
   class CLI
@@ -105,7 +107,7 @@ module Rigor
         # bindings, so a loop-body line annotates the joined widened type (`Integer`) rather than a stale
         # first-iterations constant (`1 | 2`).
         scope_index = Inference::ScopeIndexer.index(
-          parse_result.value, default_scope: base_scope(configuration),
+          parse_result.value, default_scope: base_scope(configuration, file),
                               converged_loop_recording: true
         )
         line_types = LineTypeCollector.new(scope_index).collect(parse_result.value)
@@ -128,12 +130,12 @@ module Rigor
         @out.puts(JSON.generate({ "annotations" => annotations }))
       end
 
-      def base_scope(configuration)
+      # The plugin-aware environment for the annotated file, so a `#=> <type>` matches what `rigor check`
+      # infers on that line — including types synthesized from the file's own inline RBS annotations (the file
+      # is threaded as the synthesizer's `source_files:`; see {ProbeEnvironment}).
+      def base_scope(configuration, file)
         Scope.empty(
-          environment: Environment.for_project(
-            libraries: configuration.libraries,
-            signature_paths: configuration.signature_paths
-          )
+          environment: ProbeEnvironment.build(configuration: configuration, source_files: [file])
         )
       end
 
@@ -247,14 +249,18 @@ module Rigor
             block.call(stmt)
           end
         else
-          node.compact_child_nodes.each { |child| each_statement(child, &block) }
+          node.rigor_each_child { |child| each_statement(child, &block) }
         end
       end
 
       # For a line no statement closes (the `if` / block header lines), fall back to the widest expression ending there.
+      # A hash-pair node (`1 => 2,` inside a multi-line literal / keyword-argument list) is not an expression — typing
+      # it only echoes the `Dynamic[top]` fallback — so those interior lines stay bare and the literal's type appears
+      # once, on the line the enclosing statement closes.
       def fill_uncovered_lines(program, by_line)
         widest_per_line(program).each do |line, node|
           next if by_line.key?(line)
+          next if node.is_a?(Prism::AssocNode) || node.is_a?(Prism::AssocSplatNode)
 
           type = node.is_a?(Prism::BlockParametersNode) ? block_params_type(node) : type_of(node)
           by_line[line] = type unless type.nil?
@@ -298,7 +304,7 @@ module Rigor
         return if node.nil?
 
         block.call(node)
-        node.compact_child_nodes.each { |child| walk(child, &block) }
+        node.rigor_each_child { |child| walk(child, &block) }
       end
 
       # Types the node through the flow evaluator (not the bare expression typer) under its recorded entry scope, so
@@ -331,7 +337,7 @@ module Rigor
         return if node.nil?
 
         block.call(node) if node.is_a?(Prism::DefNode)
-        node.compact_child_nodes.each { |child| each_def_node(child, &block) }
+        node.rigor_each_child { |child| each_def_node(child, &block) }
       end
     end
   end

data/lib/rigor/cli/baseline_command.rb

@@ -87,8 +87,11 @@ module Rigor
           "match-mode: #{options.fetch(:match_mode)})"
         )
         if configuration.baseline_path.nil?
+          # Name the config file that actually governs this project (`.rigor.dist.yml` when no local override
+          # exists), so the hint points at the file the user must edit.
+          config_name = options.fetch(:config) || Configuration.discover || ".rigor.yml"
           @err.puts(
-            "rigor: note — `.rigor.yml` does not declare `baseline:`; " \
+            "rigor: note — `#{config_name}` does not declare `baseline:`; " \
             "add `baseline: #{path}` to activate the suppression."
           )
         end

data/lib/rigor/cli/check_command.rb

@@ -8,12 +8,17 @@ require_relative "../configuration"
 require_relative "../config_audit"
 require_relative "../analysis/result"
 require_relative "../analysis/rule_catalog"
-require_relative "coverage_scan"
+# The baseline filter runs on EVERY exit path — including the ADR-87 WD4 cache-HIT fast path, which skips
+# `load_check_dependencies` — so it must be a load-time require. It pulls only YAML, never the engine.
+require_relative "../analysis/baseline"
+require_relative "../runtime/jit"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
-require_relative "ci_detector"
-require_relative "check_runner_factory"
+require_relative "../ci_detector"
+# ADR-87 WD4 — `coverage_scan` and `check_runner_factory` both pull the inference engine, so they are required
+# lazily (in `compute_coverage` / `build_check_runner`) rather than at load time: an ordinary check whose
+# result the run-cache probe serves must reach the hit verdict without `rigor/inference` in $LOADED_FEATURES.
 
 module Rigor
   class CLI
@@ -29,26 +34,43 @@ module Rigor
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize
-        load_check_dependencies
+      def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # Arm deferred YJIT enablement before any analysis work: the deadline
+        # thread only fires once a run outlasts the amortization window, so a
+        # short check finishes before it ever pays JIT compile cost while a
+        # long run JITs its dominant tail (Runtime::Jit).
+        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+        # 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
         buffer = Options.resolve_buffer_binding(options, err: @err)
         return CLI::EXIT_USAGE if buffer == :usage_error
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
+        conflict = parameter_inference_incremental_conflict(configuration, options)
+        return conflict unless conflict.nil?
+
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
+        # ADR-87 WD4 — try to serve the whole run from the ADR-45 cache before booting the engine. A hit boots
+        # only CLI + config + cache + digest code (no `rigor/inference`), skipping the plugin prepass + env
+        # build entirely.
+        probed = try_run_cache_hit(configuration, options, buffer, cache_root)
+        return finalize_cache_hit(probed, configuration, options, config_warnings) unless probed.nil?
+
+        load_check_dependencies
         special = dispatch_special_check_mode(configuration, options, cache_root)
         return special unless special.nil?
 
-        runner = build_check_runner(
+        invocation = invoke_check(
           configuration: configuration, options: options,
           buffer: buffer, cache_root: cache_root
         )
-        raw_result = runner.run(@argv.empty? ? configuration.paths : @argv)
+        runner = invocation.runner
+        raw_result = invocation.result
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
@@ -66,23 +88,113 @@ module Rigor
 
       private
 
+      # 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
+      # eligible; every other mode (below) declines so the full path handles it unchanged.
+      def try_run_cache_hit(configuration, options, buffer, cache_root)
+        return nil unless run_cache_hit_eligible?(configuration, options, buffer)
+
+        require_relative "../analysis/run_cache_probe"
+        Analysis::RunCacheProbe.new(
+          configuration: configuration, cache_root: cache_root, explain: options.fetch(:explain)
+        ).serve(@argv.empty? ? configuration.paths : @argv)
+      end
+
+      # The probe is eligible only for a run the ADR-45 result cache actually serves: a writable cache (not
+      # `--no-cache`), no editor buffer, sequential (pool runs are not result-cacheable), and no mode needing
+      # the engine (`--coverage` / `--incremental` / `--verify-incremental`) or the runner's own reporting
+      # (`--cache-stats`, the `RIGOR_*_TRACE` dev probes). A wrongly-permitted run still MISSES (the entry was
+      # never written its way) and falls through — the gate is an optimisation, never a soundness boundary.
+      def run_cache_hit_eligible?(configuration, options, buffer)
+        buffer.nil? &&
+          !options.fetch(:no_cache) && !options.fetch(:coverage) && !options.fetch(:cache_stats) &&
+          !options.fetch(:incremental) && !options.fetch(:verify_incremental) &&
+          !pool_workers_configured?(options, configuration) &&
+          ENV["RIGOR_BUDGET_TRACE"].to_s.empty? && ENV["RIGOR_HEAP_TRACE"].to_s.empty?
+      end
+
+      # Any signal that per-file analysis would run in a worker pool (CLI `--workers`, the env override, or the
+      # config default). Deliberately over-declines (a false positive only forgoes the fast lane); mirrors
+      # {CheckRunnerFactory.resolve_workers} without requiring it (that pulls in the engine).
+      def pool_workers_configured?(options, configuration)
+        cli = options[:workers]
+        return Integer(cli).positive? if cli
+
+        env = ENV.fetch("RIGOR_RACTOR_WORKERS", nil)
+        return Integer(env).positive? if env && !env.empty?
+
+        configuration.parallel_workers.positive?
+      rescue ArgumentError
+        false
+      end
+
+      # ADR-87 WD4 — the engine-free tail for a cache-served hit: baseline filter + output + exit code,
+      # mirroring the full path's tail but without stats (a hit collected none), trace appendices (they read
+      # engine counters), or eviction (deferred to the next miss). `raw_result` is pre-baseline so the strict
+      # 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)
+        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
+      end
+
+      # ADR-67 WD6c — `parameter_inference:` and the ADR-46 incremental modes are mutually exclusive in slice 1.
+      # The parameter table introduces cross-file edges (a caller's argument types drive a callee's body
+      # diagnostics) that the per-file dependency recorder does not yet carry, so a cached file whose parameter
+      # seeds changed would serve a stale result. Refuse with a message naming the ADR-46 gap rather than
+      # silently producing unsound incremental diagnostics; the edge wiring is the named follow-up. Returns the
+      # usage exit code on a conflict, or nil to proceed. `--verify-incremental` (the acceptance gate that runs
+      # incremental analysis) is caught here too.
+      def parameter_inference_incremental_conflict(configuration, options)
+        return nil unless configuration.parameter_inference
+        return nil unless options.fetch(:incremental) || options.fetch(:verify_incremental)
+
+        flag = options.fetch(:incremental) ? "--incremental" : "--verify-incremental"
+        @err.puts("rigor: parameter_inference: cannot combine with #{flag} — the call-site parameter table " \
+                  "introduces cross-file caller→callee edges the ADR-46 incremental dependency graph does not " \
+                  "yet record, so a cached file could serve a stale diagnostic. Run a full check (drop " \
+                  "#{flag}), or disable parameter_inference: for this run.")
+        CLI::EXIT_USAGE
+      end
+
       # ADR-46 — the two incremental-analysis check modes both fully handle the run and return an exit code (so `run`
       # short-circuits); returns nil for an ordinary check.
       def dispatch_special_check_mode(configuration, options, cache_root)
-        return run_verify_incremental(configuration) if options.fetch(:verify_incremental)
+        return run_verify_incremental(configuration, options, cache_root) if options.fetch(:verify_incremental)
         return run_incremental_check(configuration, options, cache_root) if options.fetch(:incremental)
 
         nil
       end
 
+      # ADR-85 WD1 — the persistent cache the incremental session threads into each internal Runner so plugin
+      # `#prepare` producers (the ADR-9/#74/ADR-60 WD3 record-and-validate caches) and the RBS environment serve
+      # from disk across processes / rechecks rather than recomputing every invocation. Honors `--no-cache` (nil
+      # = no store), mirroring {CheckRunnerFactory}. The whole-run ADR-45 result cache stays inert on these runs
+      # — `Runner#run_result_cacheable?` excludes `record_dependencies` / `analyze_only`.
+      def incremental_cache_store(configuration, options, cache_root)
+        return nil if options.fetch(:no_cache)
+
+        Cache::Store.new(root: cache_root, max_bytes: configuration.cache_max_bytes)
+      end
+
       # ADR-46 — the incremental-analysis acceptance gate. Runs a baseline analysis (recording cross-file dependencies),
       # then re-analyzes a representative subset of files and serves the rest from the per-file cache (the body tier),
       # and asserts the merged diagnostics are byte-identical to a full `--no-cache` analysis. A mismatch means the
       # incremental machinery would serve a stale — manufactured — diagnostic, the soundness failure this gate exists to
       # catch. Prints a one-line PASS (exit 0) or the differing diagnostics (exit 1).
-      def run_verify_incremental(configuration)
+      def run_verify_incremental(configuration, options, cache_root)
         paths = @argv.empty? ? nil : @argv
-        session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
+        # ADR-85 WD1 — thread the store so the gate also asserts the cache-served producer path stays
+        # byte-identical to the uncached full run (`verify_full_diagnostics` builds a nil-store runner).
+        session = Analysis::IncrementalSession.new(
+          configuration: configuration, paths: paths,
+          cache_store: incremental_cache_store(configuration, options, cache_root)
+        )
         session.baseline
         analyzed = session.analyzed_files
 
@@ -101,18 +213,30 @@ module Rigor
       # updated snapshot for the next invocation. Diagnostics are identical to a full run (the `--verify-incremental`
       # gate enforces this); the win is skipping per-file inference for unchanged files.
       def run_incremental_check(configuration, options, cache_root)
+        require_relative "check_runner_factory"
         paths = @argv.empty? ? nil : @argv
-        probe = Analysis::Runner.new(configuration: configuration, cache_store: nil)
-        files = paths ? probe.analysis_file_set(paths) : probe.analysis_file_set
         fingerprint = Cache::IncrementalSnapshot.fingerprint(
           configuration: configuration, roots: paths || configuration.paths
         )
         snapshot = Cache::IncrementalSnapshot.new(root: cache_root)
-        session = Analysis::IncrementalSession.new(configuration: configuration, paths: paths)
+        store = incremental_cache_store(configuration, options, cache_root)
+        session = Analysis::IncrementalSession.new(
+          configuration: configuration, paths: paths,
+          cache_store: store,
+          # ADR-46 — thread the same worker-count precedence the standard `check` path uses
+          # (CLI `--workers` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > 0) so the recheck's closure
+          # re-analysis parallelises; the fork pool marshals dependency records back so the graph is sound.
+          workers: CheckRunnerFactory.resolve_workers(options, configuration)
+        )
 
         diagnostics, warm = session.run_incremental(snapshot: snapshot, fingerprint: fingerprint)
+        # The banner's file count comes from the session's analyzed set (cold analyses all; a warm recheck's
+        # `@analyzed` advances to the current file set), so a dedicated probe Runner + `Dir.glob` is no longer
+        # built just to size the banner (recon §3 — the analysis tree was expanded three times per recheck).
         @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
-                  "(#{files.size} files)")
+                  "(#{session.analyzed_files.size} files)")
+        emit_incremental_fact_surface_notes(session)
+        write_incremental_cache_stats(session, cache_root, store) if options.fetch(:cache_stats)
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
@@ -120,6 +244,40 @@ module Rigor
         result.success? ? 0 : 1
       end
 
+      # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
+      # value, or an `incremental_state_fingerprint` hook) forced a full run: either it CHANGED since the
+      # snapshot (a Sorbet sig edit, a schema change) or a contributing plugin declares NO fingerprint surface
+      # (opaque — a full run every invocation). Both are the sound direction; the note explains why a recheck
+      # was not warm.
+      def emit_incremental_fact_surface_notes(session)
+        opaque = session.opaque_plugin_ids
+        unless opaque.empty?
+          @err.puts("rigor: --incremental plugin#{'s' unless opaque.size == 1} #{opaque.sort.join(', ')} " \
+                    "contribute call-site types with no incremental fingerprint surface; the snapshot cannot " \
+                    "be reused (full analysis every run).")
+        end
+        return unless session.fact_surface_invalidated? && opaque.empty?
+
+        @err.puts("rigor: --incremental plugin fact surface changed since the snapshot; ran a full analysis.")
+      end
+
+      # ADR-88 WD1 — `--incremental --cache-stats` surfaces the on-disk cache inventory (as a plain `check`
+      # does) plus the fact-surface status line, so an operator can see whether a full run was fact-surface
+      # driven. The plain `check` cache-stats path is bypassed by the incremental short-circuit, so it is
+      # emitted here.
+      def write_incremental_cache_stats(session, cache_root, store)
+        write_cache_stats(cache_root, store)
+        status =
+          if !session.opaque_plugin_ids.empty?
+            "opaque (#{session.opaque_plugin_ids.sort.join(', ')})"
+          elsif session.fact_surface_invalidated?
+            "changed — snapshot invalidated"
+          else
+            "unchanged"
+          end
+        @out.puts("  plugin fact surface: #{status}")
+      end
+
       def verify_full_diagnostics(configuration, paths)
         runner = Analysis::Runner.new(configuration: configuration, cache_store: nil)
         (paths ? runner.run(paths) : runner.run).diagnostics
@@ -226,10 +384,16 @@ module Rigor
         @err.puts("rigor: #{silenced_count} diagnostic(s) silenced by baseline #{baseline_path}")
       end
 
-      def build_check_runner(configuration:, options:, buffer:, cache_root:)
-        CheckRunnerFactory.build(
+      # The primary check run, routed through the shared {CheckInvocation} entry point so `rigor doctor` and
+      # `rigor skill describe --deep` reach a result through this exact path rather than re-deriving it (#148).
+      # Required lazily for the reason the old inline `CheckRunnerFactory.build` was: it pulls the inference engine,
+      # and ADR-87 WD4's cache-hit fast path must reach its verdict without it.
+      def invoke_check(configuration:, options:, buffer:, cache_root:)
+        require_relative "check_invocation"
+        CheckInvocation.run(
           configuration: configuration, options: options,
-          buffer: buffer, cache_root: cache_root
+          buffer: buffer, cache_root: cache_root,
+          paths: @argv.empty? ? nil : @argv
         )
       end
 
@@ -391,7 +555,10 @@ module Rigor
       end
 
       def inject_treat_all_as_inline_rbs(entries)
-        filtered = entries.reject { |entry| rigor_rbs_inline_entry?(entry) }
+        # Single-homed with the WD2 auto-wire gate (`Configuration.rbs_inline_plugin_entry?`) so the flag and
+        # the default agree on what "already listed" means; a pre-existing entry is removed so this one's
+        # `require_magic_comment: false` wins unconditionally.
+        filtered = entries.reject { |entry| Configuration.rbs_inline_plugin_entry?(entry) }
         filtered + [{
           "gem" => "rigor-rbs-inline",
           "id" => "rbs-inline",
@@ -399,18 +566,6 @@ module Rigor
         }]
       end
 
-      def rigor_rbs_inline_entry?(entry)
-        case entry
-        when String
-          entry == "rigor-rbs-inline"
-        when Hash
-          string_keyed = entry.to_h { |k, v| [k.to_s, v] }
-          string_keyed["gem"] == "rigor-rbs-inline" || string_keyed["id"] == "rbs-inline"
-        else
-          false
-        end
-      end
-
       def handle_clear_cache(cache_root)
         if File.directory?(cache_root)
           FileUtils.rm_rf(cache_root)
@@ -451,6 +606,42 @@ module Rigor
         @err.puts("  recursion-fixpoint-cap hits: #{counts[Inference::BudgetTrace::RECURSION_FIXPOINT_CAP]}")
         @err.puts("  block-writeback-cap hits:  #{counts[Inference::BudgetTrace::BLOCK_WRITEBACK_CAP]}")
         write_budget_distributions
+        write_memo_profile(counts)
+      end
+
+      # Dumps the ADR-57 return-memo profile (WD0). Entries / hit rate / body evals / the non-store split, then
+      # the top signatures by body-eval count with their distinct-memo-key counts — the evidence for choosing
+      # between a finalization-aware taint gate and memo-key normalization. `--workers 0` for exact counts.
+      def write_memo_profile(counts)
+        bt = Inference::BudgetTrace
+        hits = counts[bt::MEMO_HITS]
+        misses = counts[bt::MEMO_MISSES]
+        consults = hits + misses
+        rate = consults.positive? ? format("%.1f%%", 100.0 * hits / consults) : "n/a"
+        @err.puts("")
+        @err.puts("Return-memo profile (RIGOR_BUDGET_TRACE; --workers 0 for an exact count)")
+        @err.puts("  infer entries:   #{counts[bt::MEMO_ENTRIES]}")
+        @err.puts("  memo consults:   #{consults}  (hits #{hits} / misses #{misses}; hit rate #{rate})")
+        @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
+
+      # Top 15 signatures by body-eval (compute) count, each with its distinct-memo-key count — a signature
+      # whose distinct-key count dwarfs its evals is arg-granularity thrash (the key-normalization candidate).
+      def write_memo_signature_table
+        bt = Inference::BudgetTrace
+        evals = bt.distribution(bt::MEMO_BODY_EVAL_BY_SIGNATURE)
+        return if evals.empty?
+
+        keys = bt.distribution(bt::MEMO_DISTINCT_KEY_BY_SIGNATURE)
+        @err.puts("  top signatures by body-eval count (evals / distinct-keys / signature):")
+        evals.sort_by { |sig, n| [-n, sig] }.first(15).each do |sig, n|
+          @err.puts("    #{n.to_s.rjust(8)}  #{keys.fetch(sig, 0).to_s.rjust(6)}  #{sig}")
+        end
       end
 
       # Dumps the read-only size distributions (ADR-41 Slice 2a). These observe how large unions actually get, with no
@@ -488,7 +679,6 @@ module Rigor
       def load_check_dependencies
         require_relative "../analysis/runner"
         require_relative "../analysis/buffer_binding"
-        require_relative "../analysis/baseline"
         require_relative "../cache/store"
         start_heap_trace_if_requested
       end
@@ -625,6 +815,7 @@ module Rigor
       def compute_coverage(runner, configuration, options)
         return nil unless options.fetch(:coverage)
 
+        require_relative "coverage_scan"
         files = @argv.empty? ? runner.analysis_file_set : runner.analysis_file_set(@argv)
         CoverageScan.precision_report(files: files, configuration: configuration)
       end
@@ -682,7 +873,7 @@ module Rigor
         return unless options.fetch(:ci_detect)
         return unless options.fetch(:format) == "text"
 
-        platform = CLI::CiDetector.detect
+        platform = CiDetector.detect
         return if platform.nil?
 
         if platform.native_stdout?

data/lib/rigor/cli/check_invocation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # The one place a CLI command turns a loaded {Configuration} into an {Analysis::Result}.
+    #
+    # {CheckRunnerFactory} builds the runner; this module owns the *invocation* wrapped around it — resolving the
+    # analysed paths, running, and handing back both the runner (`rigor check`'s reporting tail still needs its cache
+    # store and stats) and the raw result. It exists so a non-`check` command — `rigor doctor`, `rigor skill describe
+    # --deep` — reaches a check result through the same code path `rigor check` walks, instead of re-deriving the
+    # plumbing (issue #148; ADR-73 § "Field-trial follow-ups" names the shared helper as the prerequisite).
+    #
+    # Nothing here is required at load time: {CheckRunnerFactory} pulls the inference engine, so both entry points
+    # require it lazily. A command that merely *mentions* this module therefore stays engine-free until it actually
+    # runs an analysis — the property ADR-87 WD4 protects for `rigor check`'s cache-hit fast path, and the property
+    # that keeps an un-flagged `rigor skill describe` from loading the engine at all.
+    module CheckInvocation
+      # A completed analysis. `runner` is exposed because `rigor check`'s tail reads its `cache_store` (eviction,
+      # `--cache-stats`) and feeds it to `--coverage`; `result` is the raw, pre-baseline-filter {Analysis::Result}.
+      Invocation = Data.define(:runner, :result)
+
+      # 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.
+        def ran?
+          !result.nil?
+        end
+      end
+
+      # Options for a caller that wants a check *result* rather than a check *run*: no cache writes, no explain
+      # traces, sequential. `stats: true` because the RBS-environment signal (`stats.rbs_classes_total`) lives there.
+      # This is `rigor doctor`'s preset — a diagnostic command that must not churn the project's cache.
+      READ_ONLY_OPTIONS = { no_cache: true, explain: false, stats: true, workers: 0 }.freeze
+
+      # Options for an opt-in deep probe (`rigor skill describe --deep`). Unlike {READ_ONLY_OPTIONS} this uses the
+      # configured cache and worker count, i.e. it behaves exactly like `rigor check` — fast on a warm cache, and it
+      # WRITES `.rigor/cache`. That side effect is the whole reason the flag is opt-in.
+      DEEP_OPTIONS = { no_cache: false, explain: false, stats: true, workers: nil }.freeze
+
+      module_function
+
+      # 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]
+      def run(configuration:, options:, paths: nil, buffer: nil, cache_root: nil)
+        require_relative "check_runner_factory"
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: options,
+          buffer: buffer,
+          cache_root: cache_root || configuration.cache_path
+        )
+        Invocation.new(runner: runner, result: runner.run(paths || configuration.paths))
+      end
+
+      # Best-effort variant for a *routing* caller: one that wants to sharpen a recommendation with check evidence and
+      # has a perfectly good answer when there is none. Loads the configuration itself and converts every way the run
+      # can fail outright — an unreadable / invalid config, an unloadable plugin, an engine error — into an {Outcome}
+      # carrying a short human-readable `error`. It never raises and never fabricates a clean result.
+      #
+      # Deliberately broad: the caller's contract is "degrade to the presence-only answer, whatever went wrong". A
+      # 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]
+      def attempt(config_path: nil, options: DEEP_OPTIONS, paths: nil)
+        require_relative "../configuration"
+        configuration = Configuration.load(config_path)
+        Outcome.new(result: run(configuration: configuration, options: options, paths: paths).result, error: nil)
+      rescue StandardError, LoadError => e
+        Outcome.new(result: nil, error: "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}")
+      end
+    end
+  end
+end

data/lib/rigor/cli/coverage_command.rb

@@ -14,6 +14,7 @@ require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
 require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
+require_relative "../runtime/jit"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
@@ -53,7 +54,11 @@ module Rigor
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
       # @return [Integer] CLI exit status.
-      def run
+      def run # rubocop:disable Metrics/AbcSize
+        # Arm deferred YJIT enablement (Runtime::Jit): a scan long enough to
+        # amortize JIT compile cost enables mid-flight; a short one finishes
+        # first and never pays it. Same seam as `rigor check`.
+        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
         return with_tests_misuse_error if options[:with_tests] && !options[:mutation]

data/lib/rigor/cli/docs_command.rb

@@ -20,9 +20,6 @@ module Rigor
     #
     # `<name>` resolves a category-qualified path (`handbook/03-narrowing`), a prefixed basename (`03-narrowing`), or a
     # short name (`narrowing`, when it is unique across categories).
-    #
-    # The pre-v0.3.0 verb spellings `rigor docs list` / `rigor docs path <name>` still work but emit a stderr
-    # deprecation notice; they are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI deprecations").
     class DocsCommand < Command
       USAGE = <<~USAGE
         Usage: rigor docs [<name>] [--path <name>] [--list [<category>]]
@@ -46,10 +43,6 @@ module Rigor
           rigor docs editor-integration
           rigor docs --path 17-driving-improvement
           rigor docs --list handbook
-
-        Deprecated (removed in v0.3.0) — use the flags above:
-          rigor docs list           ->  rigor docs --list
-          rigor docs path <name>    ->  rigor docs --path <name>
       USAGE
 
       # The bundled docs live at `<gem_root>/docs/`. From `lib/rigor/cli/docs_command.rb` that is three directories up.
@@ -58,18 +51,8 @@ module Rigor
       HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
       LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
 
-      # 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" },
-        "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_index
@@ -92,19 +75,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 docs: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
-          "#{LEGACY_VERB_REMOVAL}; use `rigor docs #{spec.fetch(:advice)}` instead."
-        )
-        @argv[0] = spec.fetch(:flag)
-      end
-
       def run_index
         if File.file?(LLMS_INDEX)
           @out.write(File.read(LLMS_INDEX))