rigortype 0.1.11 → 0.1.13

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

@@ -0,0 +1,195 @@
+# 01 — Package and scaffold
+
+Covers **Phase 1**. Output: a directory tree, a plugin class
+skeleton that registers itself, and an `.rigor.yml` that activates
+it.
+
+## Naming
+
+- **Plugin id** — kebab-case, starts with a letter, matches
+  `/\A[a-z][a-z0-9._-]*\z/`. Descriptive: `units`, `myapp-dsl`,
+  `legacy-macros`.
+- **Require name** — Rigor activates a plugin by `require`-ing the
+  name in the `.rigor.yml` `plugins:` entry. The convention is
+  `rigor-<id>`, and the file that name resolves to must, when
+  loaded, call `Rigor::Plugin.register`.
+- **Ruby class** — CamelCase under `Rigor::Plugin`, e.g.
+  `Rigor::Plugin::MyappDsl`.
+
+## Standalone gem layout
+
+```text
+rigor-<id>/                      # its own repository
+├── README.md
+├── rigor-<id>.gemspec
+├── Gemfile                      # gem "rigortype" (dev); gemspec
+├── lib/
+│   ├── rigor-<id>.rb            # require name → require_relative the class
+│   └── rigor/plugin/
+│       └── <id>.rb              # the plugin class + Rigor::Plugin.register
+│       └── <id>/                # only if it needs helpers
+│           └── analyzer.rb      # AST walker extracted out of the class
+├── sig/                         # optional — RBS for the DSL (Phase 2)
+└── spec/  or  test/             # fixture tests (Phase 3)
+```
+
+### Gemspec template
+
+```ruby
+# rigor-<id>.gemspec
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name        = "rigor-<id>"
+  spec.version     = "0.1.0"
+  spec.authors     = ["Your Name"]
+  spec.summary     = "Rigor plugin: <one line>."
+  spec.description = "<two sentences naming the DSL / API the plugin types>."
+  spec.license     = "MIT"        # your choice
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files        = Dir.glob(%w[README.md lib/**/*.rb sig/**/*.rbs])
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "prism", ">= 1.0", "< 2.0"
+  # Pin tightly — the plugin contract is pre-1.0 (see SKILL.md).
+  spec.add_dependency "rigortype", ">= 0.1.0", "< 0.2.0"
+end
+```
+
+`prism` is Rigor's parser; a plugin walks `Prism::Node`s, so depend
+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:
+
+### Recommended — a path gem
+
+Keep the plugin in a subdirectory with its own gemspec, and reference
+it from the app's `Gemfile` by path:
+
+```text
+your-app/
+├── Gemfile
+├── rigor-plugin/                # the plugin, unpublished
+│   ├── rigor-myapp.gemspec
+│   └── lib/
+│       ├── rigor-myapp.rb
+│       └── rigor/plugin/myapp.rb
+└── .rigor.yml
+```
+
+```ruby
+# your-app/Gemfile
+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.
+
+## The plugin class skeleton
+
+`lib/rigor-<id>.rb` — the require entry point:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/<id>"
+```
+
+`lib/rigor/plugin/<id>.rb` — the plugin class:
+
+```ruby
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class MyappDsl < Rigor::Plugin::Base
+      manifest(
+        id: "<id>",
+        version: "0.1.0",
+        description: "<one line>",
+        # Optional: declare config keys the user may set under
+        # `.rigor.yml` plugins: [{ gem:, config: { … } }].
+        config_schema: {
+          # "module_name" => :string,
+          # "rules"       => :array,
+        }
+      )
+
+      # Called once at load time with the service container.
+      # Read config defaults here. `config` is the validated
+      # user config Hash.
+      def init(_services)
+        @module_name = config.fetch("module_name", "Default")
+      end
+
+      # Called per analysed file. `root` is the file's Prism AST,
+      # `scope` answers inferred-type queries. Return an Array of
+      # Rigor::Analysis::Diagnostic. See 02-walker-and-types.md.
+      def diagnostics_for_file(path:, scope:, root:)
+        []
+      end
+    end
+
+    Rigor::Plugin.register(MyappDsl)
+  end
+end
+```
+
+`Rigor::Plugin.register` at the bottom is mandatory — the loader
+`require`s the gem, then looks for a freshly-registered plugin
+class. A gem that registers nothing fails to load with a clear
+error.
+
+## Activate the plugin in `.rigor.yml`
+
+```yaml
+plugins:
+  - rigor-<id>
+
+# Hash form when the plugin takes config:
+# plugins:
+#   - gem: rigor-<id>
+#     config:
+#       module_name: MyApp
+```
+
+Confirm activation with the public CLI:
+
+```sh
+rigor check
+```
+
+A misconfigured plugin surfaces as a `plugin-loader` diagnostic
+rather than crashing the run — read that message if the plugin seems
+inert.
+
+## Output of this module
+
+A scaffolded plugin that loads (even if `diagnostics_for_file` still
+returns `[]`) and is activated in `.rigor.yml`. Proceed to Phase 2
+([`02-walker-and-types.md`](02-walker-and-types.md)) to make it
+actually analyse.

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.