rigortype 0.1.12 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 182bad9de02b3b4579fe1c385fa740e30f2df85cad36d8c21647dfb09004b9eb
-  data.tar.gz: 398d4ebc670530522696122117592bd59b60d7f899ae0a8cd58b11c8506ec608
+  metadata.gz: 6f7d66cf2c7a6c883fbbab59a805b1d1bca62867022e42d9b68d0b788525e831
+  data.tar.gz: c327399cf8c239da46f383de404cd15843d8ce220b5538f1905d72f4e082a59f
 SHA512:
-  metadata.gz: abd25775ea4973023dc7ef7132669a0bf556604c7378caef60aa3c2fbae4ef79bc2651cd3499cecb8046507214dbdc4cb56bdb953c301ec42b0ebb86291202b6
-  data.tar.gz: 9281f16a4b2d39847aaaf408844920dfb9f2e6a914df3544182d6d3832f28f03ca63d8a19aa54ca80977f3431351717a59d7ba704f3361ee92697be21d6193ab
+  metadata.gz: a69935a6c878eba22f3050041d044855b9f98eefa8dc3ab55bd33ca2ecce12efc5abffb2dd0fbc57edfd7736fe5ee4eb985694e4fbcddbc63f2e231bf48483a4
+  data.tar.gz: 58839858c8a5adcf8db74ef9d8c5ed2999c4459854a85c330b107ce3a933d08cb024cacc6c1303c638ab12ae1f5bc6559c14922ac13d17f41a5609631220fc28

data/lib/rigor/analysis/check_rules.rb

@@ -57,6 +57,7 @@ module Rigor
       # system; new rules MUST register here so user configuration
       # can refer to them.
       RULE_UNDEFINED_METHOD = "call.undefined-method"
+      RULE_UNRESOLVED_TOPLEVEL = "call.unresolved-toplevel"
       RULE_WRONG_ARITY = "call.wrong-arity"
       RULE_ARGUMENT_TYPE = "call.argument-type-mismatch"
       RULE_NIL_RECEIVER = "call.possible-nil-receiver"
@@ -72,6 +73,7 @@ module Rigor
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
+        RULE_UNRESOLVED_TOPLEVEL,
         RULE_WRONG_ARITY,
         RULE_ARGUMENT_TYPE,
         RULE_NIL_RECEIVER,
@@ -162,6 +164,7 @@ module Rigor
       def call_node_diagnostics(path, node, scope_index)
         [
           undefined_method_diagnostic(path, node, scope_index),
+          unresolved_toplevel_diagnostic(path, node, scope_index),
           wrong_arity_diagnostic(path, node, scope_index),
           argument_type_diagnostic(path, node, scope_index),
           nil_receiver_diagnostic(path, node, scope_index),
@@ -365,10 +368,14 @@ module Rigor
           return nil if open_receiver?(class_name, scope)
 
           # Slice 7 phase 12 — suppress when the user has
-          # declared the method in source (instance `def`,
-          # `def self.foo`, or recognised `define_method`).
+          # declared the method in source (`def` /
+          # `define_method`) OR in a `pre_eval:` monkey-patch
+          # file (ADR-17). Both paths are project-side method
+          # contributions the dispatcher already resolved; the
+          # rule must not surface a false `undefined-method`
+          # for them.
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
-          return nil if scope.discovered_method?(class_name, call_node.name, kind)
+          return nil if source_declared_method?(scope, class_name, call_node.name, kind)
 
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
 
@@ -404,6 +411,92 @@ module Rigor
           scope.environment.rbs_module?(receiver_type.class_name)
         end
 
+        # Combined suppression probe for `undefined-method` /
+        # `unresolved-toplevel`. Returns true when the method is
+        # declared by any project-side contributor the dispatcher
+        # already resolves: an in-source `def` / `define_method`
+        # (`scope.discovered_method?`) OR an ADR-17 `pre_eval:`
+        # monkey-patch (`Environment#project_patched_methods`).
+        # Both paths sit at the same dispatcher precedence; the
+        # check must hold them together so neither rule fires a
+        # false positive.
+        def source_declared_method?(scope, class_name, method_name, kind)
+          return true if scope.discovered_method?(class_name, method_name, kind)
+
+          project_patched_method?(scope, class_name, method_name, kind)
+        end
+
+        # ADR-17 § "Inference contract" — consults
+        # `Environment#project_patched_methods` so a `def` declared
+        # in a `pre_eval:` file suppresses the diagnostic at the
+        # same dispatcher precedence the registry holds for type
+        # inference (between plugins and dependency-source).
+        # Returns false when the environment carries no registry
+        # (legacy path) or the lookup misses.
+        def project_patched_method?(scope, class_name, method_name, kind)
+          environment = scope.environment
+          registry = environment&.project_patched_methods
+          return false if registry.nil? || registry.empty?
+
+          !registry.lookup(class_name: class_name.to_s, method_name: method_name.to_sym, kind: kind).nil?
+        end
+
+        # ADR-34 — `call.unresolved-toplevel`. Fires on an
+        # implicit-self call (no explicit receiver) at toplevel
+        # scope (`scope.toplevel?`, i.e. outside any class /
+        # module body) whose name does not resolve against:
+        #
+        # 1. A same-file toplevel `def` via
+        #    {Scope#top_level_def_for}.
+        # 2. The ADR-17 `ProjectPatchedMethods` registry under
+        #    `(Object, name, :instance)` — projects declare
+        #    their toplevel-injecting monkey-patches in
+        #    `.rigor.yml`'s `pre_eval:` array as the canonical
+        #    opt-out per ADR-34 WD2.
+        # 3. The standard `Kernel` / `Object` private-method
+        #    surface (`puts`, `p`, `require`, `loop`, `raise`,
+        #    …) drawn from the loaded RBS environment.
+        #
+        # The rule deliberately does NOT generalise to
+        # implicit-self calls inside `def` / `class` / `module`
+        # bodies — ADR-24 WD3's lenient-on-unresolved default
+        # stays in force there. ADR-24 WD4's gated class-body
+        # diagnostic is a separate decision this ADR does not
+        # open.
+        #
+        # Authored severity is `:warning`; the severity profile
+        # remaps it (`strict` → `:error`, `balanced` →
+        # `:warning`, `lenient` → `:off` / suppressed).
+        def unresolved_toplevel_diagnostic(path, call_node, scope_index)
+          return nil unless call_node.receiver.nil?
+
+          scope = scope_index[call_node]
+          return nil if scope.nil?
+          return nil unless scope.toplevel?
+
+          name = call_node.name
+          return nil if scope.top_level_def_for(name)
+          return nil if source_declared_method?(scope, "Object", name, :instance)
+          return nil if Rigor::Reflection.instance_method_definition("Object", name, scope: scope)
+
+          build_unresolved_toplevel_diagnostic(path, call_node)
+        end
+
+        def build_unresolved_toplevel_diagnostic(path, call_node)
+          location = call_node.message_loc || call_node.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "unresolved toplevel call to `#{call_node.name}`. " \
+                     "If a project file defines `#{call_node.name}` via a toplevel " \
+                     "`def` or a monkey-patch on Object/Kernel, list that file in " \
+                     "`.rigor.yml`'s `pre_eval:` (ADR-17) so the analyzer sees it.",
+            severity: :warning,
+            rule: RULE_UNRESOLVED_TOPLEVEL
+          )
+        end
+
         # Returns a qualified class name for the in-scope check.
         # Nominal / Singleton carry a single-class identity
         # directly. Constant projects to its value's class.

data/lib/rigor/cli/skill_command.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Rigor
+  class CLI
+    # `rigor skill` — discover and print the SKILL.md files
+    # bundled with the `rigortype` gem.
+    #
+    # Rigor ships a small set of Agent Skills under `skills/` that
+    # walk an AI coding agent through onboarding (`rigor-project-init`),
+    # baseline reduction (`rigor-baseline-reduce`), and authoring a
+    # plugin (`rigor-plugin-author`). When Rigor is installed via
+    # `mise` / `gem install` / etc. the SKILL files live inside the
+    # gem checkout — the project being analysed has no copy, so an
+    # AI agent has no a priori way to find them.
+    #
+    # This command exposes the bundled skills via three subcommands:
+    #
+    # - `rigor skill list`         — table of name + absolute path.
+    # - `rigor skill print <name>` — short header (paths + how to use)
+    #                                followed by the SKILL.md body. This
+    #                                is the form AI agents should call;
+    #                                the inline body plus the header's
+    #                                absolute paths together let the
+    #                                agent act with or without a file
+    #                                reading tool.
+    # - `rigor skill path <name>`  — one-line absolute path, suitable
+    #                                as input to a Read tool.
+    #
+    # `rigor skill` with no subcommand is an alias for `list`.
+    class SkillCommand
+      USAGE = <<~USAGE
+        Usage: rigor skill <subcommand> [args]
+
+        Subcommands:
+          list                  List bundled skills (default when no subcommand given)
+          print <name>          Print the SKILL.md body for <name> to stdout, with a header
+          path  <name>          Print the absolute path of the SKILL.md file for <name>
+
+        Examples:
+          rigor skill list
+          rigor skill print rigor-project-init
+          rigor skill path  rigor-baseline-reduce
+      USAGE
+
+      # The bundled skills live at `<gem_root>/skills/`. From
+      # `lib/rigor/cli/skill_command.rb` that is three directories up.
+      SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
+
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        subcommand = @argv.shift || "list"
+
+        case subcommand
+        when "list" then run_list
+        when "print" then run_print
+        when "path" then run_path
+        when "-h", "--help", "help"
+          print_usage(@out)
+          0
+        else
+          @err.puts("Unknown subcommand: #{subcommand}")
+          print_usage(@err)
+          Rigor::CLI::EXIT_USAGE
+        end
+      end
+
+      private
+
+      def run_list
+        skills = discover_skills
+        if skills.empty?
+          @err.puts("No bundled skills found under #{SKILLS_ROOT}")
+          return 1
+        end
+
+        width = skills.map { |s| s.fetch(:name).length }.max
+        skills.each do |skill|
+          @out.puts(format("%-#{width}s  %s", skill.fetch(:name), skill.fetch(:path)))
+        end
+        0
+      end
+
+      def run_print
+        name = @argv.shift
+        return usage_error("`print` 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)))
+        0
+      end
+
+      def run_path
+        name = @argv.shift
+        return usage_error("`path` requires a skill name") if name.nil?
+
+        skill = find_skill(name)
+        return name_error(name) if skill.nil?
+
+        @out.puts(skill.fetch(:path))
+        0
+      end
+
+      # The header that precedes the SKILL.md body when an agent
+      # runs `rigor skill print <name>`. Kept as `# `-prefixed
+      # comment lines so the combined output remains parseable as
+      # markdown — anything below `---` (the SKILL frontmatter
+      # marker) is unchanged.
+      def render_print_header(skill)
+        references_dir = File.join(File.dirname(skill.fetch(:path)), "references")
+        ref_line = if File.directory?(references_dir)
+                     "# References: #{references_dir}/  (read referenced `references/NN-*.md` files from here)"
+                   else
+                     "# References: (none)"
+                   end
+        <<~HEADER.chomp
+          # Rigor skill: #{skill.fetch(:name)}
+          # Source:     #{skill.fetch(:path)}
+          #{ref_line}
+          #
+          # The body below is the canonical SKILL definition shipped with
+          # rigortype #{Rigor::VERSION}. Follow its instructions.
+        HEADER
+      end
+
+      def discover_skills
+        return [] unless File.directory?(SKILLS_ROOT)
+
+        Dir.children(SKILLS_ROOT).sort.filter_map do |name|
+          skill_md = File.join(SKILLS_ROOT, name, "SKILL.md")
+          next unless File.file?(skill_md)
+
+          { name: name, path: skill_md }
+        end
+      end
+
+      def find_skill(name)
+        discover_skills.find { |s| s.fetch(:name) == name }
+      end
+
+      def name_error(name)
+        @err.puts("Unknown skill: #{name}")
+        @err.puts("Available skills:")
+        discover_skills.each { |s| @err.puts("  #{s.fetch(:name)}") }
+        1
+      end
+
+      def usage_error(message)
+        @err.puts(message)
+        print_usage(@err)
+        Rigor::CLI::EXIT_USAGE
+      end
+
+      def print_usage(io)
+        io.puts(USAGE)
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -33,7 +33,8 @@ module Rigor
       "triage" => :run_triage,
       "coverage" => :run_coverage,
       "plugins" => :run_plugins,
-      "playground" => :run_playground
+      "playground" => :run_playground,
+      "skill" => :run_skill
     }.freeze
 
     def self.start(argv = ARGV, out: $stdout, err: $stderr)
@@ -635,6 +636,12 @@ module Rigor
       Rigor::CLI::PlaygroundCommand.new(@argv[1..], @out, @err).run
     end
 
+    def run_skill
+      require_relative "cli/skill_command"
+
+      CLI::SkillCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def write_result(result, format)
       case format
       when "json"
@@ -682,6 +689,7 @@ module Rigor
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
           plugins    Report activation status of every configured plugin
           playground Start the browser playground (requires rigor-playground gem)
+          skill      List or print bundled Agent Skills (rigor-project-init, ...)
           version    Print the Rigor version
           help       Print this help
       HELP

data/lib/rigor/configuration/severity_profile.rb

@@ -39,6 +39,7 @@ module Rigor
       PROFILES = {
         lenient: {
           "call.undefined-method" => :error,
+          "call.unresolved-toplevel" => :off,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :warning,
           "call.possible-nil-receiver" => :warning,
@@ -54,6 +55,7 @@ module Rigor
         }.freeze,
         balanced: {
           "call.undefined-method" => :error,
+          "call.unresolved-toplevel" => :warning,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,
@@ -69,6 +71,7 @@ module Rigor
         }.freeze,
         strict: {
           "call.undefined-method" => :error,
+          "call.unresolved-toplevel" => :error,
           "call.wrong-arity" => :error,
           "call.argument-type-mismatch" => :error,
           "call.possible-nil-receiver" => :error,

data/lib/rigor/scope.rb

@@ -309,6 +309,20 @@ module Rigor
       table[method_name.to_sym] == kind
     end
 
+    # ADR-34 § "Decision" — predicate identifying a toplevel-shaped
+    # scope (no enclosing `class` / `module` body). True at the top
+    # of a file AND inside a top-level `def` body (since toplevel
+    # defs leave `self_type` nil per the existing scope-construction
+    # contract, mirroring how ADR-24's `adoptable_self_call_result?`
+    # also keys on `self_type.nil?` for the same context). Used by
+    # `CheckRules#unresolved_toplevel_diagnostic` to gate the
+    # `call.unresolved-toplevel` rule so it fires only outside
+    # class / module bodies, where Rails-DSL metaprogramming
+    # leniency (ADR-24 WD3 → WD4) does not apply.
+    def toplevel?
+      @self_type.nil?
+    end
+
     def with_discovered_methods(table)
       rebuild(discovered_methods: table)
     end

data/lib/rigor/version.rb

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

data/sig/rigor/scope.rbs

@@ -58,6 +58,7 @@ module Rigor
     def with_discovered_def_nodes: (Hash[String, Hash[Symbol, untyped]] table) -> Scope
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
     def top_level_def_for: (String | Symbol method_name) -> untyped?
+    def toplevel?: () -> bool
     def with_discovered_method_visibilities: (Hash[String, Hash[Symbol, Symbol]] table) -> Scope
     def discovered_method_visibility: (String | Symbol class_name, String | Symbol method_name) -> Symbol?
     def superclass_of: (String | Symbol class_name) -> String?

data/skills/rigor-baseline-reduce/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: rigor-baseline-reduce
+description: |
+  Work a Rigor project's `.rigor-baseline.yml` down rule by rule: prioritise with `rigor triage`, sample call sites, classify each as real bug / stylistic-safe / false positive, then fix, `# rigor:disable`, or open a Rigor issue — and regenerate the baseline. Triggers: "reduce the rigor baseline", "fix some baseline diagnostics", "what rigor issue should I fix next?". NOT for first-time setup (use rigor-project-init) or authoring a plugin (use rigor-plugin-author).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Baseline Reduce
+
+Opportunistic, session-bounded quality improvement for a project
+that already has a `.rigor-baseline.yml`. Each session picks a rule,
+walks its sites, and lands a mix of fixes, intentional suppressions,
+and issue reports — then refreshes the baseline so the gains stick.
+
+This skill is for **users improving their own project**. It uses the
+published `rigor` executable on `PATH` and references only public CLI
+flags and config keys.
+
+## Phase 0 — When to use this skill
+
+Trigger when the user says "reduce the rigor baseline", "fix some
+baseline diagnostics", "what should I fix next in rigor?", or asks to
+work down the diagnostics a previous onboarding parenthesised.
+
+**Precondition: the project is in acknowledge mode.** This skill
+operates on a `.rigor-baseline.yml` that `.rigor.yml` /
+`.rigor.dist.yml` declares via `baseline:`. A strict-mode project
+(`severity_profile: strict`, no baseline) has nothing for this skill
+to reduce — its diagnostics are already all live; fix them as
+ordinary `rigor check` output. If no baseline exists, the user wants
+`rigor-project-init`, not this skill.
+
+Do NOT trigger for:
+
+- **First-time onboarding** — no `.rigor.yml` yet → `rigor-project-init`.
+- **Writing a plugin** for the project's DSL → `rigor-plugin-author`.
+
+## What baseline reduction is
+
+`.rigor-baseline.yml` records `(file, rule, count)` buckets — the
+diagnostics that existed when the project adopted Rigor. They are
+suppressed while their count holds. Reduction means: go through them
+deliberately, decide what each one really is, and shrink the file.
+Three outcomes per site:
+
+- **Real bug** — Rigor caught a genuine defect. Fix the code.
+- **Stylistic / safe** — the static reading is worst-case-sound but
+  the site is fine in practice (an idiom the analyzer's narrowing
+  doesn't follow, a slot the project always initialises). Mark it
+  `# rigor:disable <rule>` with intent.
+- **False positive** — Rigor is wrong; the rule should narrow
+  further. Leave it baselined and open a Rigor issue.
+
+Shrinking the baseline is progress whichever outcome applies — the
+file gets smaller, and "reduce the baseline by N this sprint" is a
+trackable goal.
+
+## Phase outline
+
+| Phase | What | Reference |
+| --- | --- | --- |
+| 1 | Prioritise — `rigor triage --format json` + `rigor baseline dump` pick the rule to work. | [`references/01-classify.md`](references/01-classify.md) |
+| 2 | Per rule: sample 3–5 sites, classify each (real bug / stylistic / FP). | [`references/01-classify.md`](references/01-classify.md) |
+| 3 | Act — fix, `# rigor:disable`, or open a Rigor issue. | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) |
+| 4 | Refresh — `rigor baseline drift`, then `rigor baseline regenerate`. | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) |
+
+Phases 2–4 repeat per rule until a stop condition (below) fires.
+
+## Reading order — modules
+
+| Module | Read | Covers |
+| --- | --- | --- |
+| 1 | [`references/01-classify.md`](references/01-classify.md) | **Phases 1–2.** Priority order from the `rigor triage` hints + ascending bucket count. The sample-and-classify protocol; the three-way real-bug / stylistic / FP triage and how to tell them apart. |
+| 2 | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) | **Phases 3–4.** Acting on each classification — fix patterns, `# rigor:disable` placement (per-line vs per-file), FP escalation as a Rigor GitHub issue. Refreshing the baseline with `drift` + `regenerate`. |
+
+## Stop conditions
+
+End the session — do not grind indefinitely — when any of these hit:
+
+- The user signals halt.
+- The next rule's site count exceeds the session budget (default:
+  ~20 sites). A 200-site rule is systemic; escalate it as a decision
+  (below), do not walk it site by site.
+- A wall-time budget is reached (default: ~60 minutes).
+
+Always finish with Phase 4 (refresh the baseline) before stopping, so
+the landed work is recorded.
+
+## Decision points to escalate to the user
+
+- "This rule has 200 sites across 14 files — it looks systemic. A
+  plugin or an engine fix would clear them in bulk; want me to
+  investigate that instead of walking sites one by one?"
+- "This file's diagnostics would be cleaner under one per-file
+  `# rigor:disable-file <rule>` than 30 per-line comments — switch?"
+- "The diagnostic wording changed between Rigor versions and the
+  baseline no longer matches cleanly — regenerate now?"

data/skills/rigor-baseline-reduce/references/01-classify.md

@@ -0,0 +1,107 @@
+# 01 — Prioritise and classify
+
+Covers **Phase 1** (pick the rule) and **Phase 2** (sample and
+classify its sites).
+
+## Phase 1 — Pick the rule to work
+
+Do not walk the baseline top to bottom. Two commands decide the
+order; run both.
+
+### `rigor triage --format json` — the priority signal
+
+```sh
+rigor triage --format json
+```
+
+`rigor triage` runs the analysis and returns a structured summary —
+a rule `distribution`, file `hotspots`, and a `hints` catalogue. It
+is the deterministic diagnosis layer; use it rather than counting the
+raw `rigor check` stream by hand. The `hints` array is the priority
+signal — each hint has an `id`:
+
+| Hint `id` | What it means for reduction | Priority |
+| --- | --- | --- |
+| `genuine-bugs` | Low-count, scattered rules — the localised bugs Rigor caught. | **Work these first.** Highest value per fix. |
+| `systemic-file-cluster` | One file × one rule, large count. | One fix may clear many — high leverage. Or escalate as systemic. |
+| `activesupport-core-ext`, `gem-without-rbs` | Config gaps, not code bugs. | **Not reduction work** — these are `rigor-project-init` territory (wire the RBS bundle). Flag to the user; do not walk site by site. |
+| `project-monkey-patch` | A DSL / monkey-patch Rigor can't see. | Escalate — a `pre_eval:` entry or a plugin clears the whole cluster. |
+| `activerecord-relation-misinference` | Likely an engine gap. | Treat sites as candidate false positives (Phase 2). |
+
+### `rigor baseline dump --format json` — the bucket list
+
+```sh
+rigor baseline dump --format json
+```
+
+This is the authoritative list of `(file, rule, count)` buckets in
+`.rigor-baseline.yml`. Within the priority tier the triage hints set,
+**sort rules by ascending total count** — the smallest rules first.
+A rule with 3 sites is either a quick win or a contained pattern;
+either way it is finishable in one session, and finishing a rule is
+more motivating than half-clearing a 200-site one.
+
+So the working order is: rules flagged `genuine-bugs` first, then the
+rest by ascending count, with config-gap hints handed back to the
+user instead of walked.
+
+## Phase 2 — Sample and classify
+
+Pick the chosen rule. Surface its actual diagnostics — run
+`rigor check` scoped to the affected files so the user sees real
+messages, not baseline rows:
+
+```sh
+rigor check app/models/account.rb app/services/feed_service.rb
+```
+
+(The baseline still suppresses these in a full run; naming the files
+and reading the stream shows them. `--no-baseline` also works if you
+want the whole project's live stream.)
+
+From the rule's sites, **sample 3–5 distinct ones** — different
+files, different shapes, not five copies of the same line. For each
+sampled site, read the code and classify it. Ask the user to confirm
+when the call is not clear-cut.
+
+### The three classifications
+
+**Real bug** — Rigor found a genuine defect.
+
+- A `possible-nil-receiver` where the value genuinely can be `nil` on
+  some path and the code would crash.
+- An `undefined-method` that is a real typo or a removed method.
+- An argument-type mismatch that would raise or misbehave.
+- Tell: trace the value's origin and you find a path that actually
+  produces the bad case.
+
+**Stylistic / safe** — the static reading is worst-case-sound, but
+the site is fine in practice.
+
+- `T | nil` where the slot is always initialised before this point
+  by code Rigor's narrowing doesn't follow (a memoised getter, a
+  framework lifecycle guarantee).
+- A dynamic `send` over a known-finite, known-safe tag set.
+- An idiom repeated across dozens of files — at that scale the
+  pattern *is* the project's style.
+- Tell: you can articulate *why* the bad case never reaches this
+  line, and that reason is a real invariant, not a hope.
+
+**False positive** — Rigor is simply wrong; a correct analyzer would
+not flag this site.
+
+- The narrowing should have followed an `&.` chain or an early
+  `return`/`raise` guard and didn't.
+- The receiver type is misinferred (e.g. an ActiveRecord relation
+  typed as `Array`).
+- Tell: the code is correct *and* a reasonable type checker should
+  see that it is correct — the gap is in Rigor, not the code.
+
+The distinction between "stylistic / safe" and "false positive"
+matters: stylistic-safe sites get a `# rigor:disable` (the code stays
+as is, the suppression is intentional); false positives get a Rigor
+issue (the analyzer should improve). Both stay out of the count, but
+only one of them is feedback Rigor's maintainers can act on.
+
+Carry the per-site classifications into Phase 3
+([`02-fix-or-suppress.md`](02-fix-or-suppress.md)).