rigortype 0.3.0 → 0.3.2

data/lib/rigor/cli/mutation_protection_report.rb

@@ -9,7 +9,14 @@ module Rigor
     #
     # The framing is load-bearing (ADR-63 Criterion A / ADR-62 Criterion A): the number is *effectiveness*, the
     # survivors are *missed breakages / where to add a type*, never "your code is broken".
-    FileEffectiveness = Data.define(:path, :killed, :survived, :ratio)
+    # `harness_errors` (#264) — mutants where the harness itself raised (a rescued failure), distinguished from
+    # a parse-invalid mutant. Defaults to 0 so existing call sites keep constructing a `FileEffectiveness`
+    # without the new keyword.
+    FileEffectiveness = Data.define(:path, :killed, :survived, :ratio, :harness_errors) do
+      def initialize(path:, killed:, survived:, ratio:, harness_errors: 0)
+        super
+      end
+    end
     MissedBreakage = Data.define(:method_name, :count, :examples)
 
     MutationProtectionReport = Data.define(:files, :missed, :parse_errors) do
@@ -18,15 +25,22 @@ module Rigor
       def grand_total = total_killed + total_survived
       def ratio = grand_total.zero? ? 1.0 : total_killed.to_f / grand_total
 
+      # #264 — a harness-level failure count, summed across files. Stays OUT of `grand_total`/`ratio` exactly
+      # like a parse error: it is not a measurement of the code.
+      def total_harness_errors = files.sum(&:harness_errors)
+
       def to_h
         {
           "mode" => "mutation",
           "killed" => total_killed,
           "survived" => total_survived,
           "effectiveness_ratio" => ratio.round(4),
+          # #264 — unconditional: a JSON consumer (e.g. a CI gate) must be able to check this every run, not
+          # only when a text renderer decided it was worth a line.
+          "harness_errors" => total_harness_errors,
           "files" => files.map do |f|
-            { "path" => f.path, "killed" => f.killed,
-              "survived" => f.survived, "ratio" => f.ratio.round(4) }
+            { "path" => f.path, "killed" => f.killed, "survived" => f.survived,
+              "ratio" => f.ratio.round(4), "harness_errors" => f.harness_errors }
           end,
           "add_a_type_here" => missed.map do |m|
             { "method" => m.method_name, "count" => m.count, "examples" => m.examples }
@@ -46,7 +60,8 @@ module Rigor
       def absorb(file_result)
         @files << FileEffectiveness.new(
           path: file_result.path, killed: file_result.killed,
-          survived: file_result.survived, ratio: file_result.ratio
+          survived: file_result.survived, ratio: file_result.ratio,
+          harness_errors: file_result.harness_errors
         )
         file_result.sites.each do |site|
           bucket = @missed[site.method_name]
@@ -56,7 +71,13 @@ module Rigor
       end
 
       def record_parse_error(path, errors)
-        @parse_errors << { "path" => path, "errors" => errors.size }
+        record_parse_error_count(path, errors.size)
+      end
+
+      # Count-based variant for the fork-pool path, where a worker carries only the marshalable error count
+      # (see {MutationForkScan::ParseError}), not the Prism error objects.
+      def record_parse_error_count(path, count)
+        @parse_errors << { "path" => path, "errors" => count }
       end
 
       def to_report

data/lib/rigor/cli/protection_renderer.rb

@@ -40,10 +40,23 @@ module Rigor
         @out.puts "Type-protection coverage (Tier 1 — dispatch-site receiver concreteness)"
         @out.puts "  protected dispatch sites: #{report.total_protected} / #{report.grand_total}  (#{pct}%)"
         @out.puts "  (protected = Rigor can catch a wrong call here; an upper bound on real protection)"
+        render_lower_bound_typed(report)
         render_untyped_calls(report)
         render_files(report)
       end
 
+      # ADR-67 WD6b (issue #263) — a sub-bucket WITHIN `protected`, never a move out of it: these sites'
+      # receiver types are call-site lower bounds (an undeclared parameter seeded from its callers), so the
+      # negative in-body rules decline on them — no diagnostic actually fires here yet. Silent when zero, the
+      # normal `check` / unseeded-scope case.
+      def render_lower_bound_typed(report)
+        m = report.total_lower_bound_typed
+        return if m.zero?
+
+        @out.puts "  protected #{report.total_protected} (of which #{m} lower-bound-typed — " \
+                  "no negative-rule teeth, ADR-67 WD6b)"
+      end
+
       def render_untyped_calls(report)
         calls = report.untyped_calls
         return if calls.empty?

data/lib/rigor/cli/protection_report.rb

@@ -8,7 +8,7 @@ module Rigor
     # the protected ratio, the per-file breakdown, and a ranked "add a type here" list keyed by the method called on an
     # unprotected (`Dynamic`) receiver — the highest-traffic untyped dispatches, where a receiver annotation buys the
     # most catching power.
-    FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio)
+    FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio, :lower_bound_typed)
     UntypedCall = Data.define(:method_name, :count, :examples, :dynamic_origin)
 
     ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors, :cause_site_counts) do
@@ -17,6 +17,11 @@ module Rigor
       def grand_total = total_protected + total_unprotected
       def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
 
+      # ADR-67 WD6b (issue #263) — total count of `protected` sites that are additionally lower-bound-typed
+      # (a call-site-inferred, undeclared parameter): a sub-bucket WITHIN `total_protected`, never a move out
+      # of it. `total_protected` / `ratio` are unaffected by this count.
+      def total_lower_bound_typed = files.sum(&:lower_bound_typed)
+
       # ADR-73 P6 / ADR-82 — 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
@@ -43,11 +48,13 @@ module Rigor
           "protected" => total_protected,
           "unprotected" => total_unprotected,
           "protection_ratio" => ratio.round(4),
+          "lower_bound_typed" => total_lower_bound_typed,
           "tractability_summary" => tractability_summary.transform_keys(&:to_s),
           "cause_site_counts" => cause_site_totals,
           "files" => files.map do |f|
             { "path" => f.path, "protected" => f.protected_count,
-              "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4) }
+              "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4),
+              "lower_bound_typed" => f.lower_bound_typed }
           end,
           "add_a_type_here" => untyped_calls.map do |c|
             entry = { "method" => c.method_name, "count" => c.count, "examples" => c.examples }
@@ -74,7 +81,8 @@ module Rigor
       def absorb(path, file_result)
         @files << FileProtection.new(
           path: path, protected_count: file_result.protected_count,
-          unprotected_count: file_result.unprotected_count, ratio: file_result.ratio
+          unprotected_count: file_result.unprotected_count, ratio: file_result.ratio,
+          lower_bound_typed: file_result.lower_bound_typed
         )
         file_result.sites.each do |site|
           bucket = @calls[site.method_name]

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -13,8 +13,9 @@ module Rigor
     #
     # Prints the bleeding-edge overlay — the Rigor-maintained set of the next major's queued changes
     # ({Rigor::BleedingEdge}) — as an explicit list, and reports which of them the project's `bleeding_edge:`
-    # configuration adopts. The overlay is empty in this release, so the command currently reports an empty set; it
-    # becomes the inspection surface ADR-50 describes once a feature is queued.
+    # configuration adopts. Each feature is rendered with its kind: a `severity` feature prints the rule → severity
+    # diff it imposes, and a `behaviour` feature has no such diff to print, so its summary carries the whole
+    # explanation. Ids that have already graduated to default-on (ADR-50 § WD7) are listed after the overlay.
     #
     # Read-only: it loads `.rigor.yml` to resolve the active selection but runs no analysis.
     class ShowBleedingedgeCommand < Command
@@ -62,7 +63,8 @@ module Rigor
                     "overlay" => BleedingEdge.features.map(&:to_h),
                     "selector" => configuration.to_h.fetch("bleeding_edge"),
                     "active" => BleedingEdge.active_features(selector).map(&:id),
-                    "unknown_selected" => BleedingEdge.unknown_selected_ids(selector)
+                    "unknown_selected" => BleedingEdge.unknown_selected_ids(selector),
+                    "graduated" => BleedingEdge::GRADUATED
                   ))
       end
 
@@ -74,6 +76,7 @@ module Rigor
         else
           render_overlay
         end
+        render_graduated
         @out.puts("")
         render_selection(configuration)
       end
@@ -88,7 +91,7 @@ module Rigor
         @out.puts("#{BleedingEdge.features.length} feature(s) queued for the next major:")
         @out.puts("")
         BleedingEdge.features.each do |feature|
-          @out.puts("  #{feature.id}")
+          @out.puts("  #{feature.id} [#{feature.kind}]")
           @out.puts("    #{feature.summary}")
           feature.severity_overrides.each do |rule, severity|
             @out.puts("    severity: #{rule} → :#{severity}")
@@ -96,6 +99,16 @@ module Rigor
         end
       end
 
+      # ADR-50 § WD7 — only printed when something has graduated, so a release with an empty list reads exactly
+      # as it did before graduation existed.
+      def render_graduated
+        return if BleedingEdge::GRADUATED.empty?
+
+        @out.puts("")
+        @out.puts("Graduated — on by default, no longer selectable:")
+        BleedingEdge::GRADUATED.each { |id| @out.puts("  #{id}") }
+      end
+
       def render_selection(configuration)
         selector = configuration.bleeding_edge
         active = BleedingEdge.active_features(selector).map(&:id)

data/lib/rigor/cli/sig_gen_command.rb

@@ -97,10 +97,11 @@ module Rigor
         results = writer.write_all(candidates)
 
         SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
-        # An assembled file that does not parse is refused rather than written. The user asked for a write and
-        # did not get one, so the command must not report success — a green `sig-gen --write` in CI would
-        # otherwise mean nothing.
-        results.any? { |result| result.action == :skipped_invalid_rbs } ? 1 : 0
+        # A refused write (an assembled file that does not parse, or an existing target that is not valid
+        # UTF-8) means the user asked for a write and did not get one, so the command must not report
+        # success — a green `sig-gen --write` in CI would otherwise mean nothing.
+        refusals = %i[skipped_invalid_rbs skipped_invalid_encoding]
+        results.any? { |result| refusals.include?(result.action) } ? 1 : 0
       end
 
       # Slice 3 — collect call-site argument observations when `--params=observed` is set. When `--observe=PATH` is not

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

data/lib/rigor/cli/skill_describe.rb

@@ -142,27 +142,43 @@ module Rigor
 
       # @param skills [Array<Hash>] discovered skills, each `{name:, path:}`.
       # @param root [String] project root to probe (defaults to the cwd).
-      def initialize(skills:, root: Dir.pwd)
+      # @param deep [Boolean] opt into `--deep`: run a real `rigor check` and let its result pick the headline. Off by
+      #   default, and off is ADR-73 WD2's contract — see {SkillDeepProbe} for why the whole analysis path lives
+      #   behind this one flag and in its own file.
+      def initialize(skills:, root: Dir.pwd, deep: false)
         @skills = skills
         @root = root
+        @deep = deep
       end
 
       # @return [String] the full describe report.
       def render
         catalog = catalog_skills
         state = ProjectStateProbe.new(@root).to_h
-        recommendation = recommend(state, catalog)
+        deep = deep_report(state)
+        recommendation = recommend(state, catalog, deep)
         [
           title,
           state_section(state),
+          deep_section(deep),
           recommendation_section(recommendation),
           catalog_section(catalog),
-          agent_prompt(recommendation)
-        ].join("\n")
+          agent_prompt(recommendation, deep)
+        ].compact.join("\n")
       end
 
       private
 
+      # The `--deep` analysis, or nil when the flag was not given. `require` sits here rather than at the top of the
+      # file so the default, presence-only path never even loads the check-invocation plumbing — WD2's "runs no
+      # analysis" guarantee is enforced by what gets loaded, not only by what gets called.
+      def deep_report(state)
+        return nil unless @deep
+
+        require_relative "skill_deep_probe"
+        SkillDeepProbe.new(config: state.fetch(:config), root: @root).run
+      end
+
       # The skills offered as "what to do next", in adoption-journey order. The entry-point skill is excluded, and
       # unknown skills sort after the known journey, alphabetically.
       def catalog_skills
@@ -173,8 +189,12 @@ module Rigor
 
       # The decision tree (ADR-73 WD2). Returns `{ skill:, reason: }` for the recommended next step, or nil when no
       # catalogue skill matches.
-      def recommend(state, catalog)
-        name, reason = recommended_name_and_reason(state)
+      #
+      # A `--deep` report overrides the presence-only tree only when it actually routed: a check that was skipped,
+      # could not run, or ran clean leaves the tree's answer standing untouched. So the un-flagged behaviour is
+      # literally the `deep == nil` branch of this one method.
+      def recommend(state, catalog, deep = nil)
+        name, reason = deep&.route ? [deep.route, deep.reason] : recommended_name_and_reason(state)
         skill = catalog.find { |candidate| candidate.fetch(:name) == name }
         skill.nil? ? nil : { skill: skill, reason: reason }
       end
@@ -248,6 +268,18 @@ module Rigor
         STATE
       end
 
+      # Printed only under `--deep`, so the un-flagged report is byte-identical to what it has always been.
+      def deep_section(deep)
+        return nil if deep.nil?
+
+        <<~DEEP
+          ## Deep check (--deep)
+          A real `rigor check` was run for this recommendation — unlike the probe above it
+          is slow and it writes `.rigor/cache`, exactly as `rigor check` does.
+          - Result: #{deep.detail}
+        DEEP
+      end
+
       def recommendation_section(recommendation)
         return "## Recommended next step\n- (no bundled skill matched the current state)\n" if recommendation.nil?
 
@@ -267,7 +299,7 @@ module Rigor
         "## All skills you can run next\n#{lines.join("\n")}\n"
       end
 
-      def agent_prompt(recommendation)
+      def agent_prompt(recommendation, deep = nil)
         opener =
           if recommendation.nil?
             "Ask the user what they would like to do next"
@@ -279,6 +311,33 @@ module Rigor
           #{opener}, then run `rigor skill <name>` for the chosen skill and
           follow its body top to bottom.
 
+          #{check_awareness(deep)}
+
+          Re-run `rigor skill describe` whenever you need the next step — it always
+          reflects the project's current state.
+        PROMPT
+      end
+
+      # The check-aware routing block. Without `--deep` it teaches the agent to make the call itself from a check it
+      # has already run (the 2026-06-20 field-trial fix, unchanged); with `--deep` the headline already made that
+      # call, so the block reports what happened instead of re-teaching it. The routing vocabulary is one taxonomy
+      # shared by both branches and by {SkillDeepProbe}.
+      def check_awareness(deep)
+        return presence_only_check_awareness if deep.nil?
+        return deep_failure_check_awareness if deep.failed?
+
+        <<~DEEP.chomp
+          The recommendation above already factors in the `--deep` check result, using the
+          same routing this command teaches without `--deep`: proven project monkey-patches
+          → rigor-monkeypatch-resolve; `RBS classes available: 0` or a `configuration-error`
+          → rigor-doctor; remaining error diagnostics → rigor-baseline-reduce. It does not
+          route on weaker signals (framework calls typing as Dynamic → rigor-plugin-tune is
+          still yours to judge from the check output).
+        DEEP
+      end
+
+      def presence_only_check_awareness
+        <<~PROMPT.chomp
           The recommendation above is from a presence-only probe — it does not run
           `rigor check`. If you have run (or now run) `rigor check`, let its findings
           refine the choice:
@@ -287,9 +346,16 @@ module Rigor
           - framework calls (ActiveRecord, routes, i18n …) typing as Dynamic with no
             matching plugins enabled → rigor-plugin-tune
           - `RBS classes available: 0` or a `configuration-error` diagnostic → rigor-doctor
+          (`rigor skill describe --deep` runs that check for you and applies this routing
+          to the headline itself — at the cost of a full analysis.)
+        PROMPT
+      end
 
-          Re-run `rigor skill describe` whenever you need the next step — it always
-          reflects the project's current state.
+      def deep_failure_check_awareness
+        <<~PROMPT.chomp
+          The `--deep` check did NOT complete, so the recommendation above is the
+          presence-only one. Do not treat the project as clean: run `rigor doctor`
+          (or `rigor check`) and fix what it reports before trusting any routing.
         PROMPT
       end