rigortype 0.2.5 → 0.2.7

data/lib/rigor/cli/doctor_command.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+require_relative "../configuration"
+require_relative "../config_audit"
+require_relative "../analysis/baseline"
+require_relative "../analysis/result"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+require_relative "check_runner_factory"
+require_relative "command"
+require_relative "options"
+
+module Rigor
+  class CLI
+    # `rigor doctor` — classify existing project findings into setup-problem
+    # vs clean-run with a routed next action (ADR-77 WD1).
+    #
+    # It is a presentation/aggregation layer over data `rigor check` already
+    # produces — no new analysis pass and no new diagnostic rule.  The
+    # command runs a scoped analysis to gather stats, audits the
+    # configuration, validates plugins, and checks baseline drift, then
+    # reports a small fixed set of checks with a hint for each failure.
+    class DoctorCommand < Command # rubocop:disable Metrics/ClassLength
+      USAGE = "Usage: rigor doctor [options]"
+
+      # Check identifiers — the stable JSON contract (`checks[].id`).
+      CHECK_CONFIG = "config_audit"
+      CHECK_RBS = "rbs_environment"
+      CHECK_PLUGINS = "plugins"
+      CHECK_BASELINE = "baseline"
+      CHECK_RAILS = "rails_plugins"
+
+      RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
+      RAILS_PLUGIN_MARKERS = %w[
+        rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
+        rigor-rails-routes rigor-rails-i18n rigor-actioncable rigor-activestorage rigor-rails
+      ].freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        configuration = Configuration.load(options.fetch(:config))
+        findings = []
+
+        # 1. Config audit (cheap — no analysis needed).
+        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(
+          configuration: configuration,
+          options: { no_cache: true, explain: false, stats: true, workers: 0 },
+          buffer: nil,
+          cache_root: configuration.cache_path
+        )
+        result = runner.run(configuration.paths)
+
+        # 3. RBS environment check.
+        findings.concat(check_rbs_environment(result))
+
+        # 4. Plugin load check.
+        findings.concat(check_plugins(configuration))
+
+        # 5. Baseline drift check.
+        findings.concat(check_baseline(configuration, result))
+
+        # 6. Rails locked but no Rails plugins.
+        findings.concat(check_rails_plugins(configuration))
+
+        report(findings, options.fetch(:format))
+        findings.any? { |f| f[:status] == :fail } ? 1 : 0
+      rescue OptionParser::InvalidArgument => e
+        @err.puts(e.message)
+        CLI::EXIT_USAGE
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text" }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          Options.add_config(opts, options)
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
+        end.parse!(@argv)
+        validate!(options)
+        options
+      end
+
+      def validate!(options)
+        return if %w[text json].include?(options.fetch(:format))
+
+        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      end
+
+      # ------------------------------------------------------------------
+      # Individual checks — each returns an Array of finding Hashes.
+      # A finding has: :check, :status (:pass/:fail/:warn), :message, :hint
+      # ------------------------------------------------------------------
+
+      def audit_config(configuration)
+        warnings = ConfigAudit.warnings(configuration, project_root: Dir.pwd)
+        return [] if warnings.empty?
+
+        messages = warnings.map(&:message)
+        [
+          {
+            check: CHECK_CONFIG,
+            status: :fail,
+            message: "Configuration warnings: #{messages.size}",
+            hint: "Review and fix the flagged entries in your config file."
+          }
+        ]
+      end
+
+      def check_rbs_environment(result)
+        stats = result.stats
+        return [] unless stats
+
+        if stats.rbs_classes_total.zero?
+          [
+            {
+              check: CHECK_RBS,
+              status: :fail,
+              message: "RBS environment is empty (#{stats.rbs_classes_total} classes available)",
+              hint: "The RBS environment failed to build or loaded no signatures. " \
+                    "Check `signature_paths:` for duplicate declarations, or run " \
+                    "`rbs collection install` for gem signatures."
+            }
+          ]
+        else
+          [
+            {
+              check: CHECK_RBS,
+              status: :pass,
+              message: "RBS environment healthy (#{stats.rbs_classes_total} classes available)",
+              hint: nil
+            }
+          ]
+        end
+      end
+
+      def check_plugins(configuration)
+        services = Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: nil
+        )
+        registry = Plugin::Loader.load(configuration: configuration, services: services)
+        errors = registry.load_errors
+        return [] if errors.empty?
+
+        [
+          {
+            check: CHECK_PLUGINS,
+            status: :fail,
+            message: "Plugin load errors: #{errors.size}",
+            hint: "Run `rigor plugins --strict` for the full per-plugin report."
+          }
+        ]
+      end
+
+      def check_baseline(configuration, result)
+        path = configuration.baseline_path
+        return [] if path.nil? || !File.exist?(path)
+
+        baseline = Analysis::Baseline.load(path, project_root: Dir.pwd)
+        return [] if baseline.nil? || baseline.empty?
+
+        drifted = baseline.audit(result.diagnostics).reject { |row| row.status == :within }
+        return [] if drifted.empty?
+
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :fail,
+            message: "Baseline drift detected (#{baseline_drift_summary(drifted)})",
+            hint: "Run `rigor baseline regenerate` to refresh the baseline."
+          }
+        ]
+      rescue Analysis::Baseline::LoadError, Psych::SyntaxError => e
+        [
+          {
+            check: CHECK_BASELINE,
+            status: :warn,
+            message: "Baseline load failed: #{e.message}",
+            hint: "Check the baseline file path in your config."
+          }
+        ]
+      end
+
+      def baseline_drift_summary(drifted)
+        counts = drifted.group_by(&:status).transform_values(&:size)
+        parts = []
+        parts << "#{counts.fetch(:over, 0)} over threshold" if counts.key?(:over)
+        parts << "#{counts.fetch(:cleared, 0)} cleared" if counts.key?(:cleared)
+        parts << "#{counts.fetch(:reducible, 0)} reducible" if counts.key?(:reducible)
+        parts.join(", ")
+      end
+
+      def check_rails_plugins(configuration)
+        return [] unless rails_unconfigured?(configuration)
+
+        [
+          {
+            check: CHECK_RAILS,
+            status: :fail,
+            message: "Rails detected but no Rails plugins enabled",
+            hint: "Add Rails plugins (e.g. rigor-activerecord, rigor-actionpack) to " \
+                  "`.rigor.yml` `plugins:` so framework calls resolve."
+          }
+        ]
+      end
+
+      # True when Rails is in Gemfile.lock but the config enables no
+      # Rails plugin — the same probe {ProjectStateProbe} uses.
+      def rails_unconfigured?(_configuration)
+        config_path = Configuration.discover
+        return false if config_path.nil?
+        return false unless File.file?(config_path)
+
+        lock = File.join(Dir.pwd, "Gemfile.lock")
+        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
+
+        !file_mentions_any?(config_path, RAILS_PLUGIN_MARKERS)
+      end
+
+      def file_mentions_any?(path, markers)
+        content = File.read(path)
+        markers.any? { |marker| content.include?(marker) }
+      rescue StandardError
+        false
+      end
+
+      # ------------------------------------------------------------------
+      # Reporting
+      # ------------------------------------------------------------------
+
+      def report(findings, format)
+        case format
+        when "json" then report_json(findings)
+        else report_text(findings)
+        end
+      end
+
+      def report_json(findings)
+        payload = {
+          "status" => findings.any? { |f| f[:status] == :fail } ? "issues_found" : "clean",
+          "checks" => findings.map do |f|
+            {
+              "id" => f[:check].to_s,
+              "status" => f[:status].to_s,
+              "message" => f[:message],
+              "hint" => f[:hint]
+            }
+          end
+        }
+        @out.puts(JSON.pretty_generate(payload))
+      end
+
+      def report_text(findings)
+        failures = findings.select { |f| f[:status] == :fail }
+        warnings = findings.select { |f| f[:status] == :warn }
+        passes = findings.select { |f| f[:status] == :pass }
+
+        if failures.empty? && warnings.empty?
+          @out.puts("rigor doctor: all checks passed — no setup problems detected.")
+        else
+          @out.puts("rigor doctor: #{failures.size} issue(s) found")
+          failures.each { |f| print_finding(f) }
+          warnings.each { |f| print_finding(f) } unless warnings.empty?
+        end
+
+        passes.each { |f| print_finding(f) } unless passes.empty?
+      end
+
+      def print_finding(finding)
+        label = case finding[:status]
+                when :fail then "[FAIL]"
+                when :warn then "[WARN]"
+                else "[PASS]"
+                end
+        @out.puts("#{label} #{finding[:check]}: #{finding[:message]}")
+        @out.puts("  → #{finding[:hint]}") if finding[:hint]
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugins_command.rb

@@ -37,7 +37,7 @@ module Rigor
     #   `source_rbs_synthesizer:`);
     # - the ADR-37 narrow extension protocols read off the plugin
     #   class — `node_rule` node types, `dynamic_return` receivers,
-    #   `type_specifier` methods.
+    #   `narrowing_facts` methods.
     #
     # `--capabilities` switches to a focused catalogue of just the
     # narrow-protocol gate values + produced/consumed facts (ADR-37
@@ -194,7 +194,7 @@ module Rigor
 
       # ADR-37 narrow extension protocols. Unlike the 10 declarative
       # manifest fields, these are class-level DSLs (`node_rule` /
-      # `dynamic_return` / `type_specifier`), so they are read off the
+      # `dynamic_return` / `narrowing_facts`), so they are read off the
       # plugin class rather than the manifest. The gate values — node
       # types, receiver class names, specified method names — are the
       # greppable, enumerable surface the capability catalogue exposes.

data/lib/rigor/cli/plugins_renderer.rb

@@ -170,7 +170,7 @@ module Rigor
       end
 
       # ADR-37 narrow extension protocols (node_rule / dynamic_return /
-      # type_specifier). Surfaced in the full report alongside the
+      # narrowing_facts). Surfaced in the full report alongside the
       # declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
         lines = []

data/lib/rigor/cli/protection_renderer.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text
@@ -12,6 +14,15 @@ module Rigor
       TOP_CALLS = 15
       TOP_FILES = 10
 
+      # ADR-73 P6 / ADR-75 WD2 — the actionable axis for each tractability
+      # category, shown next to a hole's origin so a user knows whether (and
+      # how) a type can close it.
+      TRACTABILITY_HINTS = {
+        Inference::DynamicOrigin::ADD_RBS => "add RBS",
+        Inference::DynamicOrigin::ENABLE_PLUGIN => "enable a plugin / pre_eval",
+        Inference::DynamicOrigin::ENGINE_GAP => "engine gap — report it"
+      }.freeze
+
       def initialize(out:)
         @out = out
       end
@@ -40,13 +51,32 @@ module Rigor
         return if calls.empty?
 
         @out.puts "\nAdd a type here — methods most often called on an untyped receiver:"
+        render_tractability_summary(report)
         calls.first(TOP_CALLS).each do |call|
-          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s",
-                           count: call.count, method: call.method_name, sites: call.examples.join("  "))
+          label = origin_label(call.dynamic_origin)
+          @out.puts format("  %<count>-5d #%<method>s   e.g. %<sites>s%<label>s",
+                           count: call.count, method: call.method_name,
+                           sites: call.examples.join("  "), label: label)
         end
         @out.puts "  (#{calls.size - TOP_CALLS} more)" if calls.size > TOP_CALLS
       end
 
+      def render_tractability_summary(report)
+        summary = report.tractability_summary
+        return if summary.empty?
+
+        parts = summary.sort_by { |_, n| -n }.map { |axis, n| "#{n} #{axis.to_s.tr('_', '-')}" }
+        @out.puts "  by tractability: #{parts.join(' · ')}  (add-rbs = closable with a type)"
+      end
+
+      def origin_label(origin)
+        return "" if origin.nil?
+
+        tractability = Inference::DynamicOrigin.tractability(origin)
+        hint = tractability ? " → #{TRACTABILITY_HINTS[tractability]}" : ""
+        "  [#{origin.to_s.tr('_', '-')}#{hint}]"
+      end
+
       def render_files(report)
         worst = report.files.reject { |f| f.unprotected_count.zero? }.sort_by(&:ratio).first(TOP_FILES)
         return if worst.empty?

data/lib/rigor/cli/protection_report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../inference/dynamic_origin"
+
 module Rigor
   class CLI
     # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner}
@@ -9,7 +11,7 @@ module Rigor
     # untyped dispatches, where a receiver annotation buys the most catching
     # power.
     FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio)
-    UntypedCall = Data.define(:method_name, :count, :examples)
+    UntypedCall = Data.define(:method_name, :count, :examples, :dynamic_origin)
 
     ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors) do
       def total_protected = files.sum(&:protected_count)
@@ -17,17 +19,37 @@ module Rigor
       def grand_total = total_protected + total_unprotected
       def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
 
+      # ADR-73 P6 — total dispatch-site count per tractability axis across
+      # the classified holes (those with a recorded `dynamic_origin`), so a
+      # user sees at a glance how much of the untyped surface a type can
+      # actually close (`add_rbs`) vs. needs a plugin (`enable_plugin`) vs.
+      # is an engine gap. Keys are omitted when zero; an all-unclassified
+      # run yields `{}`.
+      def tractability_summary
+        untyped_calls.each_with_object(Hash.new(0)) do |c, acc|
+          axis = c.dynamic_origin && Inference::DynamicOrigin.tractability(c.dynamic_origin)
+          acc[axis] += c.count if axis
+        end
+      end
+
       def to_h
         {
           "protected" => total_protected,
           "unprotected" => total_unprotected,
           "protection_ratio" => ratio.round(4),
+          "tractability_summary" => tractability_summary.transform_keys(&:to_s),
           "files" => files.map do |f|
             { "path" => f.path, "protected" => f.protected_count,
               "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4) }
           end,
           "add_a_type_here" => untyped_calls.map do |c|
-            { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+            entry = { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
+            if c.dynamic_origin
+              entry["dynamic_origin"] = c.dynamic_origin
+              tractability = Inference::DynamicOrigin.tractability(c.dynamic_origin)
+              entry["tractability"] = tractability if tractability
+            end
+            entry
           end,
           "parse_errors" => parse_errors
         }
@@ -37,7 +59,7 @@ module Rigor
     class ProtectionAccumulator
       def initialize
         @files = []
-        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [], origins: Hash.new(0) } }
         @parse_errors = []
       end
 
@@ -50,6 +72,7 @@ module Rigor
           bucket = @calls[site.method_name]
           bucket[:count] += 1
           bucket[:examples] << "#{path}:#{site.line}" if bucket[:examples].size < 3
+          bucket[:origins][site.dynamic_origin] += 1 if site.dynamic_origin
         end
       end
 
@@ -58,9 +81,12 @@ module Rigor
       end
 
       def to_report
-        untyped = @calls
-                  .map { |method, v| UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples]) }
-                  .sort_by { |c| [-c.count, c.method_name] }
+        calls = @calls.map do |method, v|
+          origin = v[:origins].max_by { |_, count| count }&.first
+          UntypedCall.new(method_name: method, count: v[:count], examples: v[:examples],
+                          dynamic_origin: origin)
+        end
+        untyped = calls.sort_by { |c| [-c.count, c.method_name] }
         ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors)
       end
     end

data/lib/rigor/cli/skill_command.rb

@@ -25,6 +25,12 @@ module Rigor
     #                                inline body plus the header's absolute
     #                                paths let the agent act with or without
     #                                a file-reading tool.
+    # - `rigor skill --full <name>`— the body AND every `references/*.md`
+    #                                inline: the complete, version-current
+    #                                procedure in one call. The thinned SKILL
+    #                                bodies point a *frozen* (vendored) copy
+    #                                at this so the reader follows the gem's
+    #                                current steps, not a stale local copy.
     # - `rigor skill --path <name>`— one-line absolute path, for a Read tool.
     # - `rigor skill --list`       — table of name + absolute path.
     # - `rigor skill --describe`   — ADR-73's live entry point: a cheap
@@ -43,12 +49,14 @@ module Rigor
     # verb, so it stays first-class alongside `--describe`.
     class SkillCommand < Command
       USAGE = <<~USAGE
-        Usage: rigor skill [<name>] [--path <name>] [--list] [--describe]
+        Usage: rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 
         With no argument, lists the bundled skills.
 
           rigor skill                List bundled skills
           rigor skill <name>         Print the SKILL.md body for <name> (with a header)
+          rigor skill --full <name>  Print the SKILL.md body AND its references/ inline
+                                     (the complete, version-current procedure in one call)
           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
@@ -56,6 +64,7 @@ module Rigor
         Examples:
           rigor skill
           rigor skill rigor-project-init
+          rigor skill --full rigor-baseline-reduce
           rigor skill --path rigor-baseline-reduce
           rigor skill --describe        (also: rigor describe)
 
@@ -95,6 +104,9 @@ module Rigor
         when "--list"
           @argv.shift
           run_list
+        when "--full"
+          @argv.shift
+          run_full(@argv.shift)
         when "--path"
           @argv.shift
           run_path(@argv.shift)
@@ -147,6 +159,34 @@ module Rigor
         0
       end
 
+      # `rigor skill --full <name>` — the whole current procedure in one
+      # call: the SKILL.md body followed by each `references/*.md` inline.
+      # This is what the thinned SKILL bodies point a *frozen* copy at — a
+      # vendored copy of a skill (installed via `npx skills`) may lag the
+      # gem, so re-fetching the complete body here guarantees the reader
+      # follows the version that shipped with the installed Rigor, without
+      # needing a file-reading tool or reading a possibly-stale co-located
+      # `references/`.
+      def run_full(name)
+        return usage_error("`--full` requires a skill name") if name.nil?
+
+        skill = find_skill(name)
+        return name_error(name) if skill.nil?
+
+        @out.puts(render_print_header(skill))
+        @out.puts
+        @out.write(File.read(skill.fetch(:path)))
+
+        reference_files(skill).each do |ref|
+          @out.puts
+          @out.puts
+          @out.puts("<!-- ===== references/#{File.basename(ref)} (bundled with rigortype #{Rigor::VERSION}) ===== -->")
+          @out.puts
+          @out.write(File.read(ref))
+        end
+        0
+      end
+
       def run_path(name)
         return usage_error("`--path` requires a skill name") if name.nil?
 
@@ -207,6 +247,17 @@ module Rigor
         discover_skills.find { |s| s.fetch(:name) == name }
       end
 
+      # The `references/*.md` files bundled alongside a skill, sorted so the
+      # `NN-` prefixes drive read order.
+      def reference_files(skill)
+        dir = File.join(File.dirname(skill.fetch(:path)), "references")
+        return [] unless File.directory?(dir)
+
+        # `Dir.glob` returns lexicographically sorted paths (Ruby 3.0+),
+        # so the `NN-` prefixes already drive read order.
+        Dir.glob(File.join(dir, "*.md"))
+      end
+
       def name_error(name)
         @err.puts("Unknown skill: #{name}")
         @err.puts("Available skills (try `rigor skill --list`):")

data/lib/rigor/cli/upgrade_command.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "command"
+
+module Rigor
+  class CLI
+    # `rigor upgrade` — the ADR-50 WD7 migration command skeleton.
+    #
+    # The real body lands when a concrete backwards-compatibility break
+    # gives it a target (e.g. re-running `baseline regenerate` against a
+    # strengthened default profile, surfacing renamed suppression ids,
+    # reporting `bleeding_edge:` graduations).  Until then it prints the
+    # current version and notes that upgrade is queued.
+    class UpgradeCommand < Command
+      USAGE = "Usage: rigor upgrade [options]"
+
+      # @return [Integer] CLI exit status.
+      def run
+        @out.puts("rigor upgrade: No migration target available yet (ADR-50 WD7, queued).")
+        @out.puts("Current version: #{Rigor::VERSION}")
+        0
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -43,7 +43,9 @@ module Rigor
       "skill" => :run_skill,
       "describe" => :run_describe,
       "docs" => :run_docs,
-      "show-bleedingedge" => :run_show_bleedingedge
+      "show-bleedingedge" => :run_show_bleedingedge,
+      "doctor" => :run_doctor,
+      "upgrade" => :run_upgrade
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -317,6 +319,18 @@ module Rigor
       CLI::ShowBleedingedgeCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_doctor
+      require_relative "cli/doctor_command"
+
+      CLI::DoctorCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def run_upgrade
+      require_relative "cli/upgrade_command"
+
+      CLI::UpgradeCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def help
       <<~HELP
         Usage: rigor <command> [options]
@@ -342,6 +356,8 @@ module Rigor
           skill      Recommend the next skill + list/print bundled Agent Skills (skill describe, skill <name>)
           docs       Print the bundled docs offline (docs <name>, docs --list)
           show-bleedingedge  Show the bleeding-edge overlay + what your config adopts (ADR-50)
+          doctor     Classify setup problems vs clean run with routed next actions (ADR-77)
+          upgrade    Migration command skeleton (ADR-50 WD7, queued)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/environment/rbs_loader.rb

@@ -291,12 +291,29 @@ module Rigor
         # prefix of another name is declared `module` (it is a
         # namespace); a leaf is declared `class` (referenced types
         # appear in instance position far more often than as mixins).
+        #
+        # Names already declared in `base_env` are skipped — exactly the
+        # `declared.include?` guard {.collect_missing_namespaces} applies.
+        # Without it, stubbing a nested reference (`Foo::Bar::Baz`) re-emits
+        # its enclosing prefix (`Foo::Bar`) as a `module`, and when that
+        # prefix is already a `class` in the project's own `sig/` the kind
+        # mismatch makes `resolve_type_names` raise
+        # `RBS::DuplicatedDeclarationError`, collapsing the WHOLE env to nil
+        # (every type-of query then degrades to `Dynamic[Top]`). One
+        # malformed `.rbs` must not disproportionately blind the analysis:
+        # a subclass sig that references an inherited nested type
+        # (`class GitAdapter; def x: () -> GitAdapter::Revision`) was the
+        # real-world trigger — see the 2026-07-04 redmine onboarding note.
         def append_stub_declarations(base_env, missing)
+          declared = declared_type_names(base_env)
           names = missing.to_set
           missing.each do |name|
             parts = name.split("::")
             (1...parts.length).each { |i| names << parts[0, i].join("::") }
           end
+          names = names.reject { |name| declared.include?(name) }.to_set
+          return if names.empty?
+
           source = names.sort_by { |n| n.count(":") }.map do |name|
             keyword = names.any? { |other| other != name && other.start_with?("#{name}::") } ? "module" : "class"
             "#{keyword} #{name}\nend\n"
@@ -308,6 +325,17 @@ module Rigor
           nil
         end
 
+        # The `::`-stripped names of every class / module / class-alias
+        # declaration already present in `env`, so the synthesis paths
+        # never re-declare (and thereby duplicate) a real declaration.
+        def declared_type_names(env)
+          names = env.class_decls.keys.map { |n| n.to_s.sub(/\A::/, "") }
+          if env.respond_to?(:class_alias_decls)
+            names.concat(env.class_alias_decls.keys.map { |n| n.to_s.sub(/\A::/, "") })
+          end
+          names.to_set
+        end
+
         # ADR-32 WD4 — merge synthesised-from-source RBS strings
         # into the freshly-built environment. Each entry is a
         # `[virtual_filename, rbs_source]` pair. `virtual_filename`