rigortype 0.3.9 → 0.4.1

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

@@ -165,20 +165,14 @@ Rigor::Plugin::Base.suggest(typo, known_names)  # nearest match, or nil
 
 ## Optional — contribute a return type with `dynamic_return` / `narrowing_facts`
 
-> **Critical — these hooks do NOT make a method "defined", so they do
-> NOT suppress `call.undefined-method`.** Method *existence* and call
-> *type* are two independent checks. A return-type contribution sharpens
-> the type of a call the analyzer has **already resolved to a real
-> method** (turning a `Dynamic` return into something precise). It is
-> never consulted for a receiver/method the analyzer cannot find — that
-> fires `call.undefined-method` first, and a contribution does nothing
-> to silence it. **If your goal is to kill a `call.undefined-method`
-> cluster on a DSL-generated method (the common reason
-> `rigor-project-init` hands off to this skill), the fix is to make the
-> method *exist* in Rigor's view — ship RBS declaring it (see "Shipping
-> RBS for the DSL" below), not a return-type contribution.** Reach for
-> these only when the call already resolves and you want a *better
-> return type*.
+> **Prefer RBS to make a DSL method exist.** A `dynamic_return` answer
+> suppresses `call.undefined-method` only at the call sites where the
+> rule fires (its gated receiver kind and methods); RBS makes the method
+> defined for all of core inference — arity, argument types, every call
+> site. To clear a `call.undefined-method` cluster on DSL-generated
+> methods (the common reason `rigor-project-init` hands off to this
+> skill), ship RBS (see "Shipping RBS for the DSL" below). Reach for
+> these hooks when you want a better *return type* for a call.
 
 A plugin can do more than emit diagnostics: it can *supply* the
 inferred return type (or narrowing facts) for a call site the core
@@ -213,10 +207,6 @@ narrowing_facts methods: [:assert_kind_of] do |call_node, scope|
 end
 ```
 
-> **`narrowing_facts` was renamed from `type_specifier` in ADR-80.**
-> The old verb was removed in 0.3.0 — `narrowing_facts` is the only
-> spelling a plugin can declare.
-
 Build return types with `Rigor::Type::Combinator`:
 
 ```ruby
@@ -233,12 +223,9 @@ plugin is confident; a wrong contribution propagates downstream.
 `rigor plugins --capabilities` catalogue enumerates — run it to see
 exactly what each loaded plugin contributes.
 
-> **The removed fat hook.** The original `flow_contribution_for(call_node:,
-> scope:)` was **deleted pre-1.0 in ADR-52 WD3** — defining it now raises
-> `ArgumentError` at load time. The two shapes it used to cover are
-> expressed by `dynamic_return`'s callable gates: a **method-gated return
-> type** (an RSpec `let(:x) { … }` binding, a Sorbet `sig`-driven return —
-> keyed on the method, not a fixed receiver class) uses
+> **Callable gates.** A **method-gated return type** (an RSpec
+> `let(:x) { … }` binding, a Sorbet `sig`-driven return — keyed on the
+> method, not a fixed receiver class) uses
 > `dynamic_return methods: -> { [...] }` or `file_methods: ->(path) { [...] }`;
 > a **dynamic per-project receiver set** (ActiveStorage's `Attached::One`
 > on discovered model classes) uses `dynamic_return receivers: -> { [...] }`,
@@ -247,7 +234,7 @@ exactly what each loaded plugin contributes.
 > if the plugin genuinely needs to sharpen call-site types; a
 > diagnostics-only plugin skips them entirely.
 
-## Shipping RBS for the DSL — the way to suppress `call.undefined-method`
+## Shipping RBS for the DSL — making DSL methods exist
 
 If the DSL introduces methods or classes that Rigor cannot see (a
 `Money` class defined by metaprogramming, `Setting.<name>` accessors a

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

@@ -106,11 +106,12 @@ 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
+The plugin contract is **not frozen until `rigortype` v1.0.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.
+- Gemspec / Gemfile: `rigortype` `~> X.Y.0` for the minor you tested
+  (`rigor --version`). Never an open `>=` range — that floats across
+  contract-changing minors.
 - 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
@@ -120,9 +121,6 @@ SKILL.md). Concretely:
 - 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:
@@ -151,13 +149,13 @@ 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.
+authors are the main source of contract feedback before v1.0.
 
 ## 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 `rigortype` pin tight to the tested minor.
 - A README stating the compatibility range.
 - The plugin published as a gem, or committed project-private with
   CI wired.

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) |
@@ -86,7 +88,7 @@ diagnostics.
 | 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. |
+| Best for | **Every project by default** — mature or brand-new, large or small. | Users fluent in both type theory and RBS who opt in and will resolve Rigor's inference gaps themselves. |
 | 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
@@ -95,12 +97,35 @@ 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.
-
-Note the ordering: the error count that feeds this recommendation (and
-the `severity_profile` choice in Phase 4) is only *measured* in
+**Recommend acknowledge mode for every project, including new and
+small ones.** Rigor's inference still has gaps, so even a fresh
+project meets diagnostics on correct code. Under strict mode each one
+needs a `sig/` fix, an RBS workaround, or a reasoned
+`# rigor:disable` — work that takes type theory and RBS. Without that
+knowledge, users rewrite correct code for the tool or scatter
+suppressions. Acknowledge mode keeps the same regression guard with an
+exit: a new diagnostic still fails the check, and once it is confirmed
+as an inference gap, the baseline can absorb it (report the false
+positive upstream). `rigor baseline regenerate` rewrites the baseline
+from every live diagnostic, so run it only when a whole-project
+`rigor check` (no path arguments) shows nothing but confirmed false
+positives; otherwise it silences a real
+bug alongside them.
+
+Present strict mode as an opt-in for users who know type theory and
+RBS, want the zero-diagnostic gate, and accept resolving inference
+gaps themselves — never as the recommendation, and never because the
+project is new, small, or a library. If the user picks it, tell them
+how to move to acknowledge mode later: optionally relax
+`severity_profile`, re-run triage, then run Phase 7 (generate a
+baseline and wire `baseline:`). The profile change comes first because
+it changes which rules fire.
+
+For a large first run (more than ~100 errors), acknowledge mode also
+suggests `severity_profile: lenient`; see Phase 4.
+
+Note the ordering: the error count that feeds the `severity_profile`
+choice in Phase 4 is only *measured* in
 Phase 6's triage run. Any profile written in Phase 4 is therefore
 **provisional** — Phase 6 revisits it against the measured count (see
 [`references/02-configure.md`](references/02-configure.md)
@@ -109,12 +134,15 @@ Phase 6's triage run. Any profile written in Phase 4 is therefore
 ## Non-interactive / agent-driven runs
 
 This skill has several ask-the-user points (the mode choice, the RBS
-collection install, the final gitignore-and-commit confirmation). When
-the user delegated the onboarding up front — including the adoption
-mode — those points resolve without blocking:
+collection install, the final gitignore-and-commit confirmation). A
+*delegation* is the user asking, before the run, for the onboarding to
+proceed without these questions ("set it up, don't ask me"). An
+ordinary request to set Rigor up is not one: ask as usual. Under a
+delegation those points resolve without blocking:
 
 - The **mode** the user pre-declared is settled; record it and skip the
-  Phase 2 presentation.
+  Phase 2 presentation. If the delegation names no mode, choose
+  acknowledge mode and say so in the report — never strict.
 - Low-risk, reversible, in-repo confirmations (`rbs collection
   install`, the `.gitignore` addition) are covered by the delegation —
   act, and note each self-answer in your report.
@@ -154,7 +182,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 +211,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 +251,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
 ```
@@ -133,14 +138,38 @@ entirely — including a `sig/` that `rigor sig-gen --write` created.
 List only directories that contain `.rbs` files or subdirectories of
 them. Rigor walks each path recursively.
 
-A strict-mode plain-Ruby gem is shorter:
+A plain-Ruby gem is shorter. The `balanced` default needs no
+`severity_profile:` key:
 
 ```yaml
 paths:
   - lib
-severity_profile: strict
+test_paths:
+  - test
+
+# Phase 7 (acknowledge mode) appends this line after generating the
+# baseline. Strict mode (opt-in) sets `severity_profile: strict` and
+# leaves it out.
+# baseline: .rigor-baseline.yml
 ```
 
+### 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 +179,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 +261,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