rigortype 0.3.8 → 0.4.0

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

@@ -1,7 +1,8 @@
 ---
 name: rigor-mcp-setup
-description: |
-  Wire Rigor's bundled MCP server (`rigor mcp`) into an AI coding agent (Claude Code, Claude Desktop, Cursor, Cline) so the agent can call Rigor's read-only analysis tools — rigor_check, rigor_type_of, rigor_triage, rigor_coverage, and more — during a session. The per-client config lives in the manual; this skill identifies the client, applies the right one, and verifies the handshake. Triggers: "set up rigor mcp", "give my AI agent Rigor tools", "wire Rigor into Claude Code / Cursor / Cline", "rigor MCP server". NOT for editor LSP integration (use rigor-editor-setup) or CI (use rigor-ci-setup).
+description: >-
+  Set up Rigor's bundled MCP server for an AI coding agent and verify the connection. Use when wiring
+  `rigor mcp` into Claude Code, Cursor, Cline, or another MCP client; not for editor LSP or CI setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -26,7 +27,7 @@ rigor docs mcp-server
 ```
 
 (Web fallback, only before Rigor is installed:
-**[Rigor MCP Server — AI Agent Integration](../../docs/manual/10-mcp-server.md)**.)
+**[Rigor MCP Server — AI Agent Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/10-mcp-server.md)**.)
 This skill is the *workflow* around it (identify the client → apply the
 manual's snippet → verify the handshake), so it does not duplicate (and
 cannot stale-out) the config details.
@@ -70,7 +71,7 @@ Every client config simply launches **`rigor mcp`** (stdio) and needs
 **`rigor` on the agent's `PATH`** — the same executable `rigor check`
 uses. For agents that do not inherit your shell, the `mise` shim path is
 the most reliable channel (see `rigor docs install`, or
-[Installing Rigor](../../docs/install.md)
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
 on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
 is a tool, not a library.
 

data/skills/rigor-monkeypatch-resolve/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-monkeypatch-resolve
-description: |
-  Resolve a cluster of `call.unresolved-toplevel` / `call.undefined-method` diagnostics that are really the project's own monkey-patches (core-extension files that add methods with literal `def`) by wiring them into `pre_eval:` so Rigor pre-evaluates them and learns the added methods. Triggers: "Rigor flags methods my core-ext adds", "undefined-method on my own monkey-patch", "set up pre_eval", "lots of unresolved-toplevel from my lib/core_ext". NOT for dynamically-generated methods (define_method / method_missing / class_eval heredocs) — those need a plugin (use rigor-plugin-author) — and NOT for an external gem with no RBS (use rigor-rbs-setup).
+description: >-
+  Resolve Rigor diagnostics caused by literal `def` methods in a project's own monkey-patches by wiring
+  their files into `pre_eval:`. Use when project core extensions cause undefined-method findings; not for
+  dynamic method generation or an external gem without RBS.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -14,7 +16,7 @@ When a project adds methods to existing classes in its own files — the
 classic `lib/core_ext/*.rb` `class String; def squish; …; end` pattern —
 Rigor does not see them unless told to, so every call to the added method
 fires `call.undefined-method` (or `call.unresolved-toplevel` for a
-top-level helper). `pre_eval:` ([ADR-17](../../docs/adr/17-monkey-patch-pre-evaluation.md))
+top-level helper). `pre_eval:` ([ADR-17](https://github.com/rigortype/rigor/blob/master/docs/adr/17-monkey-patch-pre-evaluation.md))
 fixes this: it pre-evaluates the listed project files and registers every
 method they define with a **literal** `def` / `def self.`.
 

data/skills/rigor-next-steps/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-next-steps
-description: |
-  Route a project to its next Rigor step from a single entry point: resolve the `rigor` command (install it if missing), onboard the project if it has no Rigor config, then ask `rigor skill describe` what to do next and hand off to the matching skill. Triggers: "what should we do next with Rigor?", "I want to use Rigor on this project", "help me move this project forward with Rigor", "where do I start with Rigor?". NOT a replacement for the task-specific skills it routes to — it hands off to them.
+description: >-
+  Route a project to its next Rigor step, installing or onboarding Rigor when needed and then delegating
+  to `rigor skill describe`. Use when the user asks where to start or what to do next with Rigor; not
+  instead of a task-specific skill the route selects.
 license: MPL-2.0
 metadata:
   version: 0.1.0

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-plugin-author
-description: |
-  Author a Rigor plugin in your own repository — a standalone rigor-prefixed gem or a project-private plugin — to teach Rigor about an application DSL, framework, or metaprogramming pattern. Covers gemspec / Gemfile wiring, the plugin class and AST walker, return-type contributions, fixture-based testing (RSpec or Minitest), and version pinning against the pre-1.0 plugin contract. Triggers: "write a Rigor plugin for our DSL", "extend Rigor for X in this project", "make Rigor understand our macro". NOT for onboarding a project (use rigor-project-init) or reducing a baseline (use rigor-baseline-reduce).
+description: >-
+  Author a Rigor plugin in an adopting project or standalone `rigor-*` gem for a DSL, framework, or
+  metaprogramming pattern. Use when Rigor needs project-specific extension support; not for onboarding a
+  project, reducing a baseline, or editing Rigor's bundled plugins.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -43,21 +45,20 @@ If you already loaded this skill *via* `rigor skill` you have the current
 copy — just proceed. If the `rigor` command is not available, run
 **`rigor-next-steps`** to install Rigor first, then come back.
 
-## Important — the plugin contract is a preview (pre-1.0)
+## The plugin contract is pre-1.0
 
-Rigor's plugin contract (ADR-2) is **not yet frozen**. It stabilises
-at `rigortype` v0.2.0. Until then, treat each `rigortype` minor
-release as potentially contract-changing:
+Rigor's plugin contract (ADR-2) freezes at `rigortype` v1.0.0. Until
+then, treat each `rigortype` minor release as potentially
+contract-changing:
 
-- **Pin `rigortype` tightly** — `>= 0.1.0, < 0.2.0` in your gemspec
-  or Gemfile. Do not float across the v0.2.0 boundary blind.
-- Expect to **revisit your plugin** when you bump `rigortype` to the
-  next minor. The walker hook signature, the `Diagnostic` shape, and
-  the type carriers may shift.
-- After v0.2.0 the contract is stable and ordinary semver applies.
+- **Pin `rigortype` to the minor you built against** — `"~> X.Y.0"`
+  in your gemspec or Gemfile, where `X.Y` comes from `rigor --version`.
+- Expect to **revisit your plugin** when you move to the next minor.
+  The node-rule block signature, the `Diagnostic` shape, and the type
+  carriers may shift.
 
-Tell the user this up front. A plugin written today is a preview
-artefact, valuable but not yet on a stable foundation.
+Tell the user this up front: a plugin written today is valuable but
+not yet on a frozen foundation.
 
 ## Read a real plugin — `rigor plugin`
 
@@ -114,14 +115,9 @@ AST walk per file — hands every matching node to the block along with a
 `Rigor::Analysis::Diagnostic` (built via the `diagnostic` helper).
 Optionally the plugin also declares `dynamic_return(receivers:)` /
 `narrowing_facts(methods:)` to *supply* a return type or narrowing facts
-for call sites the core analyzer types as `Dynamic`. (`narrowing_facts`
-was renamed from `type_specifier` in ADR-80; the old verb was removed in
-0.3.0, so `narrowing_facts` is the only spelling.)
-`#diagnostics_for_file`
-is the file-rule surface for whole-file diagnostics a per-node walk can't
-express. (`flow_contribution_for` was removed pre-1.0 in ADR-52 WD3 —
-defining it now raises `ArgumentError`; use `dynamic_return` /
-`narrowing_facts`. See Phase 2.)
+for call sites the core analyzer types as `Dynamic`.
+`#diagnostics_for_file` is the file-rule surface for whole-file
+diagnostics a per-node walk can't express. See Phase 2.
 
 ## Phase outline
 
@@ -136,5 +132,5 @@ defining it now raises `ArgumentError`; use `dynamic_return` /
 | Module | Read | Covers |
 | --- | --- | --- |
 | 1 | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) | **Phase 1.** The gem vs project-private packaging split, directory trees for both, gemspec template, project-private path-gem / `RUBYLIB` activation, the `Rigor::Plugin::Base` skeleton, `.rigor.yml` `plugins:` wiring. |
-| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `node_rule` engine-owned AST walk over Prism nodes, the `Base#diagnostic` helper, asking the analyzer for inferred types via `scope.type_of`, two-pass / lexical context (`node_file_context` / `NodeContext`), the optional `dynamic_return` / `narrowing_facts` return-type hooks (`narrowing_facts` was renamed from `type_specifier` in ADR-80, the alias removed in 0.3.0; `flow_contribution_for` was removed pre-1.0 in ADR-52 WD3), calling the target library's pure methods directly rather than reimplementing them (ADR-39: `Plugin::Inflector` over the real `ActiveSupport::Inflector`; `Base.suggest` for did-you-mean), and shipping `sig/*.rbs` so the DSL's types are visible. |
+| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `node_rule` engine-owned AST walk over Prism nodes, the `Base#diagnostic` helper, asking the analyzer for inferred types via `scope.type_of`, two-pass / lexical context (`node_file_context` / `NodeContext`), the optional `dynamic_return` / `narrowing_facts` return-type hooks, calling the target library's pure methods directly rather than reimplementing them (ADR-39: `Plugin::Inflector` over the real `ActiveSupport::Inflector`; `Base.suggest` for did-you-mean), and shipping `sig/*.rbs` so the DSL's types are visible. |
 | 3 | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) | **Phase 3.** Testing a plugin from outside the monorepo — fixture projects driven through `rigor check --format json`, plus pure unit tests of dispatch tables — with RSpec or Minitest. Version pinning against the pre-1.0 contract. README. Publishing to RubyGems or keeping the plugin private. |

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

@@ -52,8 +52,9 @@ Gem::Specification.new do |spec|
   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"
+  # Pin to the minor you built against — the contract is pre-1.0
+  # (see SKILL.md). X.Y comes from `rigor --version`.
+  spec.add_dependency "rigortype", "~> X.Y.0"
 end
 ```
 
@@ -131,7 +132,7 @@ your-app/
 
 ```ruby
 # your-app/Gemfile
-gem "rigortype", "~> 0.1.0"
+gem "rigortype", "~> X.Y.0"   # the minor you built against
 gem "rigor-myapp", path: "rigor-plugin"
 ```
 
@@ -172,16 +173,16 @@ module Rigor
         # Optional: declare config keys the user may set under
         # `.rigor.yml` plugins: [{ gem:, config: { … } }].
         config_schema: {
-          # "module_name" => :string,
-          # "rules"       => :array,
+          "module_name" => { kind: :string, default: "Default" }
+          # "rules"     => :array,
         }
       )
 
       # Called once at load time with the service container.
-      # Read config defaults here. `config` is the validated
-      # user config Hash.
+      # `config` is the validated user config Hash, with declared
+      # defaults merged beneath it.
       def init(_services)
-        @module_name = config.fetch("module_name", "Default")
+        @module_name = config["module_name"]
       end
 
       # The engine owns the AST walk and hands every matching node to

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

@@ -152,8 +152,9 @@ For your own target library, follow the same harness: a **fixed
 allow-list** of pure methods, inputs derived from source, and **decline
 (return nil / emit nothing) when the library is unavailable — never
 approximate**. How the call is isolated from Rigor (in-process, a forked
-worker, or a `Ruby::Box`) is a configurable strategy the user picks
-(`plugins_isolation:`); you just call the method.
+worker, or a `Ruby::Box`) is a configurable strategy the user picks with
+`.rigor.yml`'s `plugins_isolation:` key or the `RIGOR_PLUGIN_ISOLATION`
+environment variable (which wins over it); you just call the method.
 
 For the common "did you mean …?" suggestion, use the shared helper
 rather than hand-rolling Levenshtein:
@@ -164,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
@@ -194,6 +189,16 @@ dynamic_return receivers: ["Money"] do |call_node, scope|
   Rigor::Type::Combinator.nominal_of("Money")
 end
 
+# A `receivers:` entry names the receiver KIND too. `"Money"` matches an
+# INSTANCE receiver; the class object itself is `"singleton(Money)"`,
+# spelled as RBS spells it; a rule for both lists both. Write the kind
+# the rule actually models: a plugin answer suppresses that call site's
+# `call.undefined-method`, so an instance rule that also answered on the
+# class would silence a genuine miss on the class-level call.
+dynamic_return receivers: ["singleton(Money)"], methods: [:from_cents] do |call_node, scope|
+  Rigor::Type::Combinator.nominal_of("Money")
+end
+
 # Post-return NARROWING FACTS, gated on the call's method name.
 # Return an Array of facts (or nil). Used for assertion / predicate
 # narrowing (`assert_kind_of(Foo, x)` ⇒ x is Foo afterwards).
@@ -202,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
@@ -222,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: -> { [...] }`,
@@ -236,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) |
@@ -135,6 +137,7 @@ mode — those points resolve without blocking:
 | 6a | **Pre-baseline cleanup** — apply quick fixes that triage diagnosed (`pre_eval:` for monkey-patch hints, `rbs collection install` if still needed). Re-run triage; repeat until the count is stable. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) § "Phase 6a" |
 | 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; distinguish sig quality FPs from real bugs; offer escalation paths. | [`references/03-baseline-and-bugs.md`](references/03-baseline-and-bugs.md) |
+| 8a | Install the agent type-contract into `AGENTS.md` / `CLAUDE.md`, so an AI contributor sources types from Rigor instead of guessing them. | [`references/06-agent-contract.md`](references/06-agent-contract.md) |
 | 9 | Confirm the generated files with the user — what each is, and whether to commit it. | (this file — § "Final step") |
 
 Load each reference when you reach its phase. Phases run in order;
@@ -150,9 +153,10 @@ committed `sig/` directory.
 | 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. Phase 6a pre-baseline cleanup loop (`pre_eval:` for monkey-patch hints, `rbs collection install`). `rigor baseline generate` + wiring `baseline:`. Surfacing likely real bugs; sig quality FP recognition (Struct `call.wrong-arity`, `-> bot` return-type-mismatch, regex-capture `$1` FPs). The two escalation paths — write a project plugin, or open a Rigor issue. |
+| 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:
@@ -181,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)
@@ -221,16 +225,17 @@ 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`. |
 | `.rigor.yml` | Optional per-developer local override (not written by this skill). Takes precedence over `.rigor.dist.yml`; used to opt out locally (e.g. run without the baseline). | **No** — gitignore it if a developer creates one. |
 | `rbs_collection.lock.yaml` | Not a Rigor artefact — but if Phase 1 ran `rbs collection install`, the install may have regenerated this pre-existing project file (e.g. the stdlib gem list for the resolved Ruby). | **Yes**, but flag it separately: it is a change to an existing project file, not part of the Rigor file set. |
+| `AGENTS.md` / `CLAUDE.md` | The agent type-contract section added in Phase 8a — "a type you did not obtain from Rigor is a guess". Created only if neither file existed; otherwise this is an appended section in a pre-existing file. | **Yes** — commit it; the point is that every contributor's agent reads the same rule. Flag an appended section separately, as with `rbs_collection.lock.yaml`. |
 
 Recommend the two concrete actions and **ask before doing them**
 (both touch the user's repo): (1) add `.rigor/` — and `.rigor.yml`
 if present — to `.gitignore`; (2) commit `.rigor.dist.yml`,
-`.rigor-baseline.yml`, and `sig/` as the shared Rigor setup. Per the
-git-safety default, do not commit on the user's behalf until they
-confirm.
+`.rigor-baseline.yml`, `sig/`, and the Phase 8a `AGENTS.md` /
+`CLAUDE.md` section as the shared Rigor setup. Per the git-safety
+default, do not commit on the user's behalf until they confirm.

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,17 +112,18 @@ 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
 ```
 
 ### Existing `sig/` directory
 
-If the project already has a `sig/` directory (from Steep, `rbs_rails`,
-or handwritten annotations), wire it into `signature_paths:` so Rigor
-consumes it. Phase 5 (sig uplift) can be skipped, but the paths must
-still be declared — Rigor does not auto-detect `sig/`:
+A plain `<project root>/sig` directory needs no wiring: with
+`signature_paths:` unset, Rigor auto-detects it and loads it recursively.
+Phase 5 (sig uplift) can be skipped. Declare `signature_paths:` when the
+layout is something else — several trees, or a `sig/` that is not at the
+project root:
 
 ```yaml
 signature_paths:
@@ -125,18 +131,40 @@ signature_paths:
   - sig/generated
 ```
 
+Declaring the key REPLACES the auto-detected `sig`, so list it too if you
+want it. `signature_paths: []` is the way to opt out of project RBS
+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. If the sig layout is a single
-flat `sig/` directory, use `- sig` instead.
+them. Rigor walks each path recursively.
 
 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
@@ -146,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.
@@ -227,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`.