rigortype 0.3.8 → 0.4.0

data/lib/rigor/cli/sig_gen_command.rb

@@ -3,6 +3,8 @@
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "../effects/config_envelopes"
+require_relative "../effects/registry"
 require_relative "options"
 require_relative "../sig_gen"
 require_relative "command"
@@ -22,24 +24,30 @@ module Rigor
     # AND the candidate is a `tighter-return`.
     #
     # Parameter policy defaults to `untyped`. `--params=observed` (slice 3) opts in to caller-side observation
-    # harvesting: the `ObservationCollector` walks `--observe=PATH...` (default `spec/` when no flag is given AND a
-    # `spec/` directory exists), unions per-position arg types, and the generator emits the union per ADR-5 clause 2.
+    # harvesting: the `ObservationCollector` walks `--observe=PATH...` (default: the project's test roots,
+    # {Configuration#resolved_test_paths}), unions per-position arg types, and the generator emits the union per ADR-5
+    # clause 2.
     # `--params=observed-strict` stays reserved-but-inert until the capability-role catalog ships (rejected with a usage
     # error so the surface stays stable).
-    class SigGenCommand < Command
+    #
+    # `--check` (ADR-112 WD4) is the CI freshness gate: it runs the `--write` merge with every other flag as given,
+    # writes nothing, prints what would change, and exits 1 when anything would.
+    class SigGenCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor sig-gen [options] [paths]"
 
-      VALID_MODES = %w[print diff write].freeze
+      VALID_MODES = %w[print diff write check].freeze
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
-      # The skip reasons {#report_skipped} counts. The two left out each have a detailed report of their own
-      # ({#report_unrenderable}, {#report_unresolvable_superclasses}), so a method never shows up in two tallies.
+      # The skip reasons {#report_skipped} counts. The four left out each have a report of their own
+      # ({#report_unrenderable}, {#report_unresolvable_superclasses}, {#report_inline_declared}, and the refusal
+      # lines `--write` / `--check` print for `inline_differs`), so a method never shows up in two tallies.
       SUMMARISED_SKIP_REASONS = (SigGen::Classification::SKIP_DIAGNOSTIC_IDS.keys -
-                                 %i[unrenderable_rbs unresolvable_superclass]).freeze
+                                 %i[unrenderable_rbs unresolvable_superclass inline_declared
+                                    inline_differs]).freeze
       private_constant :SUMMARISED_SKIP_REASONS
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         return CLI::EXIT_USAGE if options.nil?
@@ -50,17 +58,22 @@ module Rigor
         observations = collect_observations(configuration, options)
         generator = SigGen::Generator.new(configuration: configuration, paths: paths,
                                           observations: observations,
-                                          include_private: options.fetch(:include_private))
+                                          include_private: options.fetch(:include_private),
+                                          effect_annotator: effect_annotator(configuration, paths, options),
+                                          overwrite: options.fetch(:overwrite))
         candidates = generator.run
         mode = options.fetch(:mode).to_sym
 
-        status = if mode == :write
-                   dispatch_write(candidates, configuration, options)
+        status = case mode
+                 when :write then dispatch_write(candidates, configuration, options)
+                 when :check then dispatch_check(candidates, configuration, options)
                  else
                    dispatch_print_or_diff(candidates, mode, options)
                    0
                  end
         report_skipped(candidates, options)
+        report_inline_declared(candidates, options)
+        report_withheld_annotations(candidates, options)
         report_unrenderable(generator.unrenderable)
         report_unresolvable_superclasses(generator.unresolvable_superclasses)
         status
@@ -68,6 +81,74 @@ module Rigor
 
       private
 
+      # ADR-103 WD9 — the effect table sig-gen writes annotations from, or `nil`.
+      #
+      # The gate is the project's own `effects:` opt-in and nothing else. An annotation is read back as an
+      # enforced envelope, so turning emission on from a sig-gen flag alone would let one command commit a
+      # project to a contract `rigor check` was never asked to keep; and a project that has not opted in
+      # pays neither the analysis this needs nor a single changed byte of output.
+      #
+      # `--effect-envelopes` is the second, narrower switch: `%a{pure}` is the ecosystem's existing purity
+      # spelling and round-trips through Steep as well as Rigor, while `%a{rigor:v1:effect …}` is Rigor's
+      # own and belongs in a project's `sig/` only when the author asked for it by name.
+      def effect_annotator(configuration, paths, options)
+        unless configuration.effects_enabled?
+          if options.fetch(:effect_envelopes)
+            @err.puts("rigor sig-gen: --effect-envelopes needs the `effects:` opt-in in .rigor.yml; " \
+                      "no effect annotation was emitted.")
+          end
+          return nil
+        end
+
+        require_relative "check_runner_factory"
+        # Through the same factory `rigor check` and `rigor doctor` use, so the LRU cap, the worker
+        # resolution and the tolerated-effects switch cannot drift from the command whose cache this run
+        # shares. `workers: 0` because a collecting run is pinned to the sequential path anyway, and
+        # `--no-cache` mirrors `rigor check`'s flag of the same name.
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: { no_cache: options.fetch(:no_cache), explain: false, stats: false, workers: 0 },
+          buffer: nil, cache_root: configuration.cache_path
+        )
+        runner.run((configuration.paths + paths).uniq)
+        SigGen::EffectAnnotation::Annotator.new(
+          table: runner.effect_table, envelopes: options.fetch(:effect_envelopes),
+          envelope_index: runner.effect_envelopes, config_envelopes: config_envelopes(configuration)
+        )
+      end
+
+      # The project's `effects.envelopes:` entries, for gate 0's `match:` half. Built with a plain
+      # registry rather than the run's: gate 0 asks only WHETHER an entry selects this class, never what
+      # it bounds, so the vocabulary a plugin would add cannot change the answer.
+      def config_envelopes(configuration)
+        Effects::ConfigEnvelopes.build(
+          entries: configuration.effects_envelopes,
+          registry: Effects::Registry.for_configuration(configuration)
+        )
+      rescue StandardError
+        []
+      end
+
+      # The withheld half of the emission, counted the way {#report_skipped} counts a skip: a method that
+      # did NOT get `%a{pure}` is the interesting case for a reader who expected one, and silence would
+      # read as "sig-gen does not do this" rather than "this method did not earn it".
+      def report_withheld_annotations(candidates, options)
+        return unless options.fetch(:format) == "text"
+
+        counts = candidates.each_with_object(Hash.new(0)) do |candidate, acc|
+          reason = candidate.effect_reason
+          acc[reason] += 1 if reason && reason != :emitted
+        end
+        return if counts.empty?
+
+        breakdown = counts.map { |reason, n| "#{SigGen::EffectAnnotation::DIAGNOSTIC_IDS.fetch(reason)}: #{n}" }
+        @err.puts(
+          "rigor sig-gen: withheld an effect annotation from #{counts.values.sum} method(s) " \
+          "(#{breakdown.join(', ')}). An annotation is enforced once written, so it is emitted only " \
+          "from an exhaustive, undischarged summary."
+        )
+      end
+
       # Issue #778 — one stderr line per run saying how many methods the generator declined and why, so a
       # method missing from the output is never a silent absence. Text mode only: under `--format=json` every
       # skipped row is already in the payload with its `skip_reason`, and stderr stays clean for the consumer.
@@ -90,6 +171,18 @@ module Rigor
         )
       end
 
+      # ADR-112 WD4 — `sig_gen.inline_declared: skip` leaving methods out is the project's own choice, not a
+      # method sig-gen "could not type or would not overwrite", so it is counted on a line of its own.
+      def report_inline_declared(candidates, options)
+        return unless options.fetch(:format) == "text"
+
+        count = candidates.count { |c| c.skip_reason == :inline_declared }
+        return if count.zero?
+
+        @err.puts("rigor sig-gen: left #{count} method(s) declared inline out of sig/, as " \
+                  "`sig_gen.inline_declared: skip` asks (sig.skipped.inline-declared).")
+      end
+
       # 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.
@@ -135,32 +228,101 @@ module Rigor
         )
       end
 
-      # @return [Integer] exit status — non-zero when a file the user asked to write could not be written.
+      # @return 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)
-        writer = SigGen::Writer.new(path_mapper: path_mapper, overwrite: options.fetch(:overwrite))
-
-        results = writer.write_all(candidates)
+        results = build_writer(configuration, options).write_all(candidates)
 
-        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
-        # A refused write (an assembled file that does not parse, or an existing target that is not valid
-        # UTF-8) means 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.
+        refused = refused_candidates(candidates)
+        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format), refused: refused)
+        SigGen::Renderer.refusal_lines(refused).each { |line| @err.puts(line) }
+        # A refused write (an assembled file that does not parse, an existing target that is not valid UTF-8,
+        # or a method whose inline and `sig/` declarations disagree without `--overwrite`) means 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.
         refusals = %i[skipped_invalid_rbs skipped_invalid_encoding]
-        results.any? { |result| refusals.include?(result.action) } ? 1 : 0
+        results.any? { |result| refusals.include?(result.action) } || !refused.empty? ? 1 : 0
+      end
+
+      # ADR-112 WD4 — the methods whose inline and `sig/` declarations disagree, refused because the run did not
+      # pass `--overwrite`. Unlike every other skip, `sig/` contradicts the source while one stands.
+      def refused_candidates(candidates)
+        candidates.select { |candidate| candidate.skip_reason == :inline_differs }
+      end
+
+      # ADR-112 WD4 — the same writer as {#dispatch_write}, flags included, in dry-run mode. Defined by what
+      # `--write` would do rather than by whether `--diff` prints anything: a tighter return against an existing
+      # declaration is a proposal `--write` declines without `--overwrite`, and a gate that counted it could
+      # never pass on a project that reviewed it and said no. With `--overwrite` it counts, because `--write
+      # --overwrite` would apply it.
+      #
+      # @return 1 when `sig/` is out of date (or a write would be refused), 0 when it is current.
+      def dispatch_check(candidates, configuration, options)
+        results = build_writer(configuration, options, dry_run: true).write_all(candidates)
+        refused = refused_candidates(candidates)
+        SigGen::Renderer.new(out: @out).render_check(results: results, format: options.fetch(:format),
+                                                     refused: refused)
+        stale = SigGen::Renderer.out_of_date(results)
+        return 0 if stale.empty? && refused.empty?
+
+        report_check_failure(stale, refused) if options.fetch(:format) == "text"
+        1
+      end
+
+      def report_check_failure(stale, refused)
+        unless stale.empty?
+          @err.puts("rigor sig-gen --check: #{stale.size} signature file(s) out of date; " \
+                    "run `rigor sig-gen --write` with the same options to update them.")
+        end
+        return if refused.empty?
+
+        @err.puts("rigor sig-gen --check: #{refused.size} method(s) whose inline declaration and sig/ copy " \
+                  "disagree; make them agree, or pass --overwrite to replace the sig/ member.")
+      end
+
+      def build_writer(configuration, options, dry_run: false)
+        layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
+        path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)
+        SigGen::Writer.new(path_mapper: path_mapper, overwrite: options.fetch(:overwrite), dry_run: dry_run)
       end
 
       # Slice 3 — collect call-site argument observations when `--params=observed` is set. When `--observe=PATH` is not
-      # specified, default to `spec/` (skipped silently when the directory is absent).
+      # specified, observe the project's test roots: `test_paths:`, or whichever of `spec/` and `test/` exist. With no
+      # root at all the run still succeeds, but says so — otherwise every parameter stays `untyped` with nothing
+      # naming the reason.
       def collect_observations(configuration, options)
         return {} if options.fetch(:params) != "observed"
 
         observe_paths = options.fetch(:observe)
-        observe_paths = ["spec"] if observe_paths.empty? && File.directory?("spec")
+        observe_paths = configuration.resolved_test_paths if observe_paths.empty?
+        if observe_paths.empty?
+          warn_no_test_roots(configuration)
+        else
+          warn_missing_test_roots(observe_paths)
+        end
         SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths).collect
       end
 
+      # A declared root that does not exist is read as empty, so name it: `sig-gen` is the only command that reads
+      # the test roots, and without this the run looks exactly like one whose tests pass no typed arguments.
+      def warn_missing_test_roots(observe_paths)
+        missing = observe_paths.reject { |path| File.exist?(path) }
+        return if missing.empty?
+
+        consequence = missing.size == observe_paths.size ? "; every parameter stays untyped" : ""
+        @err.puts("rigor sig-gen: no call sites are observed from #{missing.map(&:inspect).join(', ')}, " \
+                  "which does not exist#{consequence}. Check `test_paths:` or --observe=PATH.")
+      end
+
+      def warn_no_test_roots(configuration)
+        reason = if configuration.test_paths.nil?
+                   "no spec/ or test/ directory was found and `test_paths:` is unset"
+                 else
+                   "`test_paths:` is empty"
+                 end
+        @err.puts("rigor sig-gen: --params=observed has no test roots to observe (#{reason}); every parameter " \
+                  "stays untyped. Declare `test_paths:` in the configuration or pass --observe=PATH.")
+      end
+
       def parse_options
         options = {
           mode: "print",
@@ -170,6 +332,8 @@ module Rigor
           overwrite: false,
           observe: [],
           include_private: false,
+          effect_envelopes: false,
+          no_cache: false,
           config: nil
         }
         build_option_parser(options).parse!(@argv)
@@ -181,23 +345,33 @@ module Rigor
         nil
       end
 
-      def build_option_parser(options) # rubocop:disable Metrics/AbcSize
+      def build_option_parser(options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
           opts.banner = USAGE
-          opts.on("--print", "Write RBS skeletons to stdout (default)") { options[:mode] = "print" }
-          opts.on("--diff", "Write a unified diff against existing RBS") { options[:mode] = "diff" }
-          opts.on("--write", "Write generated RBS to sig/<path>.rbs files") { options[:mode] = "write" }
-          opts.on("--overwrite", "Allow tighter-return updates to replace user-authored RBS") do
+          opts.on("--print", "Write RBS skeletons to stdout (default)") { select_mode(options, "print") }
+          opts.on("--diff", "Write a unified diff against existing RBS") { select_mode(options, "diff") }
+          opts.on("--write", "Write generated RBS to sig/<path>.rbs files") { select_mode(options, "write") }
+          opts.on("--check", "Exit 1 when --write would change sig/; write nothing") { select_mode(options, "check") }
+          opts.on("--overwrite", "Allow tighter-return updates, and inline declarations that disagree with sig/, " \
+                                 "to replace user-authored RBS") do
             options[:overwrite] = true
           end
           opts.on("--include-private", "Emit private / protected instance methods (default: public only)") do
             options[:include_private] = true
           end
+          opts.on("--effect-envelopes", "Also emit %a{rigor:v1:effect ...} for effectful methods " \
+                                        "(requires the effects: opt-in)") do
+            options[:effect_envelopes] = true
+          end
+          opts.on("--no-cache", "Do not read or write the analysis cache (effect collection only)") do
+            options[:no_cache] = true
+          end
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
           opts.on("--params=POLICY", "Parameter policy: untyped (default), observed, observed-strict") do |value|
             options[:params] = value
           end
-          opts.on("--observe=PATH", "Directory / file to scan for call-site observations (repeatable)") do |value|
+          opts.on("--observe=PATH", "Directory / file to scan for call-site observations (repeatable; " \
+                                    "default: the configured test_paths)") do |value|
             options[:observe] << value
           end
           opts.on("--new-files", "Emit only new-file classifications") do
@@ -213,12 +387,19 @@ module Rigor
         end
       end
 
+      # A second, different mode flag is a usage error rather than last-one-wins: `--check --write` must not
+      # quietly write in a CI job that meant to gate, nor `--write --check` quietly not.
+      def select_mode(options, mode)
+        options[:mode] = options[:mode_given] && options[:mode] != mode ? "conflict" : mode
+        options[:mode_given] = true
+      end
+
       def validation_error(options)
         mode = options.fetch(:mode)
         format = options.fetch(:format)
         params = options.fetch(:params)
 
-        return "--print, --diff, and --write are mutually exclusive flags; pick one" unless VALID_MODES.include?(mode)
+        return "--print, --diff, --write, and --check are mutually exclusive flags; pick one" if mode == "conflict"
         return "unsupported --format=#{format}" unless VALID_FORMATS.include?(format)
         return "unsupported --params=#{params}" unless VALID_PARAM_POLICIES.include?(params)
         if params == "observed-strict"

data/lib/rigor/cli/skill_command.rb

@@ -74,9 +74,9 @@ module Rigor
 
       # 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__)
+      SKILLS_ROOT = File.expand_path("../../../skills", __dir__).freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         case @argv.first
         when nil

data/lib/rigor/cli/skill_deep_probe.rb

@@ -37,22 +37,22 @@ module Rigor
       #   that could not run is NOT a clean check and the report must never let it read as one.
       # - `route` / `reason` — the headline override, or nil to leave the presence-only recommendation standing.
       Report = Data.define(:status, :detail, :route, :reason) do
-        # @return [Boolean] true when the check did not complete — the caller must then say so rather than let the
+        # @return true when the check did not complete — the caller must then say so rather than let the
         #   fallback recommendation read as an all-clear.
         def failed?
           status == :error
         end
       end
 
-      # @param config [String, nil] the config filename the presence probe found, relative to `root`.
-      # @param root [String] project root (the analysis itself resolves paths against the process cwd, as
+      # @param config — the config filename the presence probe found, relative to `root`.
+      # @param root — project root (the analysis itself resolves paths against the process cwd, as
       #   `rigor check` does).
       def initialize(config:, root: Dir.pwd)
         @config = config
         @root = root
       end
 
-      # @return [Report] never raises — every failure degrades to a `:error`/`:skipped` report whose `route` is nil,
+      # @return never raises — every failure degrades to a `:error`/`:skipped` report whose `route` is nil,
       #   leaving the presence-only headline in charge.
       def run
         if @config.nil?

data/lib/rigor/cli/skill_describe.rb

@@ -2,6 +2,8 @@
 
 require "yaml"
 
+require_relative "../plugin_gap_advisory"
+
 module Rigor
   class CLI
     # The presence-only project-state probe behind `rigor skill describe` (ADR-73 WD2). It stats files and opens only
@@ -17,19 +19,11 @@ module Rigor
       # RBS into the signature paths, so its presence is the signal that the gem-RBS gap has been addressed.
       RBS_COLLECTION_LOCKFILE = "rbs_collection.lock.yaml"
 
-      # `Gemfile.lock` substrings that mark a Rails app, and the bundled Rails-family plugin ids — used to spot a
-      # configured Rails project that has not enabled any Rails plugin (a `rigor-plugin-tune` cue).
-      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
-
       def initialize(root)
         @root = root
       end
 
-      # @return [Hash] the presence-only state the recommendation routes on.
+      # @return the presence-only state the recommendation routes on.
       def to_h
         config = CONFIG_FILENAMES.find { |name| File.file?(File.join(@root, name)) }
         {
@@ -38,7 +32,7 @@ module Rigor
           sig: File.directory?(File.join(@root, "sig")),
           gems: File.file?(File.join(@root, "Gemfile.lock")),
           rbs_collection: File.file?(File.join(@root, RBS_COLLECTION_LOCKFILE)),
-          rails_unconfigured: rails_unconfigured?(config),
+          plugins_unconfigured: plugins_unconfigured?(config),
           ci: ci_state,
           editor: editor_state,
           mcp: mcp_state
@@ -47,24 +41,26 @@ module Rigor
 
       private
 
-      # True when Rails is in `Gemfile.lock` but the (present) config enables no Rails plugin — so `rigor-plugin-tune`
-      # (wiring the ActiveRecord / routes / i18n plugins) buys more than community RBS would (the 20260620 field trial's
-      # strap case). Only fires on an already-configured project; an un-configured Rails app routes to
-      # `rigor-project-init`, which selects the plugins itself.
-      def rails_unconfigured?(config)
+      # ADR-96 WD2 — true when the project depends on gems that bundled plugins model and enables none of those
+      # plugins, so `rigor-plugin-tune` buys more than community RBS would (the 20260620 field trial's strap
+      # case). Reads each plugin's `target_gems:` rather than the Rails-only table it replaces, so the cue
+      # covers every framework Rigor ships a plugin for. Only fires on an already-configured project; an
+      # un-configured app routes to `rigor-project-init`, which selects the plugins itself.
+      def plugins_unconfigured?(config)
         return false if config.nil?
 
-        lock = File.join(@root, "Gemfile.lock")
-        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
-
-        !file_mentions_any?(File.join(@root, config), RAILS_PLUGIN_MARKERS)
+        plugins = configured_plugins(File.join(@root, config))
+        PluginGapAdvisory.unconfigured?(project_root: @root, plugins: plugins)
       end
 
-      def file_mentions_any?(path, markers)
-        content = File.read(path)
-        markers.any? { |marker| content.include?(marker) }
+      # The probe reads the config file itself rather than {Rigor::Configuration}: it must stay a
+      # presence-only probe, and `Configuration.load` applies defaults (including the ADR-93 auto-wired
+      # `rigor-rbs-inline` entry) that have nothing to do with the question asked here.
+      def configured_plugins(path)
+        data = YAML.safe_load_file(path, permitted_classes: [], aliases: true)
+        data.is_a?(Hash) ? Array(data["plugins"]) : []
       rescue StandardError
-        false
+        []
       end
 
       # `:wired` (a CI config mentions `rigor`), `:unwired` (a CI config exists but does not), or `:none`.
@@ -121,9 +117,9 @@ module Rigor
       # The entry-point SKILL itself — excluded from the catalogue because it is the skill being run, not a destination.
       ENTRY_POINT_SKILL = "rigor-next-steps"
 
-      # Adoption-journey order for the catalogue and the order the recommendation decision tree walks. `rigor-ask` sits
-      # last: it is the journey-agnostic "answer a question about Rigor" companion the agent can offer at any point,
-      # never a presence-recommended step.
+      # Adoption-journey order for the catalogue and the order the recommendation decision tree walks. The last two are
+      # journey-agnostic companions the agent can offer at any point, never presence-recommended steps:
+      # `rigor-type-oracle` fires on an event (being about to write a type), and `rigor-ask` on a question about Rigor.
       CATALOG_ORDER = %w[
         rigor-project-init
         rigor-rbs-setup
@@ -137,12 +133,13 @@ module Rigor
         rigor-plugin-author
         rigor-upgrade
         rigor-doctor
+        rigor-type-oracle
         rigor-ask
       ].freeze
 
-      # @param skills [Array<Hash>] discovered skills, each `{name:, path:}`.
-      # @param root [String] project root to probe (defaults to the cwd).
-      # @param deep [Boolean] opt into `--deep`: run a real `rigor check` and let its result pick the headline. Off by
+      # @param skills — discovered skills, each `{name:, path:}`.
+      # @param root — project root to probe (defaults to the cwd).
+      # @param deep — opt into `--deep`: run a real `rigor check` and let its result pick the headline. Off by
       #   default, and off is ADR-73 WD2's contract — see {SkillDeepProbe} for why the whole analysis path lives
       #   behind this one flag and in its own file.
       def initialize(skills:, root: Dir.pwd, deep: false)
@@ -151,7 +148,6 @@ module Rigor
         @deep = deep
       end
 
-      # @return [String] the full describe report.
       def render
         catalog = catalog_skills
         state = ProjectStateProbe.new(@root).to_h
@@ -202,14 +198,18 @@ module Rigor
       def recommended_name_and_reason(state)
         if state.fetch(:config).nil?
           ["rigor-project-init", "this project has no Rigor configuration yet — start here."]
-        elsif state.fetch(:rails_unconfigured)
+        elsif state.fetch(:plugins_unconfigured)
           ["rigor-plugin-tune",
-           "Rails is in your Gemfile.lock but no Rails plugins are enabled — wire them so " \
-           "ActiveRecord / routes / i18n calls resolve (a bigger win here than community RBS)."]
-        elsif state.fetch(:gems) && !state.fetch(:rbs_collection)
-          ["rigor-rbs-setup", "your gems ship no community RBS yet — install it so Rigor stops typing them as Dynamic."]
+           "your Gemfile declares gems Rigor ships plugins for and none is enabled — wire them so " \
+           "those framework calls resolve (a bigger win here than community RBS)."]
+        # ADR-73's second `rbs-setup` priority-softening case (2026-09-10): CI wiring is presence-only and
+        # side-effect-free, while community-RBS install is network-bound (`rbs collection install` hits
+        # rubygems.org). A configured project earns the cheap, local win first — checked ahead of the RBS
+        # gap rather than after it.
         elsif state.fetch(:ci) != :wired
           ["rigor-ci-setup", "Rigor is configured but not wired into CI — lock in the regression guard."]
+        elsif state.fetch(:gems) && !state.fetch(:rbs_collection)
+          ["rigor-rbs-setup", "your gems ship no community RBS yet — install it so Rigor stops typing them as Dynamic."]
         # A present baseline is deliberately NOT a recommendation trigger. A baseline is a healthy, finished onboarding
         # state, not a problem to work off; pushing every baselined project to "reduce it" turns a working build into a
         # chore and tempts scattering `# rigor:disable` through the code to make a number go down — means over ends.

data/lib/rigor/cli/trace_command.rb

@@ -12,7 +12,7 @@ require_relative "../inference/flow_tracer"
 require_relative "../inference/scope_indexer"
 require_relative "command"
 require_relative "trace_renderer"
-require_relative "probe_environment"
+require_relative "../project_environment"
 
 module Rigor
   class CLI
@@ -30,7 +30,7 @@ module Rigor
       DEFAULT_KINDS = %i[bind union dispatch].freeze
       VERBOSE_KINDS = (%i[enter result] + DEFAULT_KINDS).freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         file = @argv.first
@@ -92,10 +92,10 @@ module Rigor
       end
 
       # 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
+      # same dispatch `rigor check` would, including plugin-synthesized RBS — see {ProjectEnvironment}), an empty
       # seed scope, one statement-level evaluation of the whole program — but recorded under the FlowTracer.
       def record_events(root, file, configuration)
-        environment = ProbeEnvironment.build(configuration: configuration, source_files: [file])
+        environment = ProjectEnvironment.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/trace_renderer.rb

@@ -28,9 +28,8 @@ module Rigor
       BODY_HEIGHT_MIN = 3    # never shrink the source window below this
       DEFAULT_SIZE = [24, 80].freeze
 
-      # @param out [IO]
-      # @param source [String] the traced file's source.
-      # @param file [String] display path.
+      # @param source — the traced file's source.
+      # @param file — display path.
       def initialize(out:, source:, file:)
         @out = out
         @source = source
@@ -38,11 +37,11 @@ module Rigor
         @lines = source.lines.map(&:chomp)
       end
 
-      # @param events [Array<Rigor::Inference::FlowTracer::Event>] the
+      # @param events — the
       #   pre-filtered frame list (the command owns kind filtering).
-      # @param delay [Float, nil] seconds between frames (autoplay);
+      # @param delay — seconds between frames (autoplay);
       #   nil = step on key press when interactive.
-      # @param interactive [Boolean] whether to clear/redraw and wait.
+      # @param interactive — whether to clear/redraw and wait.
       def play(events, delay: nil, interactive: false)
         @rows, @cols = interactive ? terminal_size : DEFAULT_SIZE
         @interactive = interactive

data/lib/rigor/cli/triage_command.rb

@@ -22,7 +22,7 @@ module Rigor
       USAGE = "Usage: rigor triage [options] [paths]"
       DEFAULT_SECTIONS = %i[distribution selectors hotspots hints].freeze
 
-      # @return [Integer] CLI exit status (always 0).
+      # @return CLI exit status (always 0).
       def run
         options = parse_options
         configuration = Configuration.load(options.fetch(:config))