rigortype 0.1.12 → 0.1.14

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

@@ -0,0 +1,155 @@
+# 02 — The walker and types
+
+Covers **Phase 2** — making `diagnostics_for_file` analyse the AST,
+emit diagnostics, and (optionally) contribute return types.
+
+## `diagnostics_for_file` — the core hook
+
+```ruby
+def diagnostics_for_file(path:, scope:, root:)
+  # root  — Prism::Node, the parsed file (a ProgramNode).
+  # scope — answers inferred-type queries: scope.type_of(node).
+  # path  — the file path, for Diagnostic#path.
+  # → return Array<Rigor::Analysis::Diagnostic>
+end
+```
+
+Walk `root` with a Prism visitor or a recursive descent, recognise
+the DSL's call shapes, and collect diagnostics. Keep the walk in a
+separate `Analyzer` class once it grows past a few methods — pass it
+`path` and let it return the diagnostic array.
+
+### Recognising call sites
+
+Most DSL plugins key off `Prism::CallNode`:
+
+```ruby
+def each_call(node, &block)
+  block.call(node) if node.is_a?(Prism::CallNode)
+  node&.compact_child_nodes&.each { |child| each_call(child, &block) }
+end
+```
+
+Then match on `node.name` (the method name, a Symbol),
+`node.receiver`, and `node.arguments&.arguments`.
+
+## Building a `Diagnostic`
+
+Every diagnostic the plugin emits is a `Rigor::Analysis::Diagnostic`.
+A small constructor helper keeps the call sites clean:
+
+```ruby
+def diagnostic(path, node, severity:, rule:, message:)
+  loc = node.location
+  Rigor::Analysis::Diagnostic.new(
+    path:     path,
+    line:     loc.start_line,
+    column:   loc.start_column + 1,   # 1-based column
+    message:  message,
+    severity: severity,               # :error | :warning | :info
+    rule:     rule                    # short kebab-case id
+  )
+end
+```
+
+`rule` is a short identifier (`dimension-mismatch`,
+`unknown-state`). Rigor namespaces it under your plugin —
+diagnostics surface as `plugin.<manifest.id>.<rule>`, and that
+qualified id is what `.rigor.yml` `disable:` and the baseline key
+on. Pick `severity`:
+
+- `:error` — a real defect (a type mismatch, a call that will
+  raise). Fails `rigor check`.
+- `:warning` — suspicious but not certainly wrong.
+- `:info` — informational; surfaces inferred facts without
+  judgement.
+
+## Asking the analyzer for types — `scope.type_of`
+
+A plugin does not have to infer types itself. `scope.type_of(node)`
+returns the type the core analyzer inferred for any AST node — the
+plugin can build on it:
+
+```ruby
+receiver_type = scope.type_of(call_node.receiver)
+```
+
+The returned object is one of the `Rigor::Type::*` carriers. The
+ones a plugin meets most:
+
+- `Rigor::Type::Nominal` — a class type; `#class_name` is the
+  String.
+- `Rigor::Type::Constant` — a literal value; `#value` is the Ruby
+  object.
+- `Rigor::Type::IntegerRange` — a bounded integer.
+
+Match with `case`/`when` on the carrier class. Treat any carrier you
+do not recognise as "decline to act" — never crash on an unexpected
+type.
+
+## Optional — contribute a return type with `flow_contribution_for`
+
+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`:
+
+```ruby
+def flow_contribution_for(call_node:, scope:)
+  return nil unless call_node.is_a?(Prism::CallNode)
+  # ... decide the call site's real return type ...
+  return nil if undecidable   # nil = "I have nothing to add"
+
+  Rigor::FlowContribution.new(
+    return_type: a_rigor_type,
+    provenance: Rigor::FlowContribution::Provenance.new(
+      source_family: "plugin.#{manifest.id}",
+      plugin_id:     manifest.id,
+      node:          call_node,
+      descriptor:    nil
+    )
+  )
+end
+```
+
+Build the `return_type` with `Rigor::Type::Combinator`:
+
+```ruby
+Rigor::Type::Combinator.nominal_of("Money")        # a class type
+Rigor::Type::Combinator.constant_of(true)          # a literal
+Rigor::Type::Combinator.union(a, b)                # a union
+```
+
+Returning `nil` is always safe — it means "no contribution", and the
+core analyzer keeps its own answer. Contribute a type only when the
+plugin is confident; a wrong contribution propagates downstream.
+
+This hook is the most contract-sensitive surface — it is the part
+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
+
+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.
+
+## Output of this module
+
+A plugin whose `diagnostics_for_file` recognises the DSL and emits
+diagnostics with correct severities and rule ids — optionally a
+`flow_contribution_for` and a `sig/` bundle. Verify by eye with
+`rigor check`; lock it down with tests in Phase 3
+([`03-test-and-ship.md`](03-test-and-ship.md)).

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,139 @@
+# 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. **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:`:
+
+- 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)).