rigortype 0.1.14 → 0.1.15

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/03-baseline-and-bugs.md

@@ -50,7 +50,9 @@ Use the three sections like this:
 | --- | --- | --- |
 | `activesupport-core-ext` | ActiveSupport core-class monkey-patches not loaded. | Go back to Phase 3/4: add `rigor-activesupport-core-ext` to `plugins:` (it is an RBS-bundle plugin), re-run triage. This is a config gap, not a bug. |
 | `gem-without-rbs` | A dependency ships no RBS. | If `rbs_collection.lock.yaml` was present and Phase 1 installed the collection, re-run `rigor triage` — the hint may shrink or disappear. Otherwise: Phase 8 escalation — `bundle exec rbs collection install`, or `dependencies.source_inference:`, or open a Rigor issue. |
-| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see. | Phase 7 escalation — register the defining file via `pre_eval:`, or (if it is a DSL) write a project plugin. |
+| `project-monkey-patch-known` | **High confidence.** The engine proved the called method *is* defined by a project file (a reopened core/stdlib/gem class) but is not applied cross-file. The hint **names the defining file(s)**. | Phase 7 escalation — copy the named file(s) straight into `pre_eval:`. No detective work needed; the diagnostic already found the source. |
+| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see, inferred from the *spread* of the same method across ≥3 files (no proven def site). | Phase 7 escalation — find the defining file (grep for `def <method>` / `class <Receiver>`), register it via `pre_eval:`, or (if it is a DSL) write a project plugin. |
+| `unresolved-toplevel` | Toplevel calls (outside any `def`/`class`/`module`) that resolve to nothing visible — usually a script relying on a monkey-patch or a `require`d helper Rigor did not walk (ADR-34). | Phase 7 escalation — if a project file defines these (toplevel `def`, or a patch on `Object`/`Kernel`), list it in `pre_eval:`. If nothing defines them, treat as genuine typos / missing requires (Phase 8). |
 | `activerecord-relation-misinference` | An ActiveRecord relation inferred as `Array`. | Ensure `rigor-activerecord` is enabled (Phase 3). If it persists, it is an engine gap — open a Rigor issue. |
 | `systemic-file-cluster` | One file × one rule, large count. | Acknowledge mode: a clean baseline bucket. Strict mode: a single fix may clear many — review that file first. |
 | `genuine-bugs` | Low-count rules scattered across files. | **Phase 7** — these are the localised bugs Rigor caught. Review first, in both modes. Note: the hint groups all low-count rules regardless of severity — filter for `error` severity when prioritising actionable items. |
@@ -60,6 +62,80 @@ If triage flags `activesupport-core-ext` (or any config gap),
 baseline and the real-bug review should both run against the
 post-config diagnostic set, not the inflated one.
 
+## Phase 6a — Pre-baseline cleanup
+
+Before generating the baseline, **apply every quick fix that triage
+has already diagnosed**. A smaller baseline is a better baseline: each
+bucket it omits is a regression that will surface the moment it
+appears, rather than hiding behind a ceiling that the monkey-patch
+noise inflated.
+
+Quick fixes that belong here (apply now, not as post-baseline
+escalation):
+
+### `project-monkey-patch` / `project-monkey-patch-known` → `pre_eval:`
+
+When triage reports either hint, act before Phase 7:
+
+1. **`project-monkey-patch-known`** — the hint's action line **names
+   the defining file(s)**. Copy them straight into `pre_eval:` in
+   `.rigor.dist.yml`:
+
+   ```yaml
+   pre_eval:
+     - lib/core_ext/user_extensions.rb   # exact path(s) named by the hint
+   ```
+
+2. **`project-monkey-patch`** (spread-based, no proven def site) —
+   find the defining file manually:
+
+   ```sh
+   # Replace `current` / `User` with the method and receiver named in the hint
+   grep -rn "def self\.current\|cattr_accessor.*current" app/ lib/
+   grep -rn "def deliver_\|def find_by_" app/ lib/
+   ```
+
+   Then add the file(s) to `pre_eval:`.
+
+After adding `pre_eval:` entries, **re-run `rigor triage`** and note
+the new total. If the count dropped by more than ~50 diagnostics,
+the reduction is significant enough to justify this round; proceed
+with the new, smaller count.
+
+Repeat the loop (find → `pre_eval:` → re-triage) until the hint
+disappears or the remaining count is stable. Then move to Phase 7.
+
+> **If a cluster does NOT drop after you add its file to `pre_eval:`**,
+> the methods are almost certainly **generated dynamically**
+> (`define_method` with a computed name, `method_missing`, or a
+> `class_eval` heredoc) — the pre-eval walker found no literal `def` to
+> register. That is not a `pre_eval:` failure to retry; it is the signal
+> that the durable fix is a **project-owned plugin**. Leave the file in
+> `pre_eval:` only if it also defines literal methods; otherwise remove
+> it and carry the cluster to Phase 8 § "Escalation path A", which
+> hands off to the `rigor-plugin-author` skill.
+
+> **Why `pre_eval:` reduces the count.** `pre_eval:` files are walked
+> before per-file inference. Methods defined in them — including those
+> added to existing classes via `class Foo; def bar; end; end` — become
+> visible to every subsequent file analysis. The monkey-patched methods
+> are no longer unknown, so `call.undefined-method` diagnostics that
+> depended on them disappear.
+
+### `gem-without-rbs` (if rbs collection was not yet installed)
+
+If Phase 1 did not install the collection (project had no
+`rbs_collection.lock.yaml`) and triage now reports `gem-without-rbs`,
+this is the right moment to act before the baseline:
+
+```sh
+bundle exec rbs collection install   # if rbs is in Gemfile
+# or: rbs collection install
+```
+
+Re-run `rigor triage`. If the `gem-without-rbs` count drops,
+re-generate the baseline against the new number.
+
 ## Phase 7 — Generate the baseline (acknowledge mode only)
 
 **Strict mode skips this phase entirely.** A strict project has no
@@ -120,22 +196,151 @@ fine; the baseline is a starting envelope, not a verdict that the
 bug is acceptable. Recommend the user run the `rigor-baseline-reduce`
 skill next to work them down.
 
+### Distinguishing sig quality false positives from real bugs
+
+Some diagnostics in the `call.wrong-arity` and
+`def.return-type-mismatch` families are caused by **incomplete or
+incorrect `sig/` declarations**, not by real bugs in the project code.
+Identify them before presenting findings to the user — a sig FP looks
+alarming but needs a sig fix, not a code fix.
+
+#### `call.wrong-arity` on `Struct.new(...)` subclasses
+
+When a project defines a class as:
+
+```ruby
+MyStruct = Struct.new(:foo, :bar, :baz)
+# or
+class MyRecord < Struct.new(:id, :name)
+```
+
+and its `sig/` entry is an empty shell:
+
+```rbs
+class MyRecord
+end
+```
+
+Rigor reads the empty sig and infers `initialize` takes 0 arguments
+(the default). Any `MyRecord.new(x, y)` call then fires
+`call.wrong-arity`. This is a **sig quality issue** — the sig is
+missing the generated `initialize`.
+
+To confirm: check the sig file for the class. If the sig has no
+`initialize` def AND the Ruby source inherits from `Struct.new(...)`,
+the diagnostic is a FP. Note it as a sig improvement task (add
+`initialize` matching the Struct fields) rather than a code bug.
+
+#### `def.return-type-mismatch` when the declared type is `bot`
+
+A sig that declares `-> bot` (or `-> void` for a `raises`-only
+method) says: "this method never returns normally". If Rigor infers
+an actual return value, it fires `def.return-type-mismatch`.
+
+Two interpretations:
+
+| Sig says `-> bot` and … | Interpretation |
+| --- | --- |
+| the implementation has a missing `raise` on one branch | **Likely real bug** — the method was *intended* to always raise, but a code path escapes. High priority: review the branch. |
+| the sig was written conservatively (e.g. auto-generated) and the method does sometimes return | **Sig quality issue** — the sig is too strict. Fix by loosening the return type in the sig. |
+
+To distinguish: read the method body. If every branch ends in `raise`
+or `exit` except one, the missing raise is likely a bug. If the
+method has intentional return values but the sig says `bot`, it is a
+sig issue.
+
+#### `call.argument-type-mismatch` on regex capture variables (`$1`, `$~`)
+
+Rigor infers `$1`, `$~`, and similar capture variables as
+`String | nil` everywhere, even inside `gsub`/`match` blocks where
+they are guaranteed non-nil by the match condition. Diagnostics of
+the form:
+
+```
+expected String, got String | nil   (on $1 / $~)
+```
+
+are **engine FPs** (ADR-24 WD3 / known limitation). Note them as
+noise rather than surfacing them as bugs. They belong in the
+baseline.
+
 ### Escalation path A — application-specific metaprogramming
 
-If triage reports `project-monkey-patch`, or a `call.undefined-method`
-cluster lands on the project's own DSL / `define_method` factory /
-in-house macro, Rigor cannot follow it by default. Two answers,
-cheapest first:
-
-1. **A plain monkey-patch in a known file** (e.g.
-   `lib/core_ext/string_extensions.rb`) — register it via `pre_eval:`
-   in `.rigor.dist.yml`. Rigor walks those files before per-file
-   inference, so the added methods become visible.
-2. **A genuine project DSL** — the durable fix is a **project-private
-   Rigor plugin** that teaches Rigor the DSL's shape. Offer to hand
-   off to the `rigor-plugin-author` skill. The plugin can live under
-   the project's own `lib/` (loaded without a gemspec) or as a
-   separate `rigor-<name>` gem.
+If triage reports `project-monkey-patch-known`, `project-monkey-patch`,
+`unresolved-toplevel`, or a `call.undefined-method` cluster lands on
+the project's own DSL / `define_method` factory / in-house macro,
+Rigor cannot follow it by default.
+
+**The decision that picks the fix is static-vs-dynamic.** Find the
+defining file (named by the hint, or `grep -rn 'def <method>\|<Receiver>'
+app/ lib/`) and look at *how* the method is defined:
+
+| How the method is defined | Fix | Why |
+| --- | --- | --- |
+| **Literal `def foo` / `def self.foo`** in a project file (a plain reopen / monkey-patch, e.g. `lib/core_ext/string_extensions.rb`, `User.current`) | **`pre_eval:`** — copy the file into `pre_eval:` in `.rigor.dist.yml`. | Rigor walks `pre_eval:` files before per-file inference, so the literal method becomes visible everywhere. This is Phase 6a; do it now. |
+| **Dynamically generated** — computed-name `define_method`, `method_missing`, or a `class_eval <<~RUBY … def #{name} … RUBY` heredoc template | **A project-owned Rigor plugin** (escalation, below). `pre_eval:` will *not* help. | The pre-eval walker finds no literal `def` to register, so the cluster survives `pre_eval:`. If you added the file to `pre_eval:` and re-triage shows the cluster unchanged, this is the case you are in. |
+
+So the routine is: try `pre_eval:` for the static case in Phase 6a; if a
+cluster **survives** because the methods are generated, that surviving
+residue is the plugin signal.
+
+#### The plugin handoff (the recommended next step)
+
+A genuine generated DSL is **the project's own plugin to own** — Rigor
+does not bundle per-application plugins for it. The textbook example is
+Redmine's settings accessors:
+
+```ruby
+# app/models/setting.rb — generated, NOT a literal def
+def self.define_setting(name, options = {})
+  # class_eval a heredoc that defines  self.#{name} / #{name}? / #{name}=
+end
+# names come from config/settings.yml, iterated — not source literals
+```
+
+`Setting.app_title`, `Setting.default_language`, … are never written as
+literal `def`s, so `pre_eval:` cannot see them; the durable fix is a
+project plugin (it matches ADR-16's Tier C heredoc-template shape).
+Rigor's stance: application-specific homegrown DSLs are out of scope for
+the bundled substrate (ADR-16 § Audience) — the app authors the plugin
+in their own repo.
+
+> **Sizing the cluster — `rigor triage` may not isolate it.** Triage's
+> `project-monkey-patch` hint groups by method spread and often lumps a
+> generated-DSL cluster in with unrelated patches (or buries it), so the
+> hint count is not the per-receiver size. To measure the actual cluster,
+> drop to the raw stream and count by receiver:
+>
+> ```sh
+> rigor check --format json | \
+>   ruby -rjson -e 'd=JSON.parse(File.read(0, encoding: "UTF-8").scrub); \
+>     puts d["diagnostics"].count { |x| x["message"].to_s.include?("for singleton(Setting)") }'
+> # or quick-and-dirty: rigor check 2>&1 | grep -c "for singleton(Setting)"
+> ```
+>
+> (Force UTF-8 + `.scrub` — diagnostic messages can carry non-ASCII from
+> the project's own strings, e.g. i18n content.) Swap `Setting` for the
+> receiver the def-site grep identified.
+
+When you reach this point:
+
+1. **Name the cluster and its generator** for the user — the count, the
+   receiver, and the defining method (e.g. *"~60 `call.undefined-method`
+   on `Setting.<name>`, generated by `Setting.define_setting`"*). Use the
+   raw-JSON count above, not the triage hint number.
+2. Say plainly that the durable fix is a **project-owned plugin**, not a
+   baseline entry — the baseline only parenthesises the noise; the
+   plugin removes it and types the synthetic methods.
+3. **Offer to launch the `rigor-plugin-author` skill**, and on the
+   user's confirmation, invoke it (Skill tool, `rigor-plugin-author`).
+   That skill scaffolds a standalone `rigor-<id>` gem or a
+   project-private plugin (loadable from the project's own `lib/`
+   without a gemspec) in the *user's* repo.
+
+The offer is not mandatory — acknowledge mode may baseline the cluster
+for now and author the plugin later. But make the next step explicit:
+never leave a generated-DSL cluster in the baseline without telling the
+user it has a real fix and what skill builds it.
 
 ### Escalation path B — an unsupported external gem
 
@@ -163,7 +368,16 @@ the cause; the user decides whether to act now or defer.
   `baseline:` line. Strict mode: neither.
 - The user has seen the likely real bugs and knows the two escalation
   paths.
-
-Next sessions: `rigor-baseline-reduce` to work the baseline down
-(acknowledge mode), or `rigor-plugin-author` if escalation path A
-applies.
+- If a **dynamically-generated project DSL** was found, the user has
+  been told it needs a project-owned plugin and offered the
+  `rigor-plugin-author` handoff (path A) — not left silently in the
+  baseline.
+
+Next sessions, by what the onboarding surfaced:
+
+- **`rigor-plugin-author`** — when a generated project DSL survived
+  `pre_eval:` (escalation path A). This is the durable fix for the
+  cluster and the most impactful follow-up; offer it as the next step
+  before the user reaches for the baseline-reduce loop.
+- **`rigor-baseline-reduce`** — acknowledge mode, to work the recorded
+  baseline down.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rigortype
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.15
 platform: ruby
 authors:
 - Rigor contributors
@@ -291,6 +291,7 @@ files:
 - lib/rigor/cli/explain_command.rb
 - lib/rigor/cli/lsp_command.rb
 - lib/rigor/cli/mcp_command.rb
+- lib/rigor/cli/plugin_command.rb
 - lib/rigor/cli/plugins_command.rb
 - lib/rigor/cli/plugins_renderer.rb
 - lib/rigor/cli/prism_colorizer.rb