rigortype 0.2.0 → 0.2.2

data/lib/rigor/protection/mutation_scanner.rb

@@ -2,8 +2,8 @@
 
 require "prism"
 
-require_relative "../analysis/runner"
 require_relative "mutator"
+require_relative "diagnostic_oracle"
 
 module Rigor
   module Protection
@@ -15,17 +15,16 @@ module Rigor
     # Mechanism (the ADR-62 warm loop, narrowed to per-file measurement):
     # generate the type-visible mutations ({Mutator}), keep only those whose
     # receiver Rigor holds a concrete type for (the type-aware filter — the
-    # FP-safe meaning-maker; an unresolved receiver is kept), then for each:
-    # re-analyse the mutated SOURCE against a clean baseline and read whether a
-    # NEW diagnostic appears. A *killed* mutation is a caught breakage; a
-    # *survived* one is a breakage Rigor missed — an "add a type here" site.
+    # FP-safe meaning-maker; an unresolved receiver is kept), then for each ask
+    # the **kill oracle** whether the mutant is caught. The oracle is the ADR-69
+    # seam: {#scan_file} uses the {DiagnosticOracle} (a *new Rigor diagnostic* =
+    # a kill); {#scan_file_fused} additionally consults a {TestSuiteOracle} on the
+    # type-survivors (ADR-70 — the dynamic protection axis).
     #
     # The expensive builds (RBS environment + the whole-project pre-pass scan)
-    # are paid ONCE by the caller and threaded in via `environment:` /
-    # `project_scan:`; each mutant reuses them through
-    # `Runner.new(prebuilt:)#run_source` (in-memory overlay, no disk write).
-    # Passing `prebuilt:` disables the run-result cache (whose key digests the
-    # *disk* file), so a mutant is never served a stale clean hit.
+    # are paid ONCE by the caller and threaded into the {DiagnosticOracle}; each
+    # mutant reuses them through `Runner.new(prebuilt:)#run_source` (in-memory
+    # overlay, no disk write).
     class MutationScanner
       # A surviving mutation site — a breakage Rigor did not catch.
       SurvivingSite = Data.define(:line, :receiver, :method_name, :operator)
@@ -39,18 +38,46 @@ module Rigor
         def ratio = total.zero? ? 1.0 : killed.to_f / total
       end
 
+      # ADR-70 — one type-survivor classified by the dynamic (test) axis.
+      # `protection` is `:test` (a test caught it) or `:none` (unprotected — the
+      # "add a type OR a test here" sites).
+      FusedSite = Data.define(:line, :receiver, :method_name, :operator, :protection)
+
+      # ADR-70 — the per-file fused classification. The gradual short-circuit
+      # collapses the conceptual "doubly-protected" bucket into `type_killed`:
+      # a mutant the type checker already kills never reaches the suite, because
+      # the static net already suffices and re-running the suite to learn a test
+      # *would also* catch it is wasted work. So the observed buckets are three.
+      FusedFileResult = Data.define(:path, :type_killed, :test_killed, :sites) do
+        # The unprotected sites (neither a type nor a test caught the breakage).
+        def unprotected = sites.size
+        def total = type_killed + test_killed + unprotected
+
+        # Fused protected ratio — caught by *either* axis.
+        def ratio = total.zero? ? 1.0 : (type_killed + test_killed).to_f / total
+      end
+
       # @param configuration [Rigor::Configuration]
       # @param environment [Rigor::Environment] pre-built once by the caller
       # @param project_scan [Rigor::Analysis::ProjectScan] pre-built once
       # @param limit [Integer, nil] optional per-file mutation cap (sampled with
       #   `seed`); nil analyses every type-relevant mutation (deterministic).
       # @param seed [Integer] RNG seed for the optional sample.
-      def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1)
-        @configuration = configuration
+      # @param oracle [#baseline, #killed?, nil] the kill oracle (ADR-69 Seam 1);
+      #   defaults to the {DiagnosticOracle} (the ADR-62/63 behaviour).
+      # @param site_selector [:biteable, :all] which sites to mutate (ADR-69
+      #   Seam 2). `:biteable` (default) keeps only concrete-type sites Rigor can
+      #   bite; `:all` also mutates Dynamic-receiver dispatch sites — use only
+      #   with a {TestSuiteOracle} (the fused overlay), never the diagnostic path.
+      def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1, oracle: nil,
+                     site_selector: :biteable)
         @environment = environment
-        @project_scan = project_scan
         @limit = limit
         @seed = seed
+        @site_selector = site_selector
+        @oracle = oracle || DiagnosticOracle.new(
+          configuration: configuration, environment: environment, project_scan: project_scan
+        )
       end
 
       # @param path [String] the file to measure (used as the in-memory bind path)
@@ -58,21 +85,13 @@ module Rigor
       # @return [FileResult]
       def scan_file(path, source: nil)
         source ||= File.read(path, encoding: Encoding::UTF_8)
-        mutator = Mutator.new(source)
-        kept, = mutator.filter_by_type(mutator.mutations, environment: @environment, path: path)
-        kept = sample(kept)
+        kept = kept_mutations(source, path)
         return FileResult.new(path: path, killed: 0, survived: 0, sites: []) if kept.empty?
 
-        baseline = signatures(analyse(source, path))
-        measure(source, path, kept, baseline)
-      end
-
-      private
-
-      def measure(source, path, mutations, baseline)
+        baseline = @oracle.baseline(source: source, path: path)
         killed = 0
         sites = []
-        mutations.each do |mut|
+        kept.each do |mut|
           case classify(source, path, mut, baseline)
           when :killed then killed += 1
           when :survived then sites << surviving_site(mut)
@@ -82,39 +101,80 @@ module Rigor
         FileResult.new(path: path, killed: killed, survived: sites.size, sites: sites)
       end
 
+      # ADR-70 — the fused static∪dynamic measurement. Runs the type pass
+      # (the {DiagnosticOracle}); for every mutant the type checker did **not**
+      # kill, asks `test_oracle` whether the project's test suite catches it.
+      # The expensive suite run is paid only for type-survivors (the gradual
+      # short-circuit), so the cost is proportional to the protection hole.
+      # @param test_oracle [TestSuiteOracle]
+      # @return [FusedFileResult]
+      def scan_file_fused(path, test_oracle:, source: nil)
+        source ||= File.read(path, encoding: Encoding::UTF_8)
+        kept = kept_mutations(source, path)
+        return FusedFileResult.new(path: path, type_killed: 0, test_killed: 0, sites: []) if kept.empty?
+
+        baseline = @oracle.baseline(source: source, path: path)
+        type_killed = 0
+        test_killed = 0
+        sites = []
+        kept.each do |mut|
+          case classify(source, path, mut, baseline)
+          when :killed then type_killed += 1
+          when :survived
+            if test_oracle.killed?(path: path, original: source, mutant_source: mut.apply(source))
+              test_killed += 1
+            else
+              sites << fused_site(mut, :none)
+            end
+            # :invalid — a parse-broken mutant; not a measurement, skip it.
+          end
+        end
+        FusedFileResult.new(path: path, type_killed: type_killed, test_killed: test_killed, sites: sites)
+      end
+
+      private
+
+      # The mutations to measure: the biteable filter (concrete-type sites only;
+      # the FP-safe default — an unresolved receiver is kept) or, under the
+      # `:all` selector (ADR-69 Seam 2), every dispatch site including Dynamic
+      # receivers. Optionally sampled.
+      def kept_mutations(source, path)
+        mutator = Mutator.new(source)
+        muts = mutator.mutations
+        kept =
+          if @site_selector == :all
+            mutator.dispatch_site_mutations(muts, environment: @environment, path: path)
+          else
+            mutator.filter_by_type(muts, environment: @environment, path: path).first
+          end
+        sample(kept)
+      end
+
       def classify(source, path, mut, baseline)
         mutant_source = mut.apply(source)
         return :invalid unless Prism.parse(mutant_source).success?
 
-        new_diagnostics = analyse(mutant_source, path).reject { |d| baseline.include?(sig(d)) }
-        new_diagnostics.empty? ? :survived : :killed
+        @oracle.killed?(mutant_source: mutant_source, path: path, baseline: baseline) ? :killed : :survived
       rescue StandardError
         # A harness-level failure on one mutant must not abort the file.
         :invalid
       end
 
-      # cache_store: nil + prebuilt: scan ⇒ the run cache is bypassed and the
-      # mutant is always re-analysed against the in-memory bytes.
-      def analyse(source, path)
-        Rigor::Analysis::Runner.new(
-          configuration: @configuration, environment: @environment, prebuilt: @project_scan,
-          cache_store: nil, collect_stats: false
-        ).run_source(source: source, path: path).diagnostics
-      end
-
       def sample(mutations)
         return mutations unless @limit
 
         mutations.sample(@limit, random: Random.new(@seed))
       end
 
-      def signatures(diagnostics) = diagnostics.to_set { |d| sig(d) }
-      def sig(diagnostic) = [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
-
       def surviving_site(mut)
         SurvivingSite.new(line: mut.line, receiver: mut.anchor_type,
                           method_name: mut.method_name, operator: mut.operator.to_s)
       end
+
+      def fused_site(mut, protection)
+        FusedSite.new(line: mut.line, receiver: mut.anchor_type, method_name: mut.method_name,
+                      operator: mut.operator.to_s, protection: protection)
+      end
     end
   end
 end

data/lib/rigor/protection/mutator.rb

@@ -98,6 +98,27 @@ module Rigor
         [kept, mutations.size - kept.size]
       end
 
+      # ADR-69 Seam 2 (AllSites) — keep every *dispatch-site* mutation (a method
+      # call or a call-argument literal), Dynamic receiver included, annotating
+      # the anchor type where Rigor holds one. Drops only non-dispatch literals
+      # (a literal outside any call — no receiver contract to violate). The
+      # biteable {#filter_by_type} hides exactly the Dynamic sites a test-suite
+      # consumer most wants to probe: where Rigor cannot bite, a test is the only
+      # protection. Use only with a {TestSuiteOracle} — at a Dynamic site the
+      # type pass can never kill, so without the test axis these are all noise.
+      def dispatch_site_mutations(mutations, environment:, path:)
+        base = Rigor::Scope.empty(environment: environment, source_path: path)
+        index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
+        cache = {}
+        mutations.select do |mut|
+          next false if mut.method_name.nil?
+
+          _keep, type = anchor_decision(mut.anchor, index, cache)
+          mut.anchor_type = type
+          true
+        end
+      end
+
       private
 
       def walk(node, &blk)

data/lib/rigor/protection/test_suite_oracle.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Protection
+    # ADR-70 — the **test-suite** kill oracle, the dynamic sibling of
+    # {DiagnosticOracle} on the ADR-69 seam. A mutant is killed iff applying its
+    # bytes to the file under test turns the project's test suite **red**. This is
+    # the dynamic half of the fused static∪dynamic protection map: a `Dynamic`
+    # site Rigor cannot bite (a type survivor) may still be fully guarded by a
+    # test.
+    #
+    # The suite command is the **runner hook** (`--test-command`, e.g.
+    # `bundle exec rake`). The runner is injectable so the decision logic is
+    # unit-testable without shelling out; the default shells out and reads the
+    # process exit status (0 = green / passed).
+    #
+    # I/O policy: {#killed?} writes the mutant to disk, runs the suite, and
+    # **always restores** the original bytes in an `ensure` — a normal exception
+    # never leaves a mutant on disk. (A hard interrupt mid-suite is the standard
+    # mutation-testing hazard the `ensure` cannot cover; callers running this in
+    # CI accept that, as `mutant` / Stryker do.)
+    class TestSuiteOracle
+      # @param command [Array<String>] the test command (the runner hook)
+      # @param runner [#call, nil] `runner.call(command) -> true iff the suite
+      #   passed`. Defaults to shelling out via `system`.
+      def initialize(command:, runner: nil)
+        @command = command
+        @runner = runner || method(:shell_run)
+      end
+
+      # The baseline: the suite must pass on clean code, else "a mutant survived"
+      # is meaningless (every mutant would look killed, or none would). Run once
+      # before measuring.
+      def green?
+        @runner.call(@command)
+      end
+
+      # Killed iff the mutant turns the suite red. Restores `original` afterward.
+      # @param path [String] the file to (temporarily) overwrite with the mutant
+      # @param original [String] the clean bytes to restore
+      # @param mutant_source [String] the mutated bytes to test against
+      def killed?(path:, original:, mutant_source:)
+        File.write(path, mutant_source)
+        !@runner.call(@command)
+      ensure
+        File.write(path, original)
+      end
+
+      private
+
+      # Run the suite with Bundler's environment stripped, so a `bundle exec`
+      # test command resolves the **target** project's Gemfile — not whatever
+      # bundle Rigor itself was launched under. Running Rigor via `bundle exec`
+      # leaks `RUBYOPT=-rbundler/setup` + `GEM_HOME` / `BUNDLE_*` into a plain
+      # `system` subprocess, which then resolves the target's Gemfile against
+      # Rigor's gems and fails — so a green suite looks red and the run aborts.
+      # `with_unbundled_env` restores the pre-bundler env (a bare `env -u
+      # BUNDLE_GEMFILE` is not enough — the `BUNDLER_ORIG_*` preservers defeat
+      # it). Found validating ADR-70 on real projects (2026-06-17).
+      def shell_run(command)
+        run = -> { system(*command, out: File::NULL, err: File::NULL) }
+        return run.call unless defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+
+        Bundler.with_unbundled_env(&run)
+      end
+    end
+  end
+end

data/lib/rigor/signature_path_audit.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Classifies each configured `signature_paths:` entry by what it
+  # actually contributes to the RBS environment, so a caller can warn
+  # when a configured path resolves to nothing.
+  #
+  # The failure this guards against is silent. {Environment::RbsLoader}
+  # `add`s a `signature_paths:` entry only when `path.directory?`, and
+  # only the `.rbs` files under it carry signatures — so a typo'd or
+  # moved path (or a directory holding no `.rbs`) loads zero signatures
+  # with no trace on stderr or in the run summary. The downstream symptom
+  # is the most authoritative diagnostics: every call into the extensions
+  # the missing RBS was meant to describe fires `call.undefined-method` at
+  # `evidence_tier: high`. A one-character path typo can manufacture
+  # hundreds of plausible-looking false positives; surfacing the empty
+  # entry makes the real cause visible.
+  #
+  # The audit deliberately mirrors the loader's own acceptance test
+  # (`path.directory?` + a recursive `**/*.rbs` glob) so a `:ok` verdict
+  # means the loader did load from it and a warning means it did not.
+  module SignaturePathAudit
+    # One configured `signature_paths:` entry's resolution status.
+    #
+    # `status` is one of:
+    # - `:ok`            — a directory containing at least one `.rbs`.
+    # - `:missing`       — the path does not exist.
+    # - `:not_directory` — the path exists but is not a directory (the
+    #   loader only `add`s directories, so a `.rbs` file passed directly
+    #   is silently ignored).
+    # - `:empty`         — a directory with no `.rbs` file (recursive).
+    Entry = Data.define(:path, :status, :rbs_file_count) do
+      def ok?
+        status == :ok
+      end
+
+      def warning?
+        !ok?
+      end
+
+      # One-line, human-facing reason. The wording matches the loader's
+      # actual behaviour ("loaded nothing from it") rather than the
+      # filesystem error, so the message points at the consequence.
+      def message
+        case status
+        when :missing
+          "signature_paths: #{path.inspect} does not exist (no signatures loaded from it)"
+        when :not_directory
+          "signature_paths: #{path.inspect} is not a directory (no signatures loaded from it)"
+        when :empty
+          "signature_paths: #{path.inspect} matched 0 signature files"
+        else
+          "signature_paths: #{path.inspect} loaded #{rbs_file_count} signature file(s)"
+        end
+      end
+
+      def to_h
+        { "path" => path, "status" => status.to_s, "rbs_file_count" => rbs_file_count, "message" => message }
+      end
+    end
+
+    # Audits each configured entry. `signature_paths` is the
+    # {Configuration#signature_paths} array (absolute paths, already
+    # resolved against the config file's directory). Pass `nil` — the
+    # unset default, where Rigor auto-detects `<root>/sig` — to get an
+    # empty result: an absent auto-detected `sig/` is a normal setup, not
+    # a misconfiguration, so it is never audited.
+    #
+    # @param signature_paths [Array<String, Pathname>, nil]
+    # @return [Array<Entry>]
+    def self.audit(signature_paths)
+      Array(signature_paths).map { |path| classify(path.to_s) }
+    end
+
+    # The subset of {audit} that resolved to nothing — the entries worth
+    # warning about.
+    #
+    # @param signature_paths [Array<String, Pathname>, nil]
+    # @return [Array<Entry>]
+    def self.warnings(signature_paths)
+      audit(signature_paths).select(&:warning?)
+    end
+
+    def self.classify(path)
+      return Entry.new(path: path, status: :missing, rbs_file_count: 0) unless File.exist?(path)
+      return Entry.new(path: path, status: :not_directory, rbs_file_count: 0) unless File.directory?(path)
+
+      count = Dir.glob(File.join(path, "**", "*.rbs")).size
+      Entry.new(path: path, status: count.zero? ? :empty : :ok, rbs_file_count: count)
+    end
+  end
+end

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/skills/rigor-ask/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: rigor-ask
+description: |
+  Rigor is a niche, fast-moving Ruby type checker; its rules, flags, and type behaviour are version-specific, so what you "remember" about it is likely wrong or stale — do NOT answer from memory or guess. For ANY question about Rigor, use this skill and investigate procedurally: run `rigor docs` (handbook + manual, bundled OFFLINE and version-matched), `rigor explain` for a diagnostic id, and for the user's own code `rigor check` / `annotate` / `type-of`, then answer only from what you read. Covers: why a line is flagged or if it's a false positive; the type model (narrowing, refinements, `Dynamic`, RBS); config keys, flags, baselines; comparisons to Sorbet, Steep, mypy, PHPStan; whether it handles Rails, RSpec, or a gem; writing an RBS signature; "what is Rigor / why use it / is it right for us?". Trigger on any Rigor mention seeking understanding — even casual, comparative, or grumbling. Skip only when Rigor isn't mentioned, or it's purely "set it up / fix / reduce it for me" (→ rigor-next-steps).
+license: MPL-2.0
+metadata:
+  version: 0.2.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Ask Rigor anything
+
+Someone has a question about Rigor. It might be about a diagnostic, the
+type model, a flag, how Rigor stacks up against another type checker,
+whether Rigor can handle their framework, how to type a method — or just
+"what is this, and should I use it?" Whatever it is, **answer from the
+source, not from memory.**
+
+Two things make that easy, and you have both offline:
+
+- **Rigor's own docs ship inside the gem.** `rigor docs` serves the full
+  handbook and manual, always matching the user's installed version, no
+  network. This is the authoritative copy: a rule's exact firing
+  condition, a flag's spelling, a config default — all drift release to
+  release, and `rigor docs` is the copy that shipped with *this* install,
+  so an answer drawn from it cannot disagree with the binary they run.
+- **Rigor can read the user's actual code.** When the question is about
+  *their* program — "why is this flagged?", "what type does Rigor see
+  here?", "how well-typed is my project?" — `rigor check` / `annotate` /
+  `type-of` / `triage` / `coverage` answer from what Rigor inferred. A
+  concrete inferred type beats any abstract explanation.
+
+This is the user's shortcut: they only ever need to remember two skills —
+**`rigor-next-steps`** ("what should we do next?") and **`rigor-ask`**
+("answer this about Rigor"). They ask in plain language; *you* turn it
+into the right lookup or analysis so they never have to remember the
+command.
+
+## The toolbox
+
+Everything here is read-only and needs no network.
+
+### Reading the docs
+
+| Command | Use |
+| --- | --- |
+| `rigor docs` | The offline doc index (`llms.txt`) — the map. Start here when you don't know which page. |
+| `rigor docs --list [manual\|handbook]` | List every bundled page with its path (optionally one category). |
+| `rigor docs <name>` | Print a page. `<name>` is a category-qualified path (`handbook/03-narrowing`), a prefixed basename (`03-narrowing`), or a unique short name (`narrowing`). Pages that exist in **both** trees (e.g. `plugins`) must be qualified — `manual/07-plugins` vs `handbook/09-plugins`. |
+| `rigor explain <rule>` | The catalogue entry for a diagnostic id (`rigor explain call.undefined-method`) — what it means, why it fires, how to address it. |
+
+### Grounding the answer in the user's code
+
+| Command | Use |
+| --- | --- |
+| `rigor check <path>` | Run the analysis. Scope it to a file or directory for a quick answer — don't analyse the whole project just to settle one question. `--format json` exposes structured fields (`receiver_type`, `method_name`, `evidence_tier`, …). |
+| `rigor annotate <file>` | Reprint the file with the inferred type of each line in the margin — *what Rigor actually sees*. |
+| `rigor type-of <file>:<line>:<col>` | The inferred type at one position. |
+| `rigor triage` | Cluster the project's diagnostics by rule / receiver / method — for "what's the shape of my errors?". |
+| `rigor coverage [--protection]` | Type / type-protection coverage — for "how well-typed is this?" and "where are the holes?". |
+| `rigor plugins` | Which plugins are installed and enabled *here* — the honest answer to "does Rigor support <gem/framework>?". |
+| `rigor sig-gen <path>` | Generate RBS for code — for "how do I type this?". Offer it and show the result; this project prefers sig-gen over hand-written RBS. |
+
+## Where the answer lives
+
+Classify the question, then go to the page(s) — and, for anything about
+*their* code, the command(s) — that own it. When unsure where a page is,
+`rigor docs` (the index) or `rigor docs --list handbook` routes you.
+
+| The question is about… | Go to |
+| --- | --- |
+| **A specific diagnostic** — "why is this flagged?", "what does this error mean?", "is this a false positive?" | `rigor explain <rule>`, then `rigor docs diagnostics`. If it's *their* code, also `rigor annotate <file>` / `rigor type-of` to see the inferred types the rule fired on. |
+| **The type model / a concept** — narrowing, refinements, tuple & hash shapes, `Dynamic`, RBS interop, lightweight HKT | The handbook: `rigor docs --list handbook`, then the chapter — `handbook/03-narrowing`, `04-tuples-and-shapes`, `07-rbs-and-extended`, `12-lightweight-hkt`, … |
+| **Operating Rigor** — a config key, CLI flag, baseline, plugins, CI, caching | The manual: `rigor docs configuration`, `cli-reference`, `baseline`, `manual/07-plugins`, `ci`, `caching`, `troubleshooting`. |
+| **How Rigor compares to another tool** — Sorbet, Steep, RBS, TypeScript, mypy, PHPStan, TypeProf, Go, Rust, Java/C# | The chapter/appendix written for exactly that: `handbook/10-sorbet`, `appendix-steep`, `appendix-typescript`, `appendix-mypy`, `appendix-phpstan`, `appendix-typeprof`, `appendix-rust`, `appendix-go`, `appendix-java-csharp` (`rigor docs --list handbook` shows them all). |
+| **Whether Rigor can do X** — generics, Rails, RSpec, a specific gem, concurrency | The handbook for the language feature; for framework/gem support, **`rigor plugins`** (what's actually available in *this* install) plus the per-plugin page `rigor docs rigor-<gem>` (e.g. `rigor docs rigor-sidekiq`) and the catalogue `rigor docs --list manual`. |
+| **Writing a type / RBS** — "how do I type this?", an annotation, a signature | Handbook `07-rbs-and-extended` + `11-sig-gen`; manual `rbs-extended-annotations`. Then offer `rigor sig-gen <path>` to generate it (preferred over hand-RBS) and show the output. |
+| **What Rigor is / why use it / is it right for me** | Handbook `01-getting-started` for the pitch, `handbook/02-everyday-types` for a quick mental model of the type zoo. Ground "is it right for *my* project" in a scoped `rigor check` / `rigor coverage` so they see Rigor on their real code. |
+
+## Answer from the page, name the page
+
+Quote or paraphrase the relevant passage and **say which page you drew
+from** (e.g. "per `rigor docs handbook/03-narrowing` …"), so the user can
+re-read it with the same command. Prefer the doc's own wording over a
+remembered approximation. When you ran a command against their code, show
+the relevant line of output — a concrete inferred type is more convincing
+than prose, and it proves the answer rather than asserting it.
+
+## When the question is really "do X for me"
+
+Some questions are a task in disguise: *"how do I get Rigor into CI?"*,
+*"how do I shrink this baseline?"*, *"how do I set Rigor up here?"* The
+useful reply is **short**: orient the user — what the thing is, the one
+decision that actually matters, the rough shape of it — then **hand the
+doing to the skill built for it.** Resist pasting the full procedure
+inline (the entire CI workflow YAML, the whole baseline-reduction loop):
+that skill owns the steps, keeps them correct, and updates as the tool
+moves, so duplicating them here only bloats the answer and drifts out of
+date. The line is *explaining* the thing (yours) versus *wiring it in*
+(the setup skill's).
+
+A good hand-off is two or three sentences of orientation plus the pointer:
+
+- setup / "what next?" → **`rigor-next-steps`** (it probes the project and routes)
+- CI → **`rigor-ci-setup`** · editor → **`rigor-editor-setup`** · MCP agent → **`rigor-mcp-setup`**
+- baseline reduction → **`rigor-baseline-reduce`** · coverage holes → **`rigor-protection-uplift`**
+- a missing gem/DSL → **`rigor-plugin-author`** · monkey-patch clusters → **`rigor-monkeypatch-resolve`**
+
+When in doubt, give less and point — it respects the user's "two skills
+to remember" promise and keeps each answer to the part only `rigor-ask`
+can give.
+
+## If the docs don't cover it
+
+The bundled set is the **drive-Rigor** corpus (manual + handbook). The
+normative **type specification**, the internal spec, and the ADRs are
+contributor-facing and stay web-only — they are *not* in `rigor docs`; if
+a question genuinely needs them, say so and point at
+<https://rigor.typedduck.fail/llms.txt> rather than guessing.
+
+But before you defer, remember Rigor installs from RubyGems **with its
+full source** — the per-plugin pages under the gem's `docs/manual/plugins/`,
+the analyzer and plugin code under `lib/`. For a detail no doc page spells
+out (a plugin's exact rule, a default baked into the code), reading the
+bundled file directly is a perfectly good way to ground the answer, and
+beats a guess. The rule that never bends: **never invent a flag, rule id,
+config key, behaviour, or command output** — read the page, read the
+source, or run the command, and quote only output you actually saw. A
+confident wrong answer about a type checker is worse than "let me check."
+
+## Examples
+
+**A diagnostic on their code** — *"Why is Rigor flagging `s.lenght`?"*
+
+```sh
+rigor explain call.undefined-method   # what the rule means and why it fires
+rigor annotate demo.rb                # the inferred type of `s` on that line
+```
+
+Answer from both: Rigor inferred a concrete `String` receiver for `s`,
+and `String` has no `lenght` (a typo for `length`) — grounded in what
+`annotate` showed, not in a guess.
+
+**A comparison** — *"How is Rigor different from Sorbet?"*
+
+```sh
+rigor docs handbook/10-sorbet         # the chapter written for this
+```
+
+Answer from the chapter's framing (RBS-superset, gradual `Dynamic`,
+inference-first) rather than a remembered summary, and name it so they
+can read on.
+
+**A capability** — *"Does Rigor understand our Sidekiq workers?"*
+
+```sh
+rigor plugins                          # is rigor-sidekiq enabled in THIS project?
+rigor docs rigor-sidekiq               # the per-plugin page: what it teaches Rigor
+```
+
+Answer from what's actually installed, plus — if useful — a scoped
+`rigor check app/workers` so they see Rigor on their real workers.
+
+**Authoring** — *"How do I type this method?"*
+
+```sh
+rigor sig-gen path/to/file.rb          # generate the RBS, show it
+rigor docs handbook/07-rbs-and-extended
+```
+
+Generate it, show the signature, and explain it from the handbook —
+preferring sig-gen's output over hand-written RBS.

data/skills/rigor-doctor/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rigor-doctor
+description: |
+  Validate that a project's Rigor setup is actually healthy — config parses with no silently-inert values, every configured plugin loads, the baseline is not stale, and the bundled paths resolve — by running Rigor's existing validators and interpreting them. Triggers: "is my Rigor setup correct?", "check my rigor config", "rigor diagnostics look wrong / suspicious", "validate rigor setup", "why is rigor reporting nothing / everything?". NOT for first-time setup (use rigor-project-init) or for working real diagnostics down (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Doctor
+
+`rigor skill describe` reports what *exists* (presence checks). This skill
+goes a level deeper: it *runs* Rigor's validators to confirm the setup is
+actually working — the difference between "a `.rigor.yml` is present" and
+"it parses, loads its plugins, and analyses the right files." Use it when
+the diagnostics look wrong (suspiciously zero, or suspiciously many) or
+after editing the config.
+
+It needs **no special command** — it orchestrates checks Rigor already
+ships and interprets the results.
+
+## Checks
+
+### 1. Config resolves with nothing silently inert
+
+```sh
+rigor check --format json   # read the `config_warnings` array
+```
+
+`rigor check` audits the config and emits `config_warnings` for the typo
+class whose only symptom is a confusing downstream error: a
+`signature_paths:` that is missing / not a directory / holds no `.rbs`
+(which would turn every covered call into a false `call.undefined-method`
+at `evidence_tier: high`), a `libraries:` name RBS does not recognise, a
+`disable:` / `severity_overrides:` id naming no real rule, or a missing
+`bundler` / `rbs_collection` path. **Each warning here is a real
+misconfiguration — fix it.** None appearing is the healthy state.
+
+### 2. Every configured plugin loads
+
+```sh
+rigor plugins --strict
+```
+
+Reports the activation status of each plugin in `plugins:`; `--strict`
+exits non-zero on any failure. A failure is usually a misspelled id or a
+plugin whose `signature_paths:` did not resolve. Fix it, or the plugin's
+type knowledge is silently absent.
+
+### 3. The baseline is not stale (if one exists)
+
+```sh
+rigor baseline drift
+```
+
+Shows whether the live diagnostics have drifted from `.rigor-baseline.yml`
+— entries the baseline ignores that no longer occur (safe to prune) and
+new diagnostics outside the envelope. A large drift means the baseline
+needs regenerating (often after an upgrade — see `rigor-upgrade`).
+
+### 4. The analysis is actually seeing your code
+
+```sh
+rigor check --format json   # check the "Ruby source files" count
+```
+
+If the file count is `0` or far below your project size, `paths:` /
+`exclude:` are mis-scoped, or the command is running from the wrong
+directory. The analysis is only as good as the files it reads.
+
+## Interpreting the result
+
+- **All clean** → the setup is healthy; any diagnostics are about the
+  code, not the configuration. Move on to `rigor-baseline-reduce` or
+  `rigor-protection-uplift`.
+- **A `config_warning` or a plugin failure** → that is the real problem;
+  fixing it usually resolves a whole cluster of confusing downstream
+  diagnostics at once.
+
+For deeper symptoms (hover shows `untyped` everywhere, completion empty,
+LSP silent) see the manual's troubleshooting:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/13-troubleshooting.md>
+
+## Next step
+
+Re-run `rigor skill describe` for the recommended next move.