rigortype 0.1.12 → 0.1.13

data/skills/rigor-plugin-author/references/03-test-and-ship.md

@@ -0,0 +1,163 @@
+# 03 — Test and ship
+
+Covers **Phase 3** — testing the plugin from outside the rigor
+monorepo, pinning against the pre-1.0 contract, and shipping.
+
+## Testing — drive the public CLI
+
+The rigor monorepo's plugin specs use an internal `plugin_helpers.rb`
+(`run_plugin`, `plugin_diagnostics`). That helper is **not part of
+the published `rigortype` surface** — an external plugin cannot use
+it. Test against what you *do* have: the `rigor` CLI.
+
+The robust pattern is a **fixture project + `rigor check --format
+json`**. It exercises the real load path, the real walker, the real
+diagnostic pipeline — exactly what your users get — and works
+identically under RSpec or Minitest.
+
+### Fixture layout
+
+```text
+spec/fixtures/basic/          (or test/fixtures/basic/)
+├── .rigor.yml                # plugins: [rigor-<id>]
+└── sample.rb                 # code that exercises the plugin
+```
+
+The fixture's `.rigor.yml` activates the plugin and scopes `paths:`
+to the sample file:
+
+```yaml
+paths:
+  - sample.rb
+plugins:
+  - rigor-<id>
+```
+
+### RSpec
+
+```ruby
+# spec/rigor_<id>_spec.rb
+require "json"
+require "open3"
+
+RSpec.describe "rigor-<id>" do
+  def diagnostics_for(fixture)
+    dir = File.expand_path("fixtures/#{fixture}", __dir__)
+    out, _err, _status = Open3.capture3(
+      "bundle", "exec", "rigor", "check", "--format", "json", chdir: dir
+    )
+    JSON.parse(out).fetch("diagnostics")
+  end
+
+  it "flags a dimensional mismatch" do
+    diags = diagnostics_for("basic")
+    rule = diags.map { |d| d["rule"] }
+    expect(rule).to include("plugin.<id>.dimension-mismatch")
+  end
+end
+```
+
+### Minitest
+
+```ruby
+# test/rigor_<id>_test.rb
+require "minitest/autorun"
+require "json"
+require "open3"
+
+class RigorPluginTest < Minitest::Test
+  def diagnostics_for(fixture)
+    dir = File.expand_path("fixtures/#{fixture}", __dir__)
+    out, = Open3.capture3("bundle", "exec", "rigor", "check",
+                          "--format", "json", chdir: dir)
+    JSON.parse(out).fetch("diagnostics")
+  end
+
+  def test_flags_dimensional_mismatch
+    rules = diagnostics_for("basic").map { |d| d["rule"] }
+    assert_includes rules, "plugin.<id>.dimension-mismatch"
+  end
+end
+```
+
+`rigor check --format json` emits one object per run; the
+`"diagnostics"` array carries `path` / `line` / `column` / `message`
+/ `severity` / `rule`. Assert on `rule` and `severity` — they are the
+stable fields. Avoid asserting on exact `message` wording; it changes
+between Rigor releases.
+
+### Unit-test the pure parts directly
+
+Dispatch tables, parsers, and dimension maths inside the plugin are
+plain Ruby — test them as ordinary objects, no `rigor` process
+needed:
+
+```ruby
+it "dispatches distance / time to speed" do
+  result = Rigor::Plugin::Units::MethodTable.dispatch(
+    receiver: :distance, method: :/, args: [:time]
+  )
+  expect(result.dimension).to eq(:speed)
+end
+```
+
+Split the suite: fast unit tests for the logic, a few fixture-driven
+CLI tests for the end-to-end wiring.
+
+## Version pinning — the pre-1.0 contract
+
+The plugin contract is **not frozen until `rigortype` v0.2.0** (see
+SKILL.md). Concretely:
+
+- Gemspec / Gemfile: `rigortype` `>= 0.1.0, < 0.2.0`. Never `>= 0.1`
+  alone — that floats across the contract-changing v0.2.0 boundary.
+- Your plugin's own version is normal semver, independent of
+  `rigortype`'s.
+- When you bump the `rigortype` pin to a new minor, **re-run the
+  full test suite** — the walker hook signature or the `Diagnostic` /
+  type-carrier shapes may have changed. The fixture CLI tests are
+  what catch a contract drift.
+- State the supported `rigortype` range in the README so users do
+  not pair the plugin with an incompatible Rigor.
+
+When v0.2.0 lands, re-pin to the stable range and ordinary
+compatibility rules apply.
+
+## README
+
+A plugin README should carry:
+
+1. **What it does** — the DSL / framework it teaches Rigor, and one
+   sample diagnostic.
+2. **Install** — `gem "rigor-<id>"` (or the path-gem snippet for a
+   project-private plugin).
+3. **Activate** — the `.rigor.yml` `plugins:` entry, plus any
+   `config:` keys and `signature_paths:`.
+4. **Compatibility** — the supported `rigortype` version range, and
+   the pre-1.0-contract caveat.
+5. **License.**
+
+## Ship
+
+**Standalone gem** — `gem build rigor-<id>.gemspec` then
+`gem push`. Tag the release. Announce the supported `rigortype`
+range.
+
+**Project-private plugin** — nothing to publish. Commit it with the
+app (the `rigor-plugin/` path-gem directory, or the `RUBYLIB` file).
+Make sure CI runs `rigor check` so the plugin stays
+wired and the fixture tests run.
+
+Either way, if the plugin uncovered a gap that *should* be core
+Rigor behaviour — or if you hit a plugin-contract rough edge — report
+it: <https://github.com/rigortype/rigor/issues>. External plugin
+authors are the main source of pre-v0.2.0 contract feedback.
+
+## Output of this module — plugin shipped
+
+- A test suite: fast unit tests + fixture-driven `rigor check`
+  tests, in RSpec or Minitest.
+- A `rigortype` pin tight to `< 0.2.0`.
+- A README stating the compatibility range.
+- The plugin published as a gem, or committed project-private with
+  CI wired.

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

@@ -0,0 +1,129 @@
+---
+name: rigor-project-init
+description: |
+  Onboard a project to Rigor type-checking from scratch: detect the stack, choose an adoption mode (baseline vs. strict), select plugins, write `.rigor.dist.yml`, then snapshot a baseline or commit to a zero-diagnostic gate. Triggers: "set up Rigor in this project", "configure rigor for X", "add type checking", or running `rigor check` in a Gemfile directory with no `.rigor.yml`. NOT for reducing an existing baseline (use rigor-baseline-reduce) or authoring a plugin (use rigor-plugin-author).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Project Init
+
+End-to-end onboarding for a project that has never run Rigor. The
+output is a committed `.rigor.dist.yml`, an explicit adoption mode,
+and — if the project chooses it — a `.rigor-baseline.yml` snapshot.
+
+This skill is for **users adopting Rigor on their own project**. It
+uses the published `rigor` executable, installed standalone — Rigor
+is a tool, not a library, so it does **not** go in the project's
+`Gemfile`. See the manual's
+[Installing Rigor](../../docs/manual/01-installation.md)
+chapter for the install channels (`mise` recommended). This skill
+references only public CLI flags and config keys — the same surface
+`rigor --help` documents.
+
+## Phase 0 — When to use this skill
+
+Trigger when the user says "set up Rigor here", "configure rigor for
+this app", "add type checking", or runs `rigor check` in a project
+that has no `.rigor.yml` / `.rigor.dist.yml`.
+
+Do NOT trigger for:
+
+- **An existing baseline the user wants to shrink** — that is the
+  `rigor-baseline-reduce` skill.
+- **Writing a Rigor plugin** for the project's own DSL /
+  metaprogramming — that is the `rigor-plugin-author` skill. (This
+  skill *points at* plugin authoring as an escalation in Phase 7;
+  it does not do it.)
+- **Tweaking an already-configured project** — ordinary edits to an
+  existing `.rigor.yml`; no onboarding pipeline needed.
+
+## Note — plugin installation
+
+All `rigor-*` plugins ship **bundled inside the `rigortype` gem**.
+No separate installation is needed. Listing a plugin under
+`plugins:` in `.rigor.dist.yml` is sufficient to activate it.
+The project's `Gemfile` is untouched by this workflow.
+See [`references/02-configure.md`](references/02-configure.md)
+§ "No separate installation needed" for detail.
+
+## The central decision — adoption mode
+
+A mature Ruby codebase routinely reports hundreds to thousands of
+diagnostics the first time `rigor check` runs. Most are not fresh
+bugs: some are real-but-empirically-safe (`T | nil` that production
+always initialises), some are project style, a minority are genuine
+latent bugs. Forcing every site to zero before adoption blocks
+adoption entirely.
+
+So **before writing any config, present the user with two modes**
+and let them choose. The mode drives the severity profile, whether a
+baseline is generated, and how Phase 7 frames the leftover
+diagnostics.
+
+| | **Acknowledge mode** (baseline adoption) | **Strict mode** (no compromise) |
+| --- | --- | --- |
+| Goal | Adopt Rigor now; make sure *ordinary coding does not increase* the diagnostic count. | Drive the project to zero outstanding diagnostics and keep it there. |
+| Today's diagnostics | Snapshotted into `.rigor-baseline.yml`; suppressed as long as the count does not grow. | All surfaced; every one is fixed or consciously suppressed. |
+| Hard-to-fix diagnostics | Left in the baseline. The project **trusts its test / spec suite** to cover runtime correctness for those sites — the static `T | nil` reading is worst-case-sound, the suite proves the worst case is not hit. | Fixed, or annotated `# rigor:disable <rule>` with an author-intent reason at the specific line. No blanket suppression. |
+| `severity_profile` | `lenient` (or `balanced` for a small project). | `strict`. |
+| Best for | Mature codebases; incremental adoption; teams that want the regression guard without a big upfront fix. | New / small projects; libraries; teams that want the maximum guarantee and have the budget to reach zero. |
+| New diagnostics later | Surface immediately — anything beyond the baseline envelope is a regression. | Surface immediately — there is no envelope; every diagnostic is live. |
+
+Both modes give the same core guarantee: **a change that introduces
+a new diagnostic is caught.** They differ only in what happens to the
+diagnostics that exist *today*. Acknowledge mode parenthesises them
+behind a baseline and leans on the test suite; strict mode refuses to
+parenthesise anything.
+
+If the project's first `rigor check` reports more than ~100 errors,
+recommend acknowledge mode as the default and let the user override.
+Below that, either mode is reasonable — ask.
+
+## Phase outline
+
+| Phase | What | Reference |
+| --- | --- | --- |
+| 1 | Detect the project shape (Gemfile / Gemfile.lock walk). | [`references/01-detect.md`](references/01-detect.md) |
+| 2 | Present the two adoption modes; record the user's choice. | (this file — § "The central decision") |
+| 3 | Select the plugin set matching the detected stack. | [`references/01-detect.md`](references/01-detect.md) |
+| 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) |
+| 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) |
+
+Load each reference when you reach its phase. Phases run in order;
+the only branch is Phase 7 (acknowledge mode runs it, strict mode
+skips it). Phase 5 is also optional if the project already has a
+committed `sig/` directory.
+
+## Reading order — modules
+
+| Module | Read | Covers |
+| --- | --- | --- |
+| 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. |
+
+## Escalation paths (Phase 7 preview)
+
+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.
+- **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
+  support, **open an issue on the Rigor project** asking for it:
+  <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.

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

@@ -0,0 +1,101 @@
+# 01 — Detect the project shape & select plugins
+
+Covers **Phase 1** (detect) and **Phase 3** (plugin selection). Run
+Phase 2 — the mode choice — from `SKILL.md` between them.
+
+## Phase 1 — Detect
+
+Read two files at the project root. Do not run code; just parse them.
+
+### `Gemfile` — framework family
+
+Scan the `gem "…"` lines for the markers below. A project can match
+more than one row (a Rails app with RSpec and Sidekiq matches three).
+
+| Marker gems | Family |
+| --- | --- |
+| `rails`, `railties`, `actionpack`, `activerecord` | Rails |
+| `sinatra` | Sinatra |
+| `dry-types`, `dry-struct`, `dry-schema`, `dry-validation` | dry-rb |
+| `rspec`, `rspec-core` | RSpec test suite |
+| `sorbet`, `sorbet-runtime` | Sorbet-typed |
+| none of the above | plain Ruby |
+
+Also note per-gem markers that have their own plugin: `devise`,
+`pundit`, `sidekiq`.
+
+### `Gemfile.lock` — versions & RBS state
+
+- Read the **locked versions** of the framework gems — a plugin
+  recommendation can depend on a major version.
+- Check for `rbs_collection.lock.yaml` at the project root AND whether
+  `.gem_rbs_collection/` exists alongside it.
+  - **Lockfile present, `.gem_rbs_collection/` present** → the collection
+    is installed; Rigor will auto-detect and consume it via
+    `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.
+  - **Both absent** → note it; Phase 6's triage may recommend
+    `rbs collection install` if `gem-without-rbs` hints appear.
+
+### Path scope
+
+Note the conventional source roots so Phase 4 can set `paths:`:
+
+- Rails → `app`, `lib`.
+- gem / library → `lib`.
+- plain app → `lib`, or the directory holding the code.
+
+`spec/` and `test/` are normally **excluded** from `paths:` — they
+are checked differently and inflate the diagnostic count. `vendor/`
+and `tmp/` are always excluded.
+
+## Phase 3 — Plugin selection
+
+Propose a plugin set from the detected families. Present it to the
+user as a list they can trim — do not silently enable everything.
+
+| Family | Recommended plugins |
+| --- | --- |
+| Rails | `rigor-actionpack`, `rigor-activerecord`, `rigor-actionmailer`, `rigor-rails-routes`, `rigor-rails-i18n`, plus `rigor-activesupport-core-ext` (almost always needed — see below) |
+| dry-rb | `rigor-dry-types`, `rigor-dry-struct`, and `rigor-dry-schema` / `rigor-dry-validation` when those gems are present |
+| Sinatra | `rigor-sinatra` |
+| RSpec | `rigor-rspec` |
+| Devise / Pundit / Sidekiq present | `rigor-devise` / `rigor-pundit` / `rigor-sidekiq` |
+| Sorbet present | `rigor-sorbet` (ingests existing `sig` blocks / RBI as type sources) |
+| plain Ruby | none required — the core analyzer covers it |
+
+The current production-plugin catalogue is the authority for which
+plugins exist and how each is named / installed:
+<https://github.com/rigortype/rigor/blob/master/plugins/README.md>.
+The set drifts as new plugins land — consult that page rather than
+treating the table above as exhaustive.
+
+### `rigor-activesupport-core-ext` — the common Rails gap
+
+ActiveSupport monkey-patches the core classes (`3.days`,
+`5.minutes`, `"x".squish`, `Time.current`, …). Without the
+`rigor-activesupport-core-ext` bundle, every such call reports
+`call.undefined-method` — on a real Rails app this is the single
+largest diagnostic cluster (a measured Mastodon run: ~365 of 489
+diagnostics were exactly this). Phase 5's `rigor triage` flags it as
+hint `activesupport-core-ext`.
+
+`rigor-activesupport-core-ext` is a **plugin** (an RBS-bundle plugin
+— it contributes signatures, not diagnostics). Activate it like any
+other: list it under `plugins:`. No `signature_paths:` wiring is
+needed — the plugin ships its own `sig/`. Include it for any
+Rails-family project.
+
+## Output of this module
+
+- A framework-family list.
+- A proposed, user-trimmed plugin set.
+- The `paths:` / `exclude:` scope for Phase 4.
+- Whether an RBS collection already exists.
+
+Carry these into Phase 4 ([`02-configure.md`](02-configure.md)).

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

@@ -0,0 +1,185 @@
+# 02 — Write the configuration
+
+Covers **Phase 4**. Inputs: the plugin set + path scope from
+[`01-detect.md`](01-detect.md), and the adoption mode chosen in
+Phase 2.
+
+## `.rigor.dist.yml` vs `.rigor.yml`
+
+Rigor reads both. The convention:
+
+- **`.rigor.dist.yml`** — the committed, shared project config. This
+  skill writes this file.
+- **`.rigor.yml`** — an optional, gitignored per-developer override.
+  Leave it for individuals to create; do not write one here.
+
+When both exist, `.rigor.yml` takes precedence. Writing the shared
+config as `.rigor.dist.yml` lets a contributor opt out locally (for
+example, run without the baseline) without touching the committed
+file.
+
+## Severity profile — follows the mode
+
+The `severity_profile:` key re-stamps every rule's severity. Set it
+from the Phase 2 mode:
+
+| Mode | `severity_profile` | Why |
+| --- | --- | --- |
+| Acknowledge, >100 errors on first run | `lenient` | Most rules become warnings; the baseline carries the residue. The point is the regression guard, not a wall of errors. |
+| Acknowledge, small project | `balanced` | The default. Errors stay errors; the baseline is small enough to live with. |
+| Strict | `strict` | Promotes borderline rules to errors. Paired with no baseline, every diagnostic is a live gate. |
+
+`balanced` is the built-in default — omit the key to get it.
+
+## No separate installation needed
+
+All plugins ship **bundled inside the `rigortype` gem**. The
+`plugins:` list in the config is all that is needed to activate
+them — the plugin loader runs `require "rigor-<id>"` from within
+the gem's own load path. No Gemfile entry, no `bundle install`,
+no separate gem channel.
+
+**The `rigortype` gem itself stays out of the project's
+`Gemfile`** — install it standalone per the manual's
+[Installing Rigor](../../docs/manual/01-installation.md) chapter
+(`mise use gem:rigortype` is the recommended channel). The
+project's Gemfile is untouched by this workflow.
+
+## The template
+
+Write `.rigor.dist.yml` at the project root. A Rails app in
+acknowledge mode looks like:
+
+```yaml
+# .rigor.dist.yml — Rigor configuration (committed; shared).
+# Generated by the rigor-project-init workflow.
+
+# Match the Ruby version in .ruby-version or the Gemfile `ruby "x.y"` line.
+# Rigor defaults to 4.0; set this explicitly if the project targets Ruby < 4.0.
+target_ruby: "3.4"
+
+paths:
+  - app
+  - lib
+
+exclude:
+  - vendor
+  - tmp
+
+plugins:
+  - rigor-actionpack
+  - rigor-activerecord
+  - rigor-actionmailer
+  - rigor-rails-routes
+  - rigor-rails-i18n
+  # An RBS-bundle plugin — ships ActiveSupport core_ext signatures,
+  # no signature_paths: wiring needed (see 01-detect.md).
+  - rigor-activesupport-core-ext
+
+severity_profile: lenient
+
+# Phase 6 (acknowledge mode) appends this line after generating the
+# baseline. Strict mode leaves it out entirely.
+# baseline: .rigor-baseline.yml
+```
+
+### Existing `sig/` directory
+
+If the project already has a `sig/` directory (from Steep, `rbs_rails`,
+or handwritten annotations), wire it into `signature_paths:` so Rigor
+consumes it. Phase 5 (sig uplift) can be skipped, but the paths must
+still be declared — Rigor does not auto-detect `sig/`:
+
+```yaml
+signature_paths:
+  - sig/handwritten   # adjust to the layout in your project
+  - sig/generated
+```
+
+List only directories that contain `.rbs` files or subdirectories of
+them. Rigor walks each path recursively. If the sig layout is a single
+flat `sig/` directory, use `- sig` instead.
+
+A strict-mode plain-Ruby gem is shorter:
+
+```yaml
+paths:
+  - lib
+severity_profile: strict
+```
+
+### Key reference
+
+Only the keys this skill needs. `rigor --help` and the project
+handbook document the full surface.
+
+| Key | Meaning |
+| --- | --- |
+| `paths:` | Directories Rigor analyses. Source roots only — not `spec/` / `test/`. |
+| `exclude:` | Paths removed from the `paths:` walk. |
+| `plugins:` | Plugin ids to activate (the Phase 3 set). |
+| `signature_paths:` | Extra RBS source **directories** (paths, not gem names; resolved relative to the config file). Use it for the project's own local `sig/` if it has one. RBS-bundle *plugins* like `rigor-activesupport-core-ext` ship their own `sig/` and need no entry here — list them under `plugins:`. |
+| `severity_profile:` | `lenient` / `balanced` / `strict`. See the table above. |
+| `severity_overrides:` | Per-rule severity tweaks. Leave empty at init; the baseline-reduce workflow tunes it later. |
+| `baseline:` | Path to the baseline file. **Only acknowledge mode sets it**, and only in Phase 6 *after* the file exists. Per Rigor's no-magic rule, a `.rigor-baseline.yml` on disk does nothing until this key names it. |
+| `pre_eval:` | Project files Rigor walks before per-file inference — used to register in-project monkey-patches. Leave empty at init; Phase 7 may suggest it. |
+| `dependencies.source_inference:` | Opt-in inference for gems shipping no RBS. Leave empty at init; Phase 7 may suggest it. |
+
+## Do not write the baseline yet
+
+Phase 4 writes the config with the `baseline:` line **commented out
+or absent**. The baseline file does not exist until Phase 6, and a
+`baseline:` pointing at a missing file is an error. Phase 6 writes
+the file and uncomments / appends the line in one step.
+
+Strict mode never adds `baseline:` at all.
+
+## Verify plugin activation (`rigor plugins`)
+
+Before proceeding to sig uplift, **run `rigor plugins`** from the
+project root to confirm every entry under `plugins:` actually
+loaded. The activation surface is the part of the configuration
+most prone to silent failure — a typoed gem name, a missing
+third-party plugin gem, or running rigor from a different cwd
+(so a different `.rigor.yml` is discovered) all leave plugins
+inert, which the per-file diagnostic stream then attributes to
+"missing types" rather than to a config gap.
+
+```sh
+rigor plugins
+```
+
+Expected: every entry shows `[OK ]`, the `loaded: N` count
+matches the entries in `plugins:`, and `load-error: 0`. The
+report also lists each plugin's `signature_paths:` (with a
+per-directory `.rbs` file count) and any `open_receivers:` /
+`owns_receivers:` / `produces:` / `consumes:` / macro substrate
+contributions — useful for confirming the plugin is contributing
+what you expect.
+
+If any entry shows `[ERR]`, read the `load error:` line:
+
+| Error fragment | Cause | Fix |
+| --- | --- | --- |
+| `could not load plugin gem "rigor-foo"` | The gem is not on the load path. Either misspelled in `plugins:`, or a third-party plugin (per ADR-31 WD4) that is not installed in the rigor runtime environment. | Check spelling against the catalogue in `01-detect.md`; for third-party plugins, install via the same channel that installed `rigortype` (mise / gem install). |
+| `did not register any plugin via Rigor::Plugin.register` | The require succeeded but the gem did not call `Rigor::Plugin.register`. Usually a version mismatch (older / forked rigor-foo) or a partial install. | Reinstall the plugin gem; verify the version matches `rigortype`'s. |
+| `signature path "..." is not a directory` | The bundled `sig/` directory is missing — a packaging bug in the plugin gem. | File an issue against the plugin gem's repo. |
+| `plugin "foo" config invalid: ...` | The `config:` block under the plugin entry has a typo or wrong value type. | Compare against the plugin's documented `config_schema:`. |
+
+Re-run `rigor plugins` until `load-error: 0`. Add `--strict` to
+the invocation when you want it to exit 1 (the canonical CI gate
+shape):
+
+```sh
+rigor plugins --strict
+```
+
+## Output of this module
+
+A committed `.rigor.dist.yml` with `paths:`, `exclude:`,
+`plugins:`, and `severity_profile:` set — and no active
+`baseline:` line. `rigor plugins` reports every entry loaded,
+zero load errors. No Gemfile changes; plugins are bundled inside
+`rigortype`.
+
+Proceed to Phase 5 ([`04-sig-uplift.md`](04-sig-uplift.md)).