rigortype 0.1.13 → 0.1.15

data/lib/rigor/triage/catalogue.rb

@@ -22,6 +22,7 @@ module Rigor
       module_function
 
       UNDEFINED_METHOD_RULE = "call.undefined-method"
+      UNRESOLVED_TOPLEVEL_RULE = "call.unresolved-toplevel"
 
       # `undefined method `foo' for <receiver>`
       UNDEF_METHOD = /\Aundefined method [`'"]([^`'"]+)['"`] for (.+)\z/
@@ -104,9 +105,19 @@ module Rigor
       # monkey-patch): a known AR method on `Array[...]` deserves
       # the precise relation-misinference hint, not the generic
       # "project core-ext" guess H2 would otherwise claim it for.
+      #
+      # H2K (known project patch) runs before the generic H2: the
+      # engine has already proved the defining site via the
+      # `project_definition_site` field (ADR-17), so those
+      # diagnostics get the high-confidence file-naming hint rather
+      # than the spread-based guess. H7 (unresolved toplevel) runs
+      # before the systemic / genuine-bug catch-alls so toplevel
+      # resolution misses route to `pre_eval:` (ADR-34) instead of
+      # reading as scattered bugs.
       def recognisers
         %i[h1_activesupport h4_ar_relation h3_gem_without_rbs
-           h2_monkey_patch h5_systemic_cluster h6_genuine_bugs]
+           h2k_known_project_patch h2_monkey_patch h7_unresolved_toplevel
+           h5_systemic_cluster h6_genuine_bugs]
       end
 
       # --- H1 — likely ActiveSupport core_ext --------------------
@@ -127,6 +138,31 @@ module Rigor
         ), matched]
       end
 
+      # --- H2K — known project monkey-patch (engine-proven) ------
+      # ADR-17 / WD3 slice 4: the `call.undefined-method` rule sets
+      # `project_definition_site` when the project itself defines the
+      # called method on the receiver class somewhere in the file set
+      # (a reopened core/stdlib/gem class the dispatcher does not
+      # apply cross-file). That is direct evidence — not a spread
+      # heuristic — so this recogniser is `:likely` and names the
+      # defining files outright. It runs before the generic H2.
+      def h2k_known_project_patch(pool)
+        matched = pool.select(&:project_definition_site)
+        return nil if matched.empty?
+
+        files = matched.map { |d| d.project_definition_site.sub(/:\d+\z/, "") }
+                       .uniq.sort
+        [Hint.new(
+          id: "project-monkey-patch-known", confidence: :likely,
+          diagnostic_count: matched.size,
+          summary: "#{matched.size} undefined-method site(s) resolve to project " \
+                   "definitions in #{files.first(3).join(', ')} — reopened core/" \
+                   "stdlib/gem classes Rigor does not apply cross-file",
+          action: "List #{files.size == 1 ? 'this file' : 'these files'} in " \
+                  "`.rigor.yml`'s `pre_eval:` (ADR-17): #{files.join(', ')}"
+        ), matched]
+      end
+
       # --- H2 — likely a project monkey-patch / refinement -------
       def h2_monkey_patch(pool)
         groups = undefined_method_groups(pool).select do |(_method, _recv), diags|
@@ -179,6 +215,30 @@ module Rigor
         ), matched]
       end
 
+      # --- H7 — unresolved toplevel implicit-self calls ----------
+      # ADR-34: `call.unresolved-toplevel` fires on a toplevel
+      # implicit-self call (no receiver, outside any def / class /
+      # module) that resolves against no visible contributor. The
+      # canonical opt-out is `pre_eval:` — the file is usually a
+      # script relying on methods defined by a monkey-patch or a
+      # required helper Rigor did not walk. Grouped, not per-site,
+      # so the report names the cluster once.
+      def h7_unresolved_toplevel(pool)
+        matched = pool.select { |d| rule_of(d) == UNRESOLVED_TOPLEVEL_RULE }
+        return nil if matched.empty?
+
+        files = matched.map(&:path).uniq.sort
+        [Hint.new(
+          id: "unresolved-toplevel", confidence: :possible,
+          diagnostic_count: matched.size,
+          summary: "#{matched.size} toplevel call(s) resolve to nothing visible " \
+                   "across #{files.size} file(s) (#{top_methods(matched, parser: :toplevel)})",
+          action: "If a monkey-patch or required helper defines these, list its " \
+                  "file in `.rigor.yml`'s `pre_eval:` (ADR-17); otherwise they may " \
+                  "be genuine typos or missing requires."
+        ), matched]
+      end
+
       # --- H5 — systemic single-file cluster ---------------------
       def h5_systemic_cluster(pool)
         bucket = pool.group_by { |d| [d.path, rule_of(d)] }
@@ -282,10 +342,16 @@ module Rigor
         groups.keys.first(3).map { |method, recv| "`#{method}` on #{recv}" }.join(", ")
       end
 
-      def top_methods(diagnostics, limit: 5)
-        diagnostics.filter_map { |d| parse_undefined_method(d)&.fetch(:method) }
-                   .tally.sort_by { |method, count| [-count, method] }
-                         .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
+      # `parser: :undefined_method` (default) reads the method from
+      # the parsed `undefined-method` shape; `parser: :toplevel`
+      # reads the structured `method_name` field directly (the
+      # `unresolved-toplevel` rule carries no receiver to parse).
+      def top_methods(diagnostics, limit: 5, parser: :undefined_method)
+        names = diagnostics.filter_map do |d|
+          parser == :toplevel ? d.method_name : parse_undefined_method(d)&.fetch(:method)
+        end
+        names.tally.sort_by { |method, count| [-count, method] }
+                   .first(limit).map { |method, count| "#{method}×#{count}" }.join(" ")
       end
 
       def rule_of(diag)

data/lib/rigor/version.rb

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

data/sig/rigor/environment.rbs

@@ -51,6 +51,7 @@ module Rigor
       def self.reset_default!: () -> void
       def self.build_env_for: (libraries: Array[String], signature_paths: Array[String | _ToPath]) -> untyped
       def self.vendored_gem_sig_paths: () -> Array[Pathname]
+      def self.vendored_gem_names: () -> Array[String]
 
       def initialize: (?libraries: Array[String], ?signature_paths: Array[String | _ToPath], ?cache_store: untyped?) -> void
       def class_known?: (String | Symbol name) -> bool

data/sig/rigor/scope.rbs

@@ -15,6 +15,7 @@ module Rigor
     attr_reader in_source_constants: Hash[String, Type::t]
     attr_reader discovered_methods: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_def_nodes: Hash[String, Hash[Symbol, untyped]]
+    attr_reader discovered_def_sources: Hash[String, Hash[Symbol, String]]
     attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_superclasses: Hash[String, String]
     attr_reader discovered_includes: Hash[String, Array[String]]
@@ -56,7 +57,9 @@ module Rigor
     def with_discovered_methods: (Hash[String, Hash[Symbol, Symbol]] table) -> Scope
     def discovered_method?: (String | Symbol class_name, String | Symbol method_name, Symbol kind) -> bool
     def with_discovered_def_nodes: (Hash[String, Hash[Symbol, untyped]] table) -> Scope
+    def with_discovered_def_sources: (Hash[String, Hash[Symbol, String]] table) -> Scope
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
+    def user_def_site_for: (String | Symbol class_name, String | Symbol method_name) -> String?
     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

data/skills/rigor-plugin-author/SKILL.md

@@ -43,6 +43,26 @@ release as potentially contract-changing:
 Tell the user this up front. A plugin written today is a preview
 artefact, valuable but not yet on a stable foundation.
 
+## Read a real plugin — `rigor plugin`
+
+You do not have to learn the `Rigor::Plugin::Base` surface from this
+prose alone. Because Rigor is installed on disk (`mise` / `gem
+install`), every plugin bundled in the toolchain is readable source.
+Use it as a worked-example library throughout this skill:
+
+```sh
+rigor plugin list                              # all bundled + example plugins, with paths
+rigor plugin print rigor-activesupport-core-ext  # a plugin's main source, inline
+rigor plugin path  rigor-units                 # the dir, to browse with your file tool
+rigor plugin root                              # gem root + public API (lib/rigor/plugin.rb)
+```
+
+`rigor plugin` (singular) browses the toolchain's plugins; `rigor
+plugins` (plural) reports your own `.rigor.yml` activation — different
+commands. When a step below is thinner than you need, read a shipped
+plugin that does the same thing. (Paths are local to where `rigor`
+runs — see the command's own note about containers.)
+
 ## Phase 0 — Standalone gem or project-private?
 
 Decide where the plugin lives before scaffolding anything.

data/skills/rigor-plugin-author/references/01-plan-and-scaffold.md

@@ -63,9 +63,57 @@ on it directly.
 ## Project-private layout
 
 A project-private plugin lives inside the application repo and is
-never published. Two ways to make `require "rigor-<id>"` succeed:
+never published. Rigor activates it by `require "rigor-<id>"`, so the
+plugin's `lib/` must be on the **load path of the Ruby process that
+runs `rigor`**. *Which* mechanism puts it there depends entirely on
+**how `rigor` is installed** — and getting this wrong is the most
+common project-private activation failure (`could not load plugin gem
+"rigor-<id>"`).
+
+> **First answer this: how does `rigor` run?** Per the
+> `rigor-project-init` workflow and the manual's installation chapter,
+> the recommended install is **standalone** (`mise` / `gem install`) —
+> and crucially **`rigortype` is NOT in your app's `Gemfile`**. A
+> standalone `rigor` does **not** load your project's bundle, so a
+> `path:`-gem in the `Gemfile` + `bundle install` puts the plugin on
+> the *bundle's* load path, which the standalone `rigor` never reads.
+> The path-gem route below works **only** if you deliberately run
+> `rigor` from a bundle that includes `rigortype` (an advanced / CI
+> setup). For the default standalone install, use `RUBYLIB`.
+
+### Recommended for a standalone (mise / gem install) `rigor` — `RUBYLIB`
+
+Drop the plugin under the app and put its `lib/` (or its root, if the
+entry file sits at the top) on `RUBYLIB` as an **absolute path**:
 
-### Recommended — a path gem
+```text
+your-app/rigor-ext/rigor-myapp.rb     # requires the plugin class
+```
+
+```sh
+# Absolute path — a relative RUBYLIB is resolved against the process
+# CWD and frequently does not match; use $(pwd).
+RUBYLIB="$(pwd)/rigor-ext" rigor check
+```
+
+Ruby adds `RUBYLIB` entries to `$LOAD_PATH` at startup, so the
+standalone `rigor` binary finds `require "rigor-myapp"`. Set it on
+every invocation (CI included); a `Rakefile` task or a shell alias
+keeps it ergonomic.
+
+> **Pitfall — do not wrap this in `bundle exec`.** `bundle exec`
+> rebuilds `$LOAD_PATH` from the bundle and drops `RUBYLIB` entries, so
+> `RUBYLIB=… bundle exec rigor` fails to find the plugin. If for some
+> reason you must run `rigor` through `bundle exec` (or any wrapper
+> that resets the load path), pass the directory as a Ruby flag
+> instead — `RUBYOPT="-I$(pwd)/rigor-ext" rigor check` — which Bundler
+> preserves.
+
+Verify activation with `rigor plugins` (plural): the entry should show
+`[OK ]` with `load-error: 0`. If it shows `[ERR] could not load plugin
+gem`, the load path is the problem, not the plugin code.
+
+### Advanced (only when `rigor` runs from a bundle) — a path gem
 
 Keep the plugin in a subdirectory with its own gemspec, and reference
 it from the app's `Gemfile` by path:
@@ -87,25 +135,15 @@ gem "rigortype", "~> 0.1.0"
 gem "rigor-myapp", path: "rigor-plugin"
 ```
 
-`bundle install` then puts `rigor-myapp` on the load path, so Rigor's
-`require "rigor-myapp"` resolves. This keeps the plugin versioned,
-testable, and trivially promotable to a real gem later.
-
-### Simplest — a bare file on the load path
-
-If you do not want a gemspec at all, drop `rigor-myapp.rb` somewhere
-and run `rigor` with that directory on `RUBYLIB`:
-
-```text
-your-app/rigor-ext/rigor-myapp.rb     # requires the plugin class
-```
-
-```sh
-RUBYLIB=rigor-ext rigor check
-```
-
-Workable, but the `RUBYLIB` has to be set on every invocation (CI
-included). Prefer the path gem unless the plugin is a throwaway.
+`bundle install` puts `rigor-myapp` on the bundle's load path — but
+this only helps if you then **run `rigor` through that bundle**
+(`bundle exec rigor`, or a bundle whose `bin/` is on `PATH`). It also
+means `rigortype` *is* in this `Gemfile`, which the `rigor-project-init`
+workflow recommends against for the analyzer-as-tool install. So treat
+this route as the **CI / isolated-bundle** option, not the default. It
+keeps the plugin versioned, testable, and trivially promotable to a
+real gem later — choose it when your `rigor` already runs from a
+bundle; otherwise use `RUBYLIB` above.
 
 ## The plugin class skeleton
 

data/skills/rigor-plugin-author/references/02-walker-and-types.md

@@ -89,6 +89,21 @@ type.
 
 ## Optional — contribute a return type with `flow_contribution_for`
 
+> **Critical — this hook does NOT make a method "defined", so it does
+> NOT suppress `call.undefined-method`.** Method *existence* and call
+> *type* are two independent checks. `flow_contribution_for` sharpens
+> the type of a call the analyzer has **already resolved to a real
+> method** (turning a `Dynamic` return into something precise). It is
+> never consulted for a receiver/method the analyzer cannot find — that
+> fires `call.undefined-method` first, and a flow contribution does
+> nothing to silence it. **If your goal is to kill a
+> `call.undefined-method` cluster on a DSL-generated method (the common
+> reason `rigor-project-init` hands off to this skill), the fix is to
+> make the method *exist* in Rigor's view — ship RBS declaring it (see
+> "Shipping RBS for the DSL" below), not a flow contribution.** Reach
+> for `flow_contribution_for` only when the call already resolves and
+> you want a *better return type*.
+
 A plugin can do more than emit diagnostics: it can *supply* the
 inferred return type for a call site the core analyzer would
 otherwise type as `Dynamic`. Implement `flow_contribution_for`:
@@ -128,23 +143,57 @@ most likely to shift before v0.2.0. Implement it only if the plugin
 genuinely needs to sharpen call-site types; a diagnostics-only
 plugin can skip it entirely.
 
-## Shipping RBS for the DSL
+## Shipping RBS for the DSL — the way to suppress `call.undefined-method`
 
 If the DSL introduces methods or classes that Rigor cannot see (a
-`Money` class defined by metaprogramming, methods mixed into
-`Numeric`), give Rigor RBS for them so *core* inference — not just
-your plugin — understands them. Ship `sig/*.rbs` with the plugin (or
-in the consuming project) and point `.rigor.yml` at it:
-
-```yaml
-signature_paths:
-  - sig
-```
-
-RBS covers what the *shape* of the DSL is; the plugin walker covers
-the *dynamic* parts RBS cannot express (a value computed from a
-literal argument, a dimensional rule). They compose — many plugins
-ship both.
+`Money` class defined by metaprogramming, `Setting.<name>` accessors a
+`class_eval` heredoc generates, methods mixed into `Numeric`), give
+Rigor RBS declaring them so *core* inference — not just your plugin —
+treats them as **defined**. This is what removes the
+`call.undefined-method` diagnostics on those methods; nothing else
+(not `diagnostics_for_file`, not `flow_contribution_for`) makes a
+method exist in Rigor's view.
+
+Two ways to wire the RBS, depending on how the plugin is packaged:
+
+1. **A packaged gem plugin** — declare `signature_paths:` in the
+   **plugin manifest** (resolved relative to the plugin's gem root, per
+   ADR-25), so activating the plugin contributes its RBS with no
+   user-side wiring. This is how the bundled RBS-bundle plugins work —
+   read one as a worked example:
+
+   ```sh
+   rigor plugin print rigor-activesupport-core-ext   # see manifest + sig/ layout
+   rigor plugin path  rigor-activesupport-core-ext   # then browse its sig/ dir
+   ```
+
+2. **A project-private plugin** — the manifest field still works, but
+   the simplest reliable route is to ship the `.rbs` under the plugin's
+   own `sig/` and add **that path** to the *consuming project's*
+   `.rigor.yml`:
+
+   ```yaml
+   signature_paths:
+     - rigor-ext/sig    # the project-private plugin's RBS directory
+   ```
+
+If the DSL's method names are generated from a data file (Redmine's
+`Setting` names come from `config/settings.yml`), generate the `.rbs`
+from that same source — a small script that reads the data file and
+emits one declaration per name keeps the RBS in sync with the DSL.
+
+RBS covers what the *shape* of the DSL is (which methods exist, their
+signatures); the plugin walker covers the *dynamic* parts RBS cannot
+express (a value computed from a literal argument, a dimensional rule).
+They compose — many plugins ship both.
+
+> **Browse a real plugin instead of guessing the API.** Because Rigor
+> is installed on disk (`mise` / `gem install`), every bundled plugin's
+> source is readable as a worked example. `rigor plugin list` shows
+> them all with absolute paths; `rigor plugin print <name>` inlines a
+> plugin's main source; `rigor plugin root` points at the engine source
+> and the public `Rigor::Plugin::Base` API. When the prose here is
+> thinner than you need, read a shipped plugin that does the same thing.
 
 ## Output of this module
 

data/skills/rigor-project-init/SKILL.md

@@ -92,8 +92,10 @@ Below that, either mode is reasonable — ask.
 | 4 | Write `.rigor.dist.yml` — severity profile follows the mode. Verify activation with `rigor plugins`. | [`references/02-configure.md`](references/02-configure.md) |
 | 5 | Generate initial RBS sigs; uplift attr_reader precision with `--params=observed`. | [`references/04-sig-uplift.md`](references/04-sig-uplift.md) |
 | 6 | Run `rigor triage --format json` to diagnose the diagnostic stream. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) |
+| 6a | **Pre-baseline cleanup** — apply quick fixes that triage diagnosed (`pre_eval:` for monkey-patch hints, `rbs collection install` if still needed). Re-run triage; repeat until the count is stable. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) § "Phase 6a" |
 | 7 | Acknowledge mode only — generate the baseline and wire `baseline:`. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) |
-| 8 | Surface likely real bugs; offer the two escalation paths. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) |
+| 8 | Surface likely real bugs; distinguish sig quality FPs from real bugs; offer escalation paths. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) |
+| 9 | Confirm the generated files with the user — what each is, and whether to commit it. | (this file — § "Final step") |
 
 Load each reference when you reach its phase. Phases run in order;
 the only branch is Phase 7 (acknowledge mode runs it, strict mode
@@ -107,7 +109,7 @@ committed `sig/` directory.
 | 1 | [`references/01-detect.md`](references/01-detect.md) | **Phases 1 + 3.** Gemfile / Gemfile.lock walk → framework family. The plugin-recommendation table (Rails / dry-rb / Sinatra / RSpec / plain Ruby). RBS-collection presence check. |
 | 2 | [`references/02-configure.md`](references/02-configure.md) | **Phase 4.** Severity-profile choice tied to the mode. The `.rigor.dist.yml` template and every key it uses. The `.rigor.dist.yml` vs `.rigor.yml` convention. |
 | 3 | [`references/04-sig-uplift.md`](references/04-sig-uplift.md) | **Phase 5.** `rigor sig-gen --write` baseline. `rigor sig-gen --params=observed --write` attr_reader precision uplift. Handling residual `untyped` methods. Committing `sig/`. |
-| 4 | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) | **Phases 6–8.** `rigor triage` as the diagnosis layer. `rigor baseline generate` + wiring `baseline:`. Surfacing likely real bugs. The two escalation paths — write a project plugin, or open a Rigor issue. |
+| 4 | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) | **Phases 6–8.** `rigor triage` as the diagnosis layer. Phase 6a pre-baseline cleanup loop (`pre_eval:` for monkey-patch hints, `rbs collection install`). `rigor baseline generate` + wiring `baseline:`. Surfacing likely real bugs; sig quality FP recognition (Struct `call.wrong-arity`, `-> bot` return-type-mismatch, regex-capture `$1` FPs). The two escalation paths — write a project plugin, or open a Rigor issue. |
 
 ## Escalation paths (Phase 7 preview)
 
@@ -115,10 +117,23 @@ Some diagnostic clusters are neither a quick fix nor honest baseline
 material. Two of them have a dedicated answer this skill hands off to:
 
 - **Application-specific metaprogramming** — a project DSL,
-  `define_method` factory, or in-house macro that Rigor cannot follow
-  produces a cluster of `call.undefined-method`. The durable fix is a
-  **project-private Rigor plugin** that teaches Rigor the DSL. Hand
-  off to the `rigor-plugin-author` skill.
+  `define_method` factory, `method_missing` accessor, or `class_eval`
+  heredoc generator that Rigor cannot follow produces a cluster of
+  `call.undefined-method` (or `unresolved-toplevel`). **First decide
+  whether `pre_eval:` can fix it** — it resolves only methods written
+  as *literal* `def` / `def self.` in a project file. When the methods
+  are **generated dynamically** (computed `define_method` names,
+  `method_missing`, a `class_eval <<~RUBY … def #{name} … RUBY`
+  template), `pre_eval:` walks the file and finds no literal method to
+  register, so the cluster *survives*. That residue is the signal that
+  the durable fix is a **project-private Rigor plugin** which teaches
+  Rigor the DSL's shape. **This is the recommended next step**, and
+  Rigor does **not** ship per-application plugins for it — a Redmine
+  app's `Setting.define_setting` accessors, an in-house
+  `acts_as_*`, etc. are the *project's* plugin to own (ADR-16 §
+  Audience: application-specific homegrown DSLs are out of scope for
+  the bundled substrate). Surface it and offer to launch the
+  **`rigor-plugin-author`** skill (see § "Next step" below).
 - **An external gem Rigor does not understand** — a dependency ships
   no RBS and Rigor has no built-in coverage for it. Try
   `rbs collection install` first; if that gem genuinely needs Rigor
@@ -126,4 +141,54 @@ material. Two of them have a dedicated answer this skill hands off to:
   <https://github.com/rigortype/rigor/issues>.
 
 Neither is a Phase 7 obligation — they are options to *offer* the
-user when the triage report points at one of these causes.
+user when the triage report points at one of these causes. The
+project-DSL handoff is detailed in
+[`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md)
+§ "Escalation path A".
+
+## Next step — hand off to plugin authoring when a project DSL remains
+
+Onboarding's job ends at a committed config + (acknowledge mode) a
+baseline. But if Phase 6a/8 found a **dynamically-generated project
+DSL** that `pre_eval:` could not resolve (a `define_method` factory,
+`method_missing`, or a `class_eval` heredoc generator), the onboarding
+is not *complete* until the user knows the durable fix — a
+**project-owned Rigor plugin**, which Rigor does not bundle per app.
+
+Before the final file-confirmation step, when such a cluster exists:
+name it and its generator, say plainly that the fix is a project plugin
+(not a baseline entry), and **offer to launch the `rigor-plugin-author`
+skill** — on the user's confirmation, invoke it (Skill tool). The full
+detection-and-handoff recipe is
+[`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md)
+§ "Escalation path A". The offer is not automatic — the user may
+baseline the cluster now and author the plugin later — but never leave
+a generated-DSL cluster in the baseline without naming its real fix.
+
+## Final step — confirm the generated files with the user
+
+Onboarding scatters new files across the project root. Before
+finishing, present the user with a short message that names **each
+file the workflow produced**, says what it is, and recommends
+whether to commit it — so the team shares one consistent setup
+rather than each developer reinventing it. Do not silently leave the
+files for the user to discover.
+
+Run `git status --short` first; only describe files that actually
+exist (e.g. `sig/` exists only if Phase 5 ran; `.rigor-baseline.yml`
+only in acknowledge mode). For each, give the commit recommendation:
+
+| File | What it is | Commit? |
+| --- | --- | --- |
+| `.rigor.dist.yml` | The shared project config (Phase 4) — `target_ruby`, `paths:`, `plugins:`, `severity_profile:`, and the `baseline:` pointer. The single source of truth every contributor's `rigor check` reads. | **Yes** — it is the shared config; sharing it is the whole point. |
+| `.rigor-baseline.yml` | Acknowledge mode only (Phase 7) — the snapshot of today's known diagnostics. Doubles as a record of project state; without it each developer's baseline diverges and the regression guard means different things per machine. | **Yes** — commit it; it documents project state and pins the regression envelope. |
+| `sig/` | RBS skeletons from `rigor sig-gen` (Phase 5), if that phase ran. A first-class project artefact — it sharpens inference for everyone. | **Yes** — commit it (see [`references/04-sig-uplift.md`](references/04-sig-uplift.md) § "Commit the sig/ directory"). |
+| `.rigor/` (contains `cache/`) | The per-file analysis cache `rigor check` writes to speed up re-runs. Regenerable and machine-local. | **No** — add `.rigor/` to `.gitignore`. |
+| `.rigor.yml` | Optional per-developer local override (not written by this skill). Takes precedence over `.rigor.dist.yml`; used to opt out locally (e.g. run without the baseline). | **No** — gitignore it if a developer creates one. |
+
+Recommend the two concrete actions and **ask before doing them**
+(both touch the user's repo): (1) add `.rigor/` — and `.rigor.yml`
+if present — to `.gitignore`; (2) commit `.rigor.dist.yml`,
+`.rigor-baseline.yml`, and `sig/` as the shared Rigor setup. Per the
+git-safety default, do not commit on the user's behalf until they
+confirm.

data/skills/rigor-project-init/references/01-detect.md

@@ -35,13 +35,51 @@ Also note per-gem markers that have their own plugin: `devise`,
     `rbs_collection.auto_detect: true` (the default).
   - **Lockfile present, `.gem_rbs_collection/` absent** → the lockfile
     was generated but the gems were never downloaded. Rigor loads the
-    lockfile but finds no RBS files. Note this for Phase 6: if triage
-    reports `gem-without-rbs` hints for gems that appear in
-    `rbs_collection.yaml`, run `rbs collection install` first and
-    re-run triage.
+    lockfile but finds no RBS files. **Act now — see below.**
   - **Both absent** → note it; Phase 6's triage may recommend
     `rbs collection install` if `gem-without-rbs` hints appear.
 
+### RBS collection — install if absent
+
+When `rbs_collection.lock.yaml` is present **and** `.gem_rbs_collection/`
+is absent, the collection was configured (e.g. by Steep or `rbs_rails`)
+but never installed. Installing it now — before writing the config or
+running triage — gives Rigor community RBS for dozens of gems and avoids
+a triage → config-fix → re-triage cycle.
+
+Offer to run:
+
+```sh
+bundle exec rbs collection install
+```
+
+Use `bundle exec` when `rbs` appears in `Gemfile` or `Gemfile.lock`
+(the common case — Steep / rbs_rails workflows put it there). If `rbs`
+is not in the Gemfile, use the bare `rbs collection install` instead.
+
+Ask the user for permission before running, since this installs files
+into `.gem_rbs_collection/` (a generated directory that belongs in
+`.gitignore`). Only proceed with their confirmation.
+
+After installation, verify with:
+
+```sh
+ls .gem_rbs_collection/
+```
+
+The directory should contain RBS gem subdirectories. Continue to
+Phase 2 — the collection will be auto-detected by Rigor at analysis
+time.
+
+**Note: RBS collision after install.** Some gems (e.g. `cgi`, `logger`,
+`base64`) were extracted from Ruby's stdlib into standalone gems from
+Ruby 3.3 onwards. When these appear in both `.gem_rbs_collection/` and
+Rigor's bundled stdlib, `rigor triage` may print a
+`RBS::DuplicatedDeclarationError`. If this happens, note the error and
+continue — plugin-based diagnostics are unaffected. File a Rigor issue
+at <https://github.com/rigortype/rigor/issues> so the engine can
+deduplicate stdlib gems from the collection automatically.
+
 ### Path scope
 
 Note the conventional source roots so Phase 4 can set `paths:`:

data/skills/rigor-project-init/references/02-configure.md

@@ -18,6 +18,23 @@ config as `.rigor.dist.yml` lets a contributor opt out locally (for
 example, run without the baseline) without touching the committed
 file.
 
+## Selecting `target_ruby`
+
+Read the project's declared Ruby version from `.ruby-version`, the
+`Gemfile` `ruby "…"` line, or `.tool-versions`. Use the **minimum**
+version of the declared range (e.g. `>= 3.2.0, < 3.5.0` → `3.2`).
+
+Then apply this decision table — **do not ask the user**; act
+automatically and emit the message described:
+
+| Declared minimum | `target_ruby` to write | Action |
+| --- | --- | --- |
+| 4.x | `"4.0"` (or exact patch) | Write as-is. |
+| 3.3 – 3.x | `"3.3"` (or exact minor) | Write as-is. |
+| 3.0 – 3.2 | `"3.3"` | Write `"3.3"` automatically. Emit: *"Project targets Ruby X.Y, but Prism (the parser bundled with rigortype) supports Ruby 3.3 as its minimum. Setting `target_ruby: \"3.3\"` — syntax parsing is compatible across 3.0–3.3, but RBS type definitions in `.gem_rbs_collection/` or community libraries may be authored for 3.3+ and could produce type-level false positives on APIs that changed between 3.0 and 3.3."* |
+| 2.x | — | **Stop.** Emit: *"Project targets Ruby 2.x. Rigor's bundled Prism parser does not support Ruby 2.x syntax (removed keyword argument syntax, pattern matching differences). Rigor cannot reliably analyse this project. Consider upgrading the project to Ruby 3.3+ before onboarding Rigor."* Do not write a config; do not continue the skill. |
+| Unknown / not declared | `"4.0"` (Rigor's default) | Write as-is; note that the default was used. |
+
 ## Severity profile — follows the mode
 
 The `severity_profile:` key re-stamps every rule's severity. Set it