rigortype 0.3.0 → 0.3.1

data/lib/rigor/cache/store.rb

@@ -37,18 +37,10 @@ module Rigor
       # blob whose class layout still happens to unmarshal.
       PAYLOAD_ABI_VERSION = Rigor::VERSION
 
-      # Whole-project producers are content-keyed, so dependency / signature churn writes a new entry and leaves
-      # the old generation unreachable. The global 256 MB cap is intentionally generous and often never fires on
-      # one project, so these producers get a small generation cap as a second compaction axis. Per-file / plugin
-      # producers are deliberately absent from this table: many current entries under one producer id can be live.
-      GENERATION_CAP_BY_PRODUCER = {
-        "analysis.run-diagnostics" => 16,
-        "rbs.class_ancestor_table" => 2,
-        "rbs.class_type_param_names" => 2,
-        "rbs.constant_type_table" => 2,
-        "rbs.environment" => 2,
-        "rbs.known_class_names" => 2
-      }.freeze
+      # The `generation_cap:` value declaring that a producer keeps MANY live entries under one id at once
+      # (per-file and per-plugin producers): a generation count is not a staleness proxy there, so the
+      # compaction pass in {#evict!} leaves the producer alone and only the size-based LRU pass can touch it.
+      UNBOUNDED_GENERATIONS = :unbounded
 
       STALE_TEMP_FILE_AGE_SECONDS = 60 * 60
 
@@ -76,6 +68,14 @@ module Rigor
         @misses = 0
         @writes = 0
         @by_producer = Hash.new { |h, k| h[k] = { hits: 0, misses: 0, writes: 0 } }
+        # `producer_id => generation cap`, populated from the `generation_cap:` every fetch call declares (see
+        # {#declare_generation_cap}). This is the bridge between the id STRINGS the fetch API takes and the
+        # directory names {#evict!} walks: a producer id the Store never saw declared stays uncapped, which
+        # errs toward under-evicting. Per-instance rather than process-global on purpose — a global mutable
+        # registry would be a `Ractor` shareability hazard for pool mode, and the Store instance that wrote a
+        # generation is the one whose `evict!` compacts it (`CLI::CheckCommand` calls
+        # `runner.cache_store&.evict!`).
+        @generation_caps = {}
         # Process-level in-memory layer keyed by `(producer_id, cache_key)`. Avoids the disk read +
         # `Marshal.load` cost (the dominant share of repeated cache-hit calls per stackprof) when many
         # short-lived `Analysis::Runner` instances share one `Store` — the spec process, the LSP daemon's
@@ -161,6 +161,12 @@ module Rigor
       private_class_method :collect_producers
 
       # @param producer_id [String] stable cache namespace; only `[a-z][a-z0-9._-]*` is accepted.
+      # @param generation_cap [Integer, Symbol] how many generations of this producer survive a compaction
+      #   pass — a positive `Integer` for a whole-project producer (one live entry, older ones unreachable),
+      #   or {UNBOUNDED_GENERATIONS} for a producer with many simultaneously-live entries. REQUIRED, and
+      #   sourced from the producer's own declaration (`RbsCacheProducer.generation_cap`,
+      #   `RunCacheKey::GENERATION_CAP`, `Plugin::Base.producer generation_cap:`) rather than invented at the
+      #   call site. See {#evict!}.
       # @param params [Hash] producer inputs; mixed into the cache key via {Descriptor#cache_key_for}.
       # @param descriptor [Rigor::Cache::Descriptor] the invalidation descriptor for the value being cached.
       # @param serialize [#call, nil] optional callable that turns the producer's return value into a binary
@@ -175,9 +181,10 @@ module Rigor
       #   path.
       # @yieldreturn the value to cache.
       # @return the cached value (loaded from disk on hit; produced by the block on miss).
-      def fetch_or_compute(producer_id:, params:, descriptor:,
+      def fetch_or_compute(producer_id:, params:, descriptor:, generation_cap:,
                            serialize: nil, deserialize: nil, &block)
         validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
 
         key = descriptor.cache_key_for(producer_id: producer_id, params: params)
@@ -217,8 +224,12 @@ module Rigor
       #
       # The block MUST return `[value, dependency_descriptor]`. Disk reads are not in-process-memoised —
       # validation always re-checks the filesystem — but a single run only looks up once.
-      def fetch_or_validate(producer_id:, key_descriptor:, params: {}, serialize: nil, deserialize: nil)
+      #
+      # `generation_cap:` carries the same producer-declared compaction budget as {#fetch_or_compute}.
+      def fetch_or_validate(producer_id:, key_descriptor:, generation_cap:, params: {},
+                            serialize: nil, deserialize: nil)
         validate_producer_id!(producer_id)
+        declare_generation_cap(producer_id, generation_cap)
         disk = ensure_schema_version!
 
         key = key_descriptor.cache_key_for(producer_id: producer_id, params: params)
@@ -243,6 +254,9 @@ module Rigor
       # to serve a run's diagnostics WITHOUT loading the inference engine — it never runs a producer block, so
       # there is nothing to write. Records a hit (for `--cache-stats` parity) but never a miss (a probe miss
       # hands off to the full path, which records its own).
+      #
+      # Takes no `generation_cap:`: a pure read creates no generation, so a run that only ever peeks has
+      # nothing to compact. The write path for the same producer declares the cap.
       def peek_validated(producer_id:, key_descriptor:, params: {}, deserialize: nil)
         validate_producer_id!(producer_id)
         return nil unless ensure_schema_version!
@@ -256,8 +270,15 @@ module Rigor
         validated[0]
       end
 
-      # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only. Stale
-      # temp file cleanup and the whole-project generation cap run regardless of `max_bytes:` — they reclaim
+      # ADR-6 § "Eviction" — compaction pass over the on-disk cache. No-op when the store is read-only.
+      #
+      # The generation cap of pass 2 comes from what the producers themselves declared through this Store's
+      # fetch calls (`generation_cap:`), NOT from a maintained table of producer ids: a producer id this
+      # Store never saw is left alone. That is deliberately the safe direction — a producer that was not
+      # consulted this run also wrote no new generation, so the only entries this can skip are ones that were
+      # already sitting there.
+      #
+      # Stale temp file cleanup and the generation cap run regardless of `max_bytes:` — they reclaim
       # provably-dead bytes (leaked temp files, unreachable content-keyed generations) rather than enforcing a
       # size budget, so an explicitly unbounded store (`max_bytes: nil`) still benefits from them. The
       # size-based LRU pass below stays gated on `max_bytes:` being configured: it walks all remaining
@@ -279,7 +300,7 @@ module Rigor
         entries.each do |entry|
           break if total <= @max_bytes
 
-          total -= entry[:bytes] if unlink_entry(entry[:path])
+          total -= entry[:bytes] if unlink_entry_and_shard?(entry[:path])
         end
         nil
       rescue StandardError
@@ -320,6 +341,37 @@ module Rigor
               "producer_id must match #{VALID_PRODUCER_ID.inspect}, got #{producer_id.inspect}"
       end
 
+      # Records the producer's declared compaction budget for {#evict!}. Every fetch call carries it, so a
+      # producer cannot reach disk without stating one — the failure mode the previous hardcoded id table
+      # had (a new whole-project producer silently uncapped) is not expressible.
+      #
+      # Two DIFFERENT caps for one producer id in one process is a producer bug, not a policy: whichever the
+      # compaction pass picked would be arbitrary. It raises, consistent with the serializer-contract
+      # violations {#try_write_entry} deliberately lets through.
+      def declare_generation_cap(producer_id, generation_cap)
+        validate_generation_cap!(producer_id, generation_cap)
+        @monitor.synchronize do
+          previous = @generation_caps[producer_id]
+          if !previous.nil? && previous != generation_cap
+            raise ArgumentError,
+                  "producer #{producer_id.inspect} declared generation_cap #{generation_cap.inspect} after " \
+                  "#{previous.inspect}; one producer id must declare one cap"
+          end
+
+          @generation_caps[producer_id] = generation_cap
+        end
+      end
+
+      def validate_generation_cap!(producer_id, generation_cap)
+        return if generation_cap == UNBOUNDED_GENERATIONS
+        return if generation_cap.is_a?(Integer) && generation_cap.positive?
+
+        raise ArgumentError,
+              "producer #{producer_id.inspect} must declare generation_cap as a positive Integer (a " \
+              "whole-project producer: how many generations survive compaction) or " \
+              "#{UNBOUNDED_GENERATIONS.inspect} (many entries live at once), got #{generation_cap.inspect}"
+      end
+
       def entry_path(producer_id, key)
         File.join(@root, producer_id, key[0, 2], "#{key[2..]}.entry")
       end
@@ -541,7 +593,7 @@ module Rigor
           next unless File.file?(path)
           next if File.mtime(path) > cutoff
 
-          unlink_entry(path)
+          unlink_entry_and_shard?(path)
         rescue StandardError
           next
         end
@@ -550,16 +602,16 @@ module Rigor
       end
 
       def evict_excess_generations(entries)
+        caps = @monitor.synchronize { @generation_caps.dup }
         removed = {}
         entries.group_by { |entry| entry[:producer] }.each do |producer, producer_entries|
-          cap = GENERATION_CAP_BY_PRODUCER[producer]
+          cap = caps[producer]
+          cap = nil if cap == UNBOUNDED_GENERATIONS
           next if cap.nil? || producer_entries.size <= cap
 
-          producer_entries.sort_by { |entry| [entry[:mtime], entry[:path]] }
-                          .first(producer_entries.size - cap)
-                          .each do |entry|
-            removed[entry[:path]] = true if unlink_entry(entry[:path])
-          end
+          excess = producer_entries.sort_by { |entry| [entry[:mtime], entry[:path]] }
+                                   .first(producer_entries.size - cap)
+          excess.each { |entry| removed[entry[:path]] = true if unlink_entry_and_shard?(entry[:path]) }
         end
         return entries if removed.empty?
 
@@ -573,6 +625,29 @@ module Rigor
         false
       end
 
+      # {#unlink_entry} plus a best-effort {#rmdir_if_empty} of the shard directory the unlinked file left
+      # behind. Shared by every eviction/sweep pass so an emptied shard is cleaned up wherever an entry (or
+      # stale temp file) is removed, per the issue #216 fossil fix.
+      def unlink_entry_and_shard?(path)
+        return false unless unlink_entry(path)
+
+        rmdir_if_empty(File.dirname(path))
+        true
+      end
+
+      # Removes `dir` — a shard directory (`entry_path`'s `key[0, 2]` component) — when the unlink that
+      # just preceded this call was the one to empty it. Best-effort and rescued the same way
+      # {#unlink_entry} is: a concurrent writer's `FileUtils.mkdir_p` recreating the shard between the
+      # unlink and this call (`Errno::ENOTEMPTY`) or another pass already having removed it
+      # (`Errno::ENOENT`) are both benign outcomes, never a reason to break the eviction/sweep pass. This
+      # is purely cosmetic (inode reclaim) — it never decides which ENTRIES are evicted, only tidies the
+      # directory left behind once they are gone.
+      def rmdir_if_empty(dir)
+        Dir.rmdir(dir)
+      rescue StandardError
+        nil
+      end
+
       # Returns an array of `{ path:, producer:, mtime:, bytes: }` hashes for every `.entry` file under the
       # cache root, skipping unreadable entries.
       def collect_entry_stats

data/lib/rigor/cli/check_command.rb

@@ -65,11 +65,12 @@ module Rigor
         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)
@@ -383,11 +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:)
-        require_relative "check_runner_factory"
-        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
 

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/doctor_command.rb

@@ -12,7 +12,7 @@ require_relative "../plugin/loader"
 require_relative "../plugin/services"
 require_relative "../reflection"
 require_relative "../type/combinator"
-require_relative "check_runner_factory"
+require_relative "check_invocation"
 require_relative "command"
 require_relative "options"
 
@@ -53,14 +53,12 @@ module Rigor
         findings.concat(audit_config(configuration))
 
         # 2. Run a scoped analysis to gather stats + diagnostics for the
-        #    deeper checks.  Use no-cache so the probe doesn't churn disk.
-        runner = CheckRunnerFactory.build(
+        #    deeper checks, through the shared check-invocation entry point (#148).
+        #    `READ_ONLY_OPTIONS` is no-cache so the probe doesn't churn disk.
+        result = CheckInvocation.run(
           configuration: configuration,
-          options: { no_cache: true, explain: false, stats: true, workers: 0 },
-          buffer: nil,
-          cache_root: configuration.cache_path
-        )
-        result = runner.run(configuration.paths)
+          options: CheckInvocation::READ_ONLY_OPTIONS
+        ).result
 
         # 3. RBS environment check.
         findings.concat(check_rbs_environment(result))

data/lib/rigor/cli/skill_command.rb

@@ -36,6 +36,13 @@ module Rigor
     #                                version-coupled guidance is frozen into
     #                                the SKILL. Also spelled `describe`, and
     #                                surfaced top-level as `rigor describe`.
+    # - `rigor skill describe --deep`
+    #                              — the same report, except it runs `rigor
+    #                                check` first and lets the result pick the
+    #                                headline. Opt-in because that is slow and
+    #                                writes the cache; the un-flagged form keeps
+    #                                WD2's presence-only, side-effect-free
+    #                                contract exactly (issue #148).
     #
     # `describe` is a no-argument action, not a name-slot verb, so it stays first-class alongside `--describe`.
     class SkillCommand < Command
@@ -51,6 +58,10 @@ module Rigor
           rigor skill --path <name>  Print the absolute path of the SKILL.md file for <name>
           rigor skill --list         List bundled skills (name + absolute path)
           rigor skill --describe     Report project state + recommend the next skill to run
+                                     (presence-only probe — never runs `rigor check`)
+          rigor skill describe --deep
+                                     Same, but run `rigor check` first and route the
+                                     recommendation on its result (slow; writes the cache)
 
         Examples:
           rigor skill
@@ -58,6 +69,7 @@ module Rigor
           rigor skill --full rigor-baseline-reduce
           rigor skill --path rigor-baseline-reduce
           rigor skill --describe        (also: rigor describe)
+          rigor skill describe --deep   (also: rigor describe --deep)
       USAGE
 
       # The bundled skills live at `<gem_root>/skills/`. From `lib/rigor/cli/skill_command.rb` that is three directories
@@ -159,10 +171,18 @@ module Rigor
       # probes the current project's state with cheap presence checks (it never runs `rigor check`), recommends the next
       # skill to run, and prints every bundled skill's current frontmatter description, so the `rigor-next-steps` SKILL
       # can route without copying any version-coupled guidance into itself.
+      #
+      # `--deep` is the one opt-in that breaks the "never runs `rigor check`" guarantee — and only for the invocation
+      # that asks for it (issue #148 / ADR-73 § "Field-trial follow-ups"). It runs a real check and lets the result
+      # pick the headline; the un-flagged command is unchanged, down to loading no analysis code at all.
       def run_describe
+        deep = !@argv.delete("--deep").nil?
+        unknown = @argv.first
+        return usage_error("unknown option for `describe`: #{unknown}") unless unknown.nil?
+
         require_relative "skill_describe"
 
-        @out.puts(SkillDescribe.new(skills: discover_skills).render)
+        @out.puts(SkillDescribe.new(skills: discover_skills, deep: deep).render)
         0
       end
 

data/lib/rigor/cli/skill_deep_probe.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "check_invocation"
+
+module Rigor
+  class CLI
+    # `rigor skill describe --deep` — the one part of `describe` that runs an analysis (issue #148; ADR-73
+    # § "Field-trial follow-ups", the "headline check-awareness" open decision, shape (b)).
+    #
+    # **The boundary is this file.** ADR-73 WD2 makes `describe` presence-only and side-effect-free, and that
+    # guardrail binds the *un-flagged* command exactly as before: {SkillDescribe} requires this file only when
+    # `--deep` was passed, so a default `rigor skill describe` never loads the inference engine, never opens a
+    # project source file, and writes nothing. `--deep` is the opt-in that trades that purity away: it runs a real
+    # `rigor check` over the configured paths using the configured cache and worker count, so it is as slow as
+    # `rigor check` on a cold cache and it WRITES `.rigor/cache` just like `rigor check` does.
+    #
+    # The routing vocabulary is deliberately the one `describe`'s "For the agent" section already teaches (errors →
+    # `rigor-baseline-reduce`, a proven monkey-patch cluster → `rigor-monkeypatch-resolve`, an empty RBS environment
+    # or a `configuration-error` → `rigor-doctor`). `--deep` makes the headline compute the call the agent would
+    # otherwise make from the same evidence; it does not introduce a second taxonomy.
+    class SkillDeepProbe
+      # Diagnostics the engine emits when the *setup* is broken rather than the code — the `rigor-doctor` signal.
+      CONFIGURATION_ERROR_RULE = "configuration-error"
+
+      # The share of a run's errors that must be proven monkey-patches before the headline routes to
+      # `rigor-monkeypatch-resolve` rather than `rigor-baseline-reduce`. The agent-prompt vocabulary this reuses says
+      # "a monkey-patch *cluster*", and a cluster is what makes the workflow the right one: `pre_eval:` clears those
+      # sites wholesale, so it is the shortest path only when clearing them materially changes the count. One proven
+      # site beside four hundred unrelated errors is a true finding pointing at the wrong workflow — the report says
+      # so in the reason line either way, so nothing is lost by leaving the headline on the bigger problem.
+      MONKEY_PATCH_CLUSTER_SHARE = Rational(1, 3)
+
+      # What the deep check concluded.
+      #
+      # - `status` — `:skipped` (no config to check), `:error` (the check could not run), `:analyzed` (it ran).
+      # - `detail` — the human line printed under "## Deep check"; on `:error` it says so outright, because a check
+      #   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
+        #   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
+      #   `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,
+      #   leaving the presence-only headline in charge.
+      def run
+        if @config.nil?
+          return Report.new(
+            status: :skipped, route: nil, reason: nil,
+            detail: "skipped — this project has no Rigor configuration, so there is nothing to check yet."
+          )
+        end
+
+        outcome = CheckInvocation.attempt(config_path: File.join(@root, @config))
+        return failed(outcome.error) unless outcome.ran?
+
+        classify(outcome.result)
+      end
+
+      private
+
+      # A check that could not run at all. Reported as a failure, not as a clean result, and with the raw error text
+      # so the user can act on it — the un-run check is itself a finding, but not one precise enough to route on.
+      def failed(error)
+        Report.new(
+          status: :error, route: nil, reason: nil,
+          detail: "the check could NOT run: #{error}. This is not a clean result — the recommendation below " \
+                  "falls back to the presence-only probe. Run `rigor check` (or `rigor doctor`) to see what failed."
+        )
+      end
+
+      def classify(result)
+        sites = monkey_patch_diagnostics(result)
+        if broken_environment?(result)
+          doctor_report(result)
+        elsif monkey_patch_cluster?(result, sites)
+          monkeypatch_report(result, sites)
+        elsif result.error_count.positive?
+          baseline_report(result, sites)
+        else
+          Report.new(
+            status: :analyzed, route: nil, reason: nil,
+            detail: "the check ran clean — 0 error diagnostics. The recommendation below is the presence-only one."
+          )
+        end
+      end
+
+      # The `rigor-doctor` signal, read exactly as `rigor doctor` itself reads it: an RBS environment that built to
+      # zero classes (analysis is hollow, so every other count is meaningless), or a `configuration-error` the run
+      # already emitted. Checked first — with a broken setup the remaining diagnostics are not evidence of anything.
+      def broken_environment?(result)
+        result.stats&.rbs_classes_total&.zero? ||
+          result.diagnostics.any? { |diagnostic| diagnostic.rule == CONFIGURATION_ERROR_RULE }
+      end
+
+      # ADR-17 / the `project-monkey-patch-known` triage recogniser: `call.undefined-method` sets
+      # `project_definition_site` when the project itself defines the called method on the receiver class somewhere
+      # in the analysed file set. That is engine-proven evidence, not a spread heuristic, which is why it routes with
+      # no count threshold — and why the *unproven* shapes (a bare `call.unresolved-toplevel` count, "framework calls
+      # typing as Dynamic") are deliberately not routed on here. Guessing a workflow from a weak signal is worse than
+      # leaving the generic recommendation standing.
+      def monkey_patch_diagnostics(result)
+        result.diagnostics.select(&:project_definition_site)
+      end
+
+      # Whether the proven sites dominate the run enough for `pre_eval:` to be the shortest path. Any proven site is
+      # real evidence — `project_definition_site` is engine-proven, not a spread heuristic — but evidence of a *site*
+      # is not evidence that clearing it is the next thing to do. Below the share, `baseline_report` still names the
+      # sites, so the finding survives even when the headline does not follow it.
+      def monkey_patch_cluster?(result, sites)
+        return false if sites.empty?
+        return true unless result.error_count.positive?
+
+        Rational(sites.size, result.error_count) >= MONKEY_PATCH_CLUSTER_SHARE
+      end
+
+      def doctor_report(result)
+        classes = result.stats&.rbs_classes_total
+        cause = if classes&.zero?
+                  "the RBS environment built to 0 classes"
+                else
+                  "the run emitted a `#{CONFIGURATION_ERROR_RULE}` diagnostic"
+                end
+        Report.new(
+          status: :analyzed, route: "rigor-doctor",
+          reason: "a `--deep` check found a broken setup (#{cause}) — the analysis is hollow until that is fixed, " \
+                  "so no other finding is trustworthy yet.",
+          detail: "the check found a broken setup — #{cause}."
+        )
+      end
+
+      def monkeypatch_report(result, sites)
+        files = sites.filter_map { |d| d.project_definition_site&.sub(/:\d+\z/, "") }.uniq.sort
+        Report.new(
+          status: :analyzed, route: "rigor-monkeypatch-resolve",
+          reason: "a `--deep` check found #{sites.size} call site(s) that resolve to the project's own definitions " \
+                  "in #{files.first(3).join(', ')} — reopened classes Rigor does not apply cross-file. Listing " \
+                  "them in `pre_eval:` clears them wholesale.",
+          detail: "the check reported #{result.error_count} error diagnostic(s), #{sites.size} of them proven " \
+                  "project monkey-patches (#{files.size} file(s))."
+        )
+      end
+
+      def baseline_report(result, sites = [])
+        aside = if sites.empty?
+                  ""
+                else
+                  " #{sites.size} of them are proven project monkey-patches — too small a share to make `pre_eval:` " \
+                    "the shortest path, but `rigor-monkeypatch-resolve` clears them if you want them gone first."
+                end
+        Report.new(
+          status: :analyzed, route: "rigor-baseline-reduce",
+          reason: "a `--deep` check reported #{result.error_count} error diagnostic(s) — work them down (or record " \
+                  "them in a baseline) before adding more surface.#{aside}",
+          detail: "the check reported #{result.error_count} error diagnostic(s), " \
+                  "#{sites.empty? ? 'none' : sites.size} of them proven project monkey-patches."
+        )
+      end
+    end
+  end
+end