rigortype 0.3.9 → 0.4.0

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-plugin-review
-description: |
-  Review an existing Rigor plugin's source against the current authoring contract and produce a prioritized upgrade path — the modernization counterpart to rigor-plugin-author. Audits config-default declaration (ADR-40), the AST-walk model (node_rule vs a hand-rolled traversal), return-type / narrowing hooks (dynamic_return / narrowing_facts, not the removed flow_contribution_for or type_specifier), the ADR-60 WD4 authoring helpers (diagnostic / diagnostics_for / suggest / producer_value / read_fact), engine-collaboration vs reimplementation, cache-producer soundness, manifest-field hygiene, and doc freshness. Triggers: "review this Rigor plugin", "does my plugin follow best practices", "upgrade our rigor-prefixed plugin to the latest contract", "modernize this plugin", "is this plugin using the current API". NOT for authoring a new plugin (use rigor-plugin-author), enabling bundled plugins on a project (use rigor-plugin-tune), or tuning plugin config.
+description: >-
+  Audit an existing Rigor plugin against the current authoring contract and produce a prioritized upgrade
+  path. Use when modernizing or reviewing a `rigor-*` plugin; not for authoring a new plugin, enabling
+  bundled plugins, or tuning project config.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -120,7 +122,7 @@ green first, so you can prove each later step is a faithful refactor:
 # external gem:
 bundle exec rspec spec/
 # in the rigor monorepo:
-nix … develop --command bundle exec rspec spec/integration/<plugins|examples>/<id>_plugin_spec.rb
+nix develop --command bundle exec rspec spec/integration/<plugins|examples>/<id>_plugin_spec.rb
 ```
 
 If there is no spec, **write one first** (per `rigor-plugin-author`
@@ -148,7 +150,7 @@ step**:
 ### Phase 5 — Verify
 
 ```sh
-rigor check <plugin>/lib        # ADR-43 contract self-check — MUST be clean
+rigor check <plugin>/lib        # ADR-43 contract self-check — must be clean
 rigor plugins --strict          # the plugin still loads
 rigor plugins --capabilities    # node-rule types / dynamic_return receivers look right
 bundle exec rspec …             # the oracle spec, still green

data/skills/rigor-plugin-review/references/01-best-practices-checklist.md

@@ -205,7 +205,8 @@ and put that in a CHANGELOG / migration note, not the class docstring.
 
 - `rigor check <plugin>/lib` — the ADR-43 contract self-check resolves
   the plugin's inherited `Plugin::Base` calls and warns on contract
-  misuse. MUST be clean; fix the cause, never disable the rule.
+  misuse. It must be clean; fix the cause rather than disabling the
+  rule.
 - `rigor plugins --strict` — the plugin still activates.
 - `rigor plugins --capabilities` — `node_rule_types` /
   `dynamic_return_receivers` / `narrowing_facts_methods` reflect the

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-plugin-tune
-description: |
-  Re-scan a configured project's Gemfile.lock against Rigor's bundled plugin catalogue and enable the plugins that match its current dependencies (Rails, RSpec, dry-rb, Sidekiq, Devise, …), then verify they all load. Run it after adding a gem, or when an onboarding predates a dependency the project now uses. Triggers: "enable the right Rigor plugins", "I added gem X, does Rigor have a plugin?", "which rigor plugins should this project use?", "rigor plugins for my stack". NOT for first-time onboarding (use rigor-project-init, which does the initial selection) and NOT for authoring a new plugin (use rigor-plugin-author).
+description: >-
+  Match a configured project's `Gemfile.lock` to Rigor's bundled plugin catalogue and enable the plugins
+  its current dependencies need. Use after adding a gem or when plugin selection is stale; not for
+  first-time onboarding or authoring a new plugin.
 license: MPL-2.0
 metadata:
   version: 0.1.0

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

@@ -1,7 +1,9 @@
 ---
 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).
+description: >-
+  Onboard a project to Rigor from scratch by detecting the stack, selecting plugins and an adoption mode,
+  and writing the initial config and baseline or strict gate. Use for first-time Rigor setup; not for an
+  existing baseline or plugin authoring.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -52,7 +54,7 @@ Do NOT trigger for:
   `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;
+  skill *points at* plugin authoring as an escalation in Phase 8;
   it does not do it.)
 - **Tweaking an already-configured project** — ordinary edits to an
   existing `.rigor.yml`; no onboarding pipeline needed.
@@ -77,7 +79,7 @@ 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
+baseline is generated, and how Phase 8 frames the leftover
 diagnostics.
 
 | | **Acknowledge mode** (baseline adoption) | **Strict mode** (no compromise) |
@@ -154,7 +156,7 @@ committed `sig/` directory.
 | 5 | [`references/06-agent-contract.md`](references/06-agent-contract.md) | **Phase 8a.** The one paragraph the project's `AGENTS.md` / `CLAUDE.md` keeps so every agent session sources types from Rigor rather than guessing them. Where to append it, when to create the file, and what never to overwrite. |
 | — (optional) | [`references/05-jit-performance.md`](references/05-jit-performance.md) | **Operational, not a phase.** Run speed via a Ruby JIT: Rigor auto-enables YJIT for long runs (~5 s break-even), how to detect JIT support in your install, the override env vars, and why YJIT beats ZJIT for Rigor on Ruby 4.0. Read only when a large project's `rigor check` wall time matters. |
 
-## Escalation paths (Phase 7 preview)
+## Escalation paths (Phase 8 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:
@@ -183,7 +185,7 @@ material. Two of them have a dedicated answer this skill hands off to:
   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
+Neither is a Phase 8 obligation — they are options to *offer* the
 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)
@@ -223,7 +225,7 @@ 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.dist.yml` | The shared project config (Phase 4) — `target_ruby`, `paths:`, `test_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`. |

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

@@ -71,14 +71,13 @@ 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.
+**Note: RBS collision after install.** Rigor skips collection entries
+for gems it already loads from its bundled RBS — including gems
+extracted from Ruby's stdlib, such as `cgi` and `logger` — so the
+collection does not double-declare them. If `rigor triage` still prints
+an `RBS::DuplicatedDeclarationError`, note it and continue, and report
+it at <https://github.com/rigortype/rigor/issues> with the gem names the
+error mentions.
 
 ### Path scope
 
@@ -92,6 +91,11 @@ Note the conventional source roots so Phase 4 can set `paths:`:
 are checked differently and inflate the diagnostic count. `vendor/`
 and `tmp/` are always excluded.
 
+Note the **test roots** too — every directory holding the project's
+tests, not only the conventional one (`spec/`, `test/`, and any
+extra suite such as `test/system` kept elsewhere or an
+`integration/` tree). Phase 4 writes them to `test_paths:`.
+
 ## Phase 3 — Plugin selection
 
 Propose a plugin set from the detected families. Present it to the
@@ -120,7 +124,7 @@ ActiveSupport monkey-patches the core classes (`3.days`,
 `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
+diagnostics were exactly this). Phase 6's `rigor triage` flags it as
 hint `activesupport-core-ext`.
 
 `rigor-activesupport-core-ext` is a **plugin** (an RBS-bundle plugin

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

@@ -91,6 +91,11 @@ paths:
   - app
   - lib
 
+# Where the tests live. `rigor sig-gen --params=observed` reads their
+# call sites to type parameters (Phase 5). Not analysed by `rigor check`.
+test_paths:
+  - spec
+
 exclude:
   - vendor
   - tmp
@@ -107,7 +112,7 @@ plugins:
 
 severity_profile: lenient
 
-# Phase 6 (acknowledge mode) appends this line after generating the
+# Phase 7 (acknowledge mode) appends this line after generating the
 # baseline. Strict mode leaves it out entirely.
 # baseline: .rigor-baseline.yml
 ```
@@ -138,9 +143,28 @@ A strict-mode plain-Ruby gem is shorter:
 ```yaml
 paths:
   - lib
+test_paths:
+  - test
 severity_profile: strict
 ```
 
+### Test roots — write `test_paths:` explicitly
+
+Always write `test_paths:` with the test roots Phase 1 found, even
+when they are the conventional `spec/` or `test/`. Left unset, Rigor
+auto-detects whichever of `spec/` and `test/` exist; that covers the
+common layouts, but the committed config is then silent about where
+the tests are, and a suite anywhere else (a second tree, an
+`integration/` directory) is never read. Declaring the key replaces
+auto-detection, so list every root. A project with no tests yet
+writes `test_paths: []`.
+
+The key affects no diagnostic. Its reader today is `rigor sig-gen
+--params=observed` (Phase 5), which types a parameter from the
+arguments the tests pass. When there is no root to read, or a declared
+root does not exist, sig-gen says so on stderr and the affected
+parameters stay `untyped`.
+
 ### Key reference
 
 Only the keys this skill needs. `rigor --help` and the project
@@ -150,19 +174,20 @@ handbook document the full surface.
 | --- | --- |
 | `paths:` | Directories Rigor analyses. Source roots only — not `spec/` / `test/`. |
 | `exclude:` | Paths removed from the `paths:` walk. |
+| `test_paths:` | The project's test roots (`spec`, `test`, or several). Write it explicitly; see § "Test roots". Relative entries resolve against the config file. `rigor check` ignores it; `sig-gen` names a declared root that does not exist. |
 | `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. |
+| `baseline:` | Path to the baseline file. **Only acknowledge mode sets it**, and only in Phase 7 *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 6a may add it. |
+| `dependencies.source_inference:` | Opt-in inference for gems shipping no RBS. Leave empty at init; Phase 8 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
+or absent**. The baseline file does not exist until Phase 7, and a
+`baseline:` pointing at a missing file is an error. Phase 7 writes
 the file and uncomments / appends the line in one step.
 
 Strict mode never adds `baseline:` at all.
@@ -231,8 +256,8 @@ with the message text.
 
 ## Output of this module
 
-A committed `.rigor.dist.yml` with `paths:`, `exclude:`,
-`plugins:`, and `severity_profile:` set — and no active
+A committed `.rigor.dist.yml` with `paths:`, `test_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`.

data/skills/rigor-project-init/references/03-baseline-and-bugs.md

@@ -75,12 +75,12 @@ Use the 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-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). |
+| `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 6a — 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 6a — 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 6a — 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. |
+| `genuine-bugs` | Low-count rules scattered across files. | **Phase 8** — 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. |
 
 If triage flags `activesupport-core-ext` (or any config gap),
 **fix the config and re-run `rigor triage` before continuing**. The
@@ -170,8 +170,8 @@ 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.
+Re-run `rigor triage`. If the `gem-without-rbs` count drops, carry
+the new, smaller count into Phase 7.
 
 ## Phase 7 — Generate the baseline (acknowledge mode only)
 
@@ -215,7 +215,8 @@ So ordinary coding cannot quietly grow the diagnostic count: the
 baseline is a ceiling, not a blanket. Reducing it later is the
 `rigor-baseline-reduce` skill's job.
 
-Commit `.rigor-baseline.yml` — it documents project state.
+Recommend committing `.rigor-baseline.yml` — it documents project
+state; list it in the Final step's file inventory.
 
 Print the suppression summary for the user: "N diagnostics recorded
 as baseline; M will surface on subsequent runs."
@@ -288,18 +289,17 @@ 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:
+Rigor narrows `$1`, `$~`, and similar capture variables to non-nil
+after a successful `=~` match and inside a `when /re/` branch. Where
+the match is guaranteed by some other shape Rigor does not track, they
+stay `String | nil`, and a diagnostic 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.
+is an **engine FP** (ADR-24 WD3 / known limitation). Note it as noise rather than
+surfacing it as a bug; it belongs in the baseline.
 
 ### Escalation path A — application-specific metaprogramming
 

data/skills/rigor-project-init/references/04-sig-uplift.md

@@ -28,7 +28,8 @@ rigor sig-gen lib        # adjust path to match the paths: key
 Typical output at this point: most `new_method` candidates have
 literal or concrete return types (`"hello"`, `42`, `:done`, `nil`).
 Methods whose return type cannot be inferred show up with
-`skip_reason: :untyped_return` — these are the sig precision targets.
+`skip_reason: "sig.skipped.untyped-return"` — these are the sig
+precision targets.
 
 To get a breakdown in JSON:
 
@@ -50,6 +51,12 @@ rigor sig-gen --format json lib | ruby -e '
 
 ## Step 5-b — Write the baseline sigs
 
+If the project's `Steepfile` reads inline annotations (`inline: true`
+beside `signature "sig"`), first add `sig_gen:` / `inline_declared: skip`
+to `.rigor.yml`. Otherwise sig-gen copies every `# @rbs` / `#:`
+declaration into `sig/`, and Steep reports each copied method as
+`DuplicatedMethodDefinition`.
+
 ```sh
 rigor sig-gen --write lib
 ```
@@ -63,12 +70,18 @@ head -40 sig/lib/your_class.rbs
 
 At this point, `attr_reader` and `attr_accessor` methods that rely on
 ivar types set from `initialize` parameters will likely still be
-absent (classified as `:untyped_return`). Step 5-c fixes that.
+absent (skipped as `sig.skipped.untyped-return`). Step 5-c fixes that.
+An `attr_writer` or `attr_accessor` stays skipped even then unless its
+ivar is assigned from an `initialize` parameter: the writer stores
+whatever its caller passes, so the ivar reads untyped. That covers
+`@count = 0` and `@logger = Logger.new` alike, and any other method
+that returns the ivar.
 
 ## Step 5-c — Precision uplift with --params=observed
 
 `--params=observed` tells sig-gen to collect observed argument types
-from every call site it processes during the analysis pass. The most
+from the call sites in the project's test roots — the `test_paths:`
+Phase 4 wrote (`--observe=PATH` overrides them for one run). The most
 important use case: **`attr_reader` / `attr_writer` / `attr_accessor`
 methods whose `@ivar` is assigned from an `initialize` parameter**.
 
@@ -88,7 +101,8 @@ Person.new("Alice", 30)
 Person.new("Bob",   25)
 ```
 
-Without observations: `attr_reader :name` → skipped as `:untyped_return`
+Without observations: `attr_reader :name` → skipped as
+`sig.skipped.untyped-return`
 (the ivar's type is unknown because the blank inference scope never
 sees the parameter values).
 
@@ -129,9 +143,9 @@ there are a few options depending on the cause:
 | Pattern | Cause | Fix |
 |---|---|---|
 | `attr_reader :x` with `@x` never set in `initialize` | ivar set from a DB query, config read, or side effect | Add a hand-written sig: create (or edit) `sig/your_class.rbs` with `attr_reader x: String` |
-| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 7 escalation path B |
+| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 8 escalation path B |
 | Recursive or mutually recursive methods | Return type not inferrable without a base case | Add a `# @rbs return: YourType` inline annotation, or a hand-written sig |
-| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 7 escalation path A (project plugin) |
+| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 8 escalation path A (project plugin) |
 
 Do not spend long on residual `untyped` methods at this stage — a
 handful of `untyped` returns in `sig/` does not block adoption. The
@@ -140,12 +154,10 @@ reach perfect sig coverage.
 
 ## Step 5-e — Commit the sig/ directory
 
-Once you are satisfied with the initial sig quality:
-
-```sh
-git add sig/
-git commit -m "Add initial RBS sigs from rigor sig-gen (--params=observed)"
-```
+Once you are satisfied with the initial sig quality, recommend
+committing `sig/`: list it in the Final step's file inventory
+(`SKILL.md` § "Final step") rather than committing it here — the user
+confirms every commit.
 
 A committed `sig/` is a first-class project artefact: it improves
 inference quality on every subsequent run and is maintained alongside
@@ -164,8 +176,9 @@ the source (add new sig files when adding classes; update sigs with
 
 ## Output of this module
 
-A committed `sig/` directory with RBS skeletons for all statically
-inferrable methods. Remaining `:untyped_return` methods are noted for
+A `sig/` directory, ready to commit, with RBS skeletons for all
+statically inferrable methods. Remaining `sig.skipped.untyped-return`
+methods are noted for
 potential manual annotation; they do not block Phase 6.
 
 Proceed to Phase 6 ([`03-baseline-and-bugs.md`](03-baseline-and-bugs.md)).

data/skills/rigor-protection-uplift/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-protection-uplift
-description: |
-  Close the type-protection holes `rigor coverage --protection` surfaces: for each unprotected dispatch site, run `rigor sig-gen` first, hand-author only the minimal residual annotation, then verify with a double gate — the site becomes protected AND `rigor check` gains no new diagnostic. Triggers: "raise type protection", "add types where Rigor can't catch bugs", "act on coverage --protection / --mutation output", "make more of this code bug-catchable". NOT for Rigor's own `lib/` or the bundled plugins (use `rigor sig-gen` directly there and treat gaps as engine signal), and NOT for first-time setup (use rigor-project-init).
+description: >-
+  Close the protection gaps reported by `rigor coverage --protection`, using generated signatures before
+  minimal residual annotations and a no-new-diagnostics gate. Use when increasing bug-catching coverage
+  in an adopting project; not for Rigor's own tree, bundled plugins, or first-time setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -40,10 +42,6 @@ copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
 
 ## When NOT to use
 
-- **Rigor's own `lib/`, or the bundled `plugins/` / `examples/`** — the
-  self-check tree. Hand-authoring types there collides with the
-  sig-gen-first ethos; run `rigor sig-gen` directly and treat residual
-  gaps as engine signal to report, not a private fix.
 - **"Make my code more precise" with no protection goal** — that is
   `rigor coverage` (precision), not `--protection`.
 - **A project with no Rigor config yet** — onboard first with

data/skills/rigor-rbs-setup/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-rbs-setup
-description: |
-  Install community RBS for the project's gems with `rbs collection install`, so Rigor stops typing calls into RBS-less dependencies as `Dynamic` and gains real coverage (and real bug-catching) on them. Rigor auto-detects the resulting `rbs_collection.lock.yaml` — no Rigor config change needed. Triggers: "set up rbs collection", "my gems type as Dynamic", "rigor check says N gems have no RBS available", "reduce false positives from untyped gems". NOT for first-time Rigor setup (use rigor-project-init first) and NOT for a gem that has no entry in the community collection (that needs rigor-plugin-author or a Rigor issue).
+description: >-
+  Install community RBS for a project's gems so Rigor can type dependencies that currently become
+  `Dynamic`. Use when `rbs collection` is missing or untyped gems limit coverage; not for first-time
+  Rigor setup or a gem with no community RBS entry.
 license: MPL-2.0
 metadata:
   version: 0.1.0

data/skills/rigor-type-oracle/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-type-oracle
-description: |
-  Before writing or asserting ANY Ruby type, get it from Rigor rather than from reading the code: `rigor type-of FILE:LINE:COL` / `rigor annotate FILE` for an expression, `rigor sig-gen --print FILE` for a method signature, call-site observation for a parameter. A type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere. Triggers: writing RBS under `sig/`, an inline `#:` / `# @rbs` annotation, a Sorbet `sig do … end`, a YARD `@param` / `@return`, a type stated in a doc sentence or a review comment, a nil check / `is_a?` / `respond_to?` guard justified by "this should be an X", "add types to this class / file", "document this method", "what type is this / what does this return?". Applies to Rigor's own tree too. When Rigor answers `Dynamic[top]` or `untyped`, or `sig-gen` skips the method, report the gap — never fill it in from inference of your own. NOT for setting Rigor up (use rigor-next-steps) or working a baseline down (use rigor-baseline-reduce).
+description: >-
+  Obtain a Ruby type from Rigor before writing or asserting it, using `type-of`, `annotate`, or `sig-gen`
+  as appropriate. Use when adding RBS, inline annotations, Sorbet/YARD types, type-shaped docs, or
+  type-justified guards; not for Rigor setup or baseline reduction.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -59,10 +61,6 @@ scope the moment you are about to write or assert one:
 - Being asked "what type is this?", "what does this method return?",
   "add types to this class", "document this file".
 
-It applies to **Rigor's own tree** as well: `lib/`, the bundled plugins,
-and the examples are held to the same rule, and a gap found there is
-engine signal worth more than the annotation you would have written.
-
 ## When NOT to use
 
 - **Setting Rigor up on a project that has none** → `rigor-next-steps`

data/skills/rigor-type-oracle/references/01-oracle-commands.md

@@ -101,7 +101,7 @@ rigor sig-gen [paths]
 | `--overwrite` | Allow a tighter return to replace user-authored RBS. |
 | `--include-private` | Emit private / protected instance methods too (default: public only). |
 | `--params=untyped\|observed\|observed-strict` | Parameter policy. Default `untyped`. `observed-strict` is reserved and currently a usage error. |
-| `--observe=PATH` | Directory / file to scan for call-site observations. Repeatable. Defaults to `spec/` when present. |
+| `--observe=PATH` | Directory / file to scan for call-site observations. Repeatable. Defaults to the configured `test_paths:` (unset: whichever of `spec/` and `test/` exist). |
 | `--new-files` / `--new-methods` / `--tighter-returns` | Emit only that classification. |
 | `--format=text\|json` | Text RBS, or the structured candidate report. |
 | `--config=PATH` | Explicit `.rigor.yml`. |
@@ -133,8 +133,9 @@ skip is a finding. `--format=json` names each one:
   "classification": "skipped", "skip_reason": "sig.skipped.untyped-return" }
 ```
 
-Classifications: `new-file`, `new-method`, `tighter-return`, `equivalent`
-(nothing to tighten; silently dropped), `skipped`. Skip reasons and what
+Classifications (the JSON `classification` values): `new_file`,
+`new_method`, `tighter_return`, `equivalent` (nothing to tighten;
+silently dropped), `skipped`. Skip reasons and what
 each one means for you: [`03-gap-protocol.md`](03-gap-protocol.md).
 
 ### Deriving a parameter type from call sites
@@ -215,10 +216,11 @@ a family prefix (`call`, `flow`, `assert`, `dump`, `def`) it prints the
 rule's firing conditions, the severity per profile, the evidence tier,
 and how to suppress it.
 
-**`explain` covers diagnostic rules only.** A `sig.skipped.*` id is a
-sig-gen *skip reason*, not a diagnostic rule — `rigor explain
-sig.skipped.untyped-return` answers `Unknown rule`. Skip reasons are
-documented in [`03-gap-protocol.md`](03-gap-protocol.md).
+**`explain` has two catalogues.** A `sig.skipped.*` id is a sig-gen
+*skip reason*, not a diagnostic rule, but `rigor explain
+sig.skipped.untyped-return` answers it from a second catalogue (no
+severity, no profile, nothing to suppress). The table in
+[`03-gap-protocol.md`](03-gap-protocol.md) is the summary.
 
 ## `rigor check` — the gate, not the oracle
 
@@ -255,7 +257,9 @@ Two shape differences from the CLI worth knowing:
 - `rigor_sig_gen` returns the **JSON candidate report**, always — there
   is no `--print` text mode and no `--diff`. Read `rbs` per candidate.
 - `rigor_sig_gen` exposes `params` but **not** `observe`; observation
-  falls back to `spec/` when present. Point it elsewhere from the CLI.
+  reads the configured `test_paths:` (unset: whichever of `spec/` and
+  `test/` exist). To observe anything else, declare it in `test_paths:`
+  or use the CLI's `--observe`.
 
 `rigor_triage` and `rigor_coverage` are also served, and belong to
 `rigor-baseline-reduce` / `rigor-protection-uplift` rather than here.

data/skills/rigor-type-oracle/references/03-gap-protocol.md

@@ -123,6 +123,3 @@ more to the project than any annotation. File it at
 Also say `rigor --version`, and note whether `sig/` and the relevant
 plugins were in play — a gap that only appears without community RBS is a
 different bug from one that survives it.
-
-Inside Rigor's own tree the same report is the deliverable: the gap is
-the reason not to hand-write the RBS there.

data/skills/rigor-unused-adjudicate/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-unused-adjudicate
-description: |
-  Find dead code in a Ruby project with `rigor unused` — establish what the report can see on THIS project first, then adjudicate every row before proposing any deletion. Use this whenever someone asks to find or remove dead code, unused classes, unused constants, or "code nobody calls", whenever they ask what a `rigor unused` report means or which rows are safe to delete, and whenever a dead-code cleanup, codebase inventory, or legacy audit comes up — even if they never say "rigor". The report is a review queue and not a defect list; on an adjudicated corpus target only 4 of 57 rows were genuinely dead, so acting on it directly produces mostly wrong deletions. NOT for deleting a specific class you already know is dead, and NOT for `rigor check` diagnostics (those are ordinary type errors).
+description: >-
+  Adjudicate a `rigor unused` report safely before proposing dead-code removal. Use when interpreting or
+  reviewing Rigor's unused classes/modules/constants, or when a cleanup is based on that report; not for
+  a specific deletion already known to be safe or for ordinary `rigor check` diagnostics.
 license: MPL-2.0
 metadata:
   version: 0.2.0

data/skills/rigor-upgrade/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-upgrade
-description: |
-  Adopt a new Rigor version cleanly: after upgrading the `rigortype` gem, re-run the analysis, diff the diagnostics against the committed baseline, and sort the changes into genuine new catches (sharper inference), known sig-quality false positives, and the baseline you should regenerate. Triggers: "I upgraded Rigor, what changed?", "new diagnostics after gem update rigortype", "adopt the new Rigor version", "rigor baseline drifted after upgrade". NOT for first-time setup (use rigor-project-init) or routine baseline work unrelated to an upgrade (use rigor-baseline-reduce).
+description: >-
+  Adopt a new `rigortype` version by comparing its diagnostics with the committed baseline and separating
+  new catches from signature-quality false positives. Use after a Rigor gem upgrade; not for first-time
+  setup or routine baseline reduction.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -50,12 +52,15 @@ rigor --version
 ### Phase 2 — see the delta against the committed baseline
 
 ```sh
-rigor check
-rigor diff            # compare current diagnostics to the saved baseline JSON
+rigor check             # everything outside the committed baseline's envelope
+rigor baseline drift    # per-bucket movement against .rigor-baseline.yml
 ```
 
-`rigor diff` shows what is **new** relative to the baseline — that set is
-what the upgrade changed.
+With `baseline:` wired, `rigor check` already hides what the baseline
+covers, so what it prints is **new** relative to the baseline — that set
+is what the upgrade changed. `rigor baseline drift` adds the bucket view:
+buckets now over their recorded count, and buckets the new version
+cleared or shrank.
 
 ### Phase 3 — sort the new diagnostics
 
@@ -80,8 +85,8 @@ envelope so the regeneration does not bury what you just fixed:
 rigor baseline regenerate
 ```
 
-Commit the updated `.rigor-baseline.yml` together with any fixes, so the
-team adopts the same post-upgrade baseline.
+Recommend committing the updated `.rigor-baseline.yml` together with any
+fixes, so the team adopts the same post-upgrade baseline.
 
 ## Note