rigortype 0.2.9 → 0.3.1

data/sig/rigor/inference.rbs

@@ -3,8 +3,10 @@ module Rigor
     type closure_classification = :non_escaping | :escaping | :unknown
 
     class ExpressionTyper
+      def self.harvest_return_memo: () -> Hash[untyped, Array[untyped]]
       def initialize: (scope: Scope, ?tracer: FallbackTracer?) -> void
       def type_of: (untyped node) -> Type::t
+      def return_type_for: (untyped def_node, Type::t receiver, Array[Type::t] arg_types) -> Type::t?
       def scope: () -> Scope
       def tracer: () -> FallbackTracer?
       def dynamic_top: () -> Type::Dynamic
@@ -27,6 +29,7 @@ module Rigor
 
       def initialize: (scope: Scope, ?tracer: FallbackTracer?, ?on_enter: (^(untyped, Scope) -> void)?, ?class_context: Array[ClassFrame]) -> void
       def evaluate: (untyped node) -> [Type::t, Scope]
+      def content_mutated_parameter_positions: (untyped def_node) -> Array[Integer]
       def scope: () -> Scope
       def tracer: () -> FallbackTracer?
       def sub_eval: (untyped node, Scope with_scope, ?class_context: Array[ClassFrame]) -> [Type::t, Scope]
@@ -163,6 +166,10 @@ module Rigor
       def self?.record_declarations: (untyped node, Array[String] qualified_prefix, Hash[untyped, Type::t] identity_table, Hash[String, Type::t] discovered) -> void
       def self?.discovered_classes_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[String, Type::t]
       def self?.discovered_def_index_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.scan_summary_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.code_fingerprint: (String source, untyped comments) -> String
+      def self?.discovered_project_index_for_paths: (Array[String] paths, ?buffer: untyped) -> Hash[Symbol, untyped]
+      def self?.discovered_project_index_incremental: (Array[String] paths, seed_bundles: Hash[String, untyped], ?buffer: untyped) -> Hash[Symbol, untyped]
       def self?.collect_class_decls: (untyped node, Array[String] qualified_prefix, Hash[String, Type::t] accumulator) -> void
       def self?.qualified_name_for: (untyped constant_path_node) -> String?
       def self?.render_constant_path: (untyped node) -> String

data/sig/rigor/plugin/base.rbs

@@ -14,7 +14,7 @@ class Rigor::Plugin::Base
   # the no-arg `manifest` reads the cached value back.
   def self.manifest: (**untyped fields) -> Rigor::Plugin::Manifest
 
-  def self.producer: (untyped id, ?watch: untyped, ?serialize: untyped, ?deserialize: untyped) { (untyped params) -> untyped } -> Symbol
+  def self.producer: (untyped id, ?watch: untyped, ?serialize: untyped, ?deserialize: untyped, ?generation_cap: untyped) { (untyped params) -> untyped } -> Symbol
   def self.producers: () -> Hash[Symbol, untyped]
 
   def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> untyped
@@ -23,13 +23,13 @@ class Rigor::Plugin::Base
   def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> untyped
   def self.node_file_context_block: () -> untyped
 
-  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?) { (untyped call_node, untyped scope) -> untyped } -> nil
+  def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(untyped path) -> Array[untyped])?) { (untyped call_node, untyped scope) -> untyped } -> nil
   def self.dynamic_returns: () -> Array[untyped]
 
   def self.narrowing_facts: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
-  # Deprecating alias for `narrowing_facts` (ADR-80); removed in 0.3.0.
-  def self.type_specifier: (methods: Array[untyped]) { (untyped call_node, untyped scope) -> untyped } -> nil
-  def self.type_specifiers: () -> Array[untyped]
+  # The engine-facing reader for the declared `narrowing_facts` rules. Named
+  # `type_specifiers` before ADR-80; that spelling was removed in 0.3.0.
+  def self.narrowing_facts_rules: () -> Array[untyped]
 
   def self.suggest: (untyped name, untyped candidates) -> String?
 
@@ -48,7 +48,7 @@ class Rigor::Plugin::Base
   # Engine-executed dispatch over the declared DSLs.
   def node_rule_diagnostics: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
   def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> untyped
-  def type_specifier_facts: (call_node: untyped, scope: untyped) -> Array[untyped]
+  def narrowing_facts_for: (call_node: untyped, scope: untyped) -> Array[untyped]
 
   # Authoring helpers.
   def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> untyped

data/sig/rigor/reflection.rbs

@@ -6,6 +6,7 @@ module Rigor
     def self?.nominal_for_name: (String | Symbol class_name, ?scope: Scope) -> Type::Nominal?
     def self?.singleton_for_name: (String | Symbol class_name, ?scope: Scope) -> Type::Singleton?
     def self?.constant_type_for: (String | Symbol constant_name, ?scope: Scope) -> Type::t?
+    def self?.resolve_constant_type: (String | Symbol name, ?scope: Scope) -> Type::t?
     def self?.instance_method_definition: (String | Symbol class_name, String | Symbol method_name, ?scope: Scope) -> untyped
     def self?.singleton_method_definition: (String | Symbol class_name, String | Symbol method_name, ?scope: Scope) -> untyped
     def self?.instance_definition: (String | Symbol class_name, ?scope: Scope) -> untyped

data/sig/rigor/scope.rbs

@@ -11,6 +11,7 @@ module Rigor
     attr_reader dynamic_origins: Hash[untyped, Symbol]
     attr_reader local_origins: Hash[Symbol, Symbol]
     attr_reader ivar_origins: Hash[Symbol, Symbol]
+    attr_reader void_origins: Hash[untyped, Inference::VoidOrigin]
     attr_reader indexed_narrowings: Hash[IndexedKey, Type::t]
     attr_reader method_chain_narrowings: Hash[ChainKey, Type::t]
     attr_reader source_path: String?
@@ -28,6 +29,7 @@ module Rigor
     def discovered_def_nodes: () -> Hash[String, Hash[Symbol, untyped]]
     def discovered_singleton_def_nodes: () -> Hash[String, Hash[Symbol, untyped]]
     def discovered_def_sources: () -> Hash[String, Hash[Symbol, String]]
+    def discovered_singleton_def_sources: () -> Hash[String, Hash[Symbol, String]]
     def discovered_method_visibilities: () -> Hash[String, Hash[Symbol, Symbol]]
     def discovered_superclasses: () -> Hash[String, String]
     def discovered_includes: () -> Hash[String, Array[String]]
@@ -35,8 +37,11 @@ module Rigor
     def data_member_layouts: () -> Hash[String, Array[Symbol]]
     def struct_member_layouts: () -> Hash[String, { members: Array[Symbol], keyword_init: bool }]
     def param_inferred_types: () -> Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+    def run_generation: () -> Object?
     def record_dynamic_origin: (untyped node, Symbol cause) -> Scope
 
+    def record_void_origin: (untyped node, Inference::VoidOrigin origin) -> Scope
+
     class DiscoveryIndex
       attr_reader declared_types: Hash[untyped, Type::t]
       attr_reader class_ivars: Hash[String, Hash[Symbol, Type::t]]
@@ -48,6 +53,7 @@ module Rigor
       attr_reader discovered_def_nodes: Hash[String, Hash[Symbol, untyped]]
       attr_reader discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]]
       attr_reader discovered_def_sources: Hash[String, Hash[Symbol, String]]
+      attr_reader discovered_singleton_def_sources: Hash[String, Hash[Symbol, String]]
       attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
       attr_reader discovered_superclasses: Hash[String, String]
       attr_reader discovered_includes: Hash[String, Array[String]]
@@ -55,10 +61,11 @@ module Rigor
       attr_reader data_member_layouts: Hash[String, Array[Symbol]]
       attr_reader struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }]
       attr_reader param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]
+      attr_reader run_generation: Object?
 
       EMPTY: DiscoveryIndex
 
-      def with: (?declared_types: Hash[untyped, Type::t], ?class_ivars: Hash[String, Hash[Symbol, Type::t]], ?class_cvars: Hash[String, Hash[Symbol, Type::t]], ?program_globals: Hash[Symbol, Type::t], ?discovered_classes: Hash[String, Type::Singleton], ?in_source_constants: Hash[String, Type::t], ?discovered_methods: Hash[String, Hash[Symbol, Symbol]], ?discovered_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]], ?discovered_superclasses: Hash[String, String], ?discovered_includes: Hash[String, Array[String]], ?discovered_class_sources: Hash[String, Set[String]], ?data_member_layouts: Hash[String, Array[Symbol]], ?struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }], ?param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]]) -> DiscoveryIndex
+      def with: (?declared_types: Hash[untyped, Type::t], ?class_ivars: Hash[String, Hash[Symbol, Type::t]], ?class_cvars: Hash[String, Hash[Symbol, Type::t]], ?program_globals: Hash[Symbol, Type::t], ?discovered_classes: Hash[String, Type::Singleton], ?in_source_constants: Hash[String, Type::t], ?discovered_methods: Hash[String, Hash[Symbol, Symbol]], ?discovered_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_singleton_def_nodes: Hash[String, Hash[Symbol, untyped]], ?discovered_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_singleton_def_sources: Hash[String, Hash[Symbol, String]], ?discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]], ?discovered_superclasses: Hash[String, String], ?discovered_includes: Hash[String, Array[String]], ?discovered_class_sources: Hash[String, Set[String]], ?data_member_layouts: Hash[String, Array[Symbol]], ?struct_member_layouts: Hash[String, { members: Array[Symbol], keyword_init: bool }], ?param_inferred_types: Hash[[String, Symbol, Symbol], Hash[Symbol, Type::t]], ?run_generation: Object?) -> DiscoveryIndex
     end
 
     class IndexedKey
@@ -97,6 +104,9 @@ module Rigor
     def with_declaration_sourced_local: (String | Symbol name, Type::t type) -> Scope
     def with_local_declaration_mark: (String | Symbol name) -> Scope
     def declaration_sourced?: (Symbol kind, String | Symbol name) -> bool
+    def with_inferred_param_mark: (String | Symbol name) -> Scope
+    def without_inferred_param_mark: (String | Symbol name) -> Scope
+    def inferred_param?: (String | Symbol name) -> bool
     def forget_match_globals: () -> Scope
     def class_ivars_for: (String | Symbol? class_name) -> Hash[Symbol, Type::t]
     def class_cvars_for: (String | Symbol? class_name) -> Hash[Symbol, Type::t]
@@ -125,6 +135,7 @@ module Rigor
     def local_facts: (String | Symbol name, ?bucket: Symbol?) -> Array[Analysis::FactStore::Fact]
     def type_of: (untyped node, ?tracer: Inference::FallbackTracer?) -> Type::t
     def evaluate: (untyped node, ?tracer: Inference::FallbackTracer?) -> [Type::t, Scope]
+    def user_method_return: (untyped def_node, Type::t receiver, Array[Type::t] arg_types) -> Type::t?
     def join: (Scope other) -> Scope
     def ==: (untyped other) -> bool
     alias eql? ==

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

@@ -141,6 +141,16 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
   role.
 - **Determinism.** Add `--no-cache` in CI if you want each run independent
   of any persisted `.rigor/cache`.
+- **Cache persistence (opposite trade).** When the Rigor job's runtime
+  matters, persist `.rigor/cache` with the CI's cache facility. Current
+  Rigor detects CI and validates the restored cache by content hash
+  automatically (`cache.validation: auto`); on versions before the
+  `auto` default, **also set `RIGOR_STRICT_VALIDATION=1` on the job** —
+  without it a fresh checkout's regenerated stat tuples make the plugin
+  watch-glob cache slots read as stale on every run. A self-hosted
+  runner that reuses its workspace opts back into the faster stat check
+  with `cache.validation: stat`. Snippets: `rigor docs ci`
+  § "Persisting the analysis cache across runs".
 
 ## Verify
 

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

@@ -89,6 +89,17 @@ The manual chapter covers:
 - **Helix** (`languages.toml`)
 - **Emacs** (Eglot and lsp-mode)
 
+**The editors are not equally cheap to wire.** Neovim / Helix / Emacs
+are plain config snippets. **VS Code has no first-party Rigor
+extension yet** — its path means authoring and side-loading a minimal
+extension (a `LanguageClient` wrapper), which is a development task,
+not a `settings.json` edit. Say so *before* starting: the developer
+may prefer to wait for a first-class extension, and an autonomous
+agent should treat the VS Code path as a **user handoff** (report the
+manual's recipe; do not scaffold an unrequested extension). Phase 4's
+verification (live diagnostics, hover) also requires a human in front
+of the editor — an agent stops there and reports, for every editor.
+
 ### Phase 3 — apply the matching config
 
 Open the manual's **Editor wiring** section and apply the snippet for

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

@@ -21,6 +21,25 @@ frozen in this file (ADR-73).
 Work top to bottom. Stop at the first step that is not yet satisfied,
 complete it, then continue.
 
+## Autonomous / non-interactive runs
+
+When the user has delegated the journey up front ("set this project up
+and get it healthy; don't wait for me"), the skills below still contain
+ask-the-user points. Handle them like this:
+
+- A choice the user **already made in their instruction** (e.g. the
+  adoption mode) is settled — record it and proceed; do not re-ask.
+- A low-risk, reversible, in-repo action a skill says to confirm
+  (installing an RBS collection, a `.gitignore` addition) is covered by
+  the standing delegation — do it, and note the self-answer in your
+  report.
+- **Committing, pushing, or publishing is never covered** by a general
+  delegation — leave the files uncommitted and list them for the user.
+- A step only a human can complete or verify (watching a CI run
+  execute, confirming live diagnostics inside an editor) is a
+  **handoff, not a stall**: do the file-level part if it is safe,
+  then report what remains for the user instead of waiting.
+
 ## Step 1 — Resolve the `rigor` command
 
 ```sh
@@ -53,9 +72,11 @@ Check the project root for `.rigor.yml` or `.rigor.dist.yml`. If
 first:
 
 ```sh
-rigor skill rigor-project-init
+rigor skill --full rigor-project-init
 ```
 
+(`rigor skill <name>` prints the skill body alone; `--full` inlines its
+`references/` files too, so one call fetches the complete procedure.)
 Follow that skill's body top to bottom (it detects the stack, picks
 plugins, writes `.rigor.dist.yml`, and snapshots a baseline if needed),
 then come back to Step 4.
@@ -87,7 +108,7 @@ the `describe` output, then:
 - Then load the chosen skill and follow it:
 
   ```sh
-  rigor skill <chosen-skill>
+  rigor skill --full <chosen-skill>
   ```
 
 Re-run `rigor skill describe` any time you want the next step again — it

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

@@ -115,8 +115,8 @@ AST walk per file — hands every matching node to the block along with a
 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; `type_specifier` remains as a
-deprecating alias removed in 0.3.0 — use `narrowing_facts` in new plugins.)
+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 —
@@ -136,5 +136,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, 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 (`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. |
 | 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/02-walker-and-types.md

@@ -203,8 +203,8 @@ end
 ```
 
 > **`narrowing_facts` was renamed from `type_specifier` in ADR-80.**
-> `type_specifier` remains as a deprecating alias, removed in 0.3.0 — use
-> `narrowing_facts` in new plugins.
+> 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`:
 

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

@@ -1,7 +1,7 @@
 ---
 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 deprecated 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.
+  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.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -30,7 +30,7 @@ appears:
 3. **A hand-rolled AST walk** where the engine-owned `node_rule` now
    fits (ADR-37 / ADR-52).
 4. **Removed / renamed hooks** still named — `flow_contribution_for`
-   (deleted, ADR-52 WD3) or `type_specifier` (deprecated alias for
+   (deleted, ADR-52 WD3) or `type_specifier` (removed in 0.3.0; renamed to
    `narrowing_facts`, ADR-80).
 5. **Stale docs** — archaeology about deleted hooks, pinned version
    references that no longer mean anything.

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

@@ -78,12 +78,13 @@ can.
 ## 3. Return-type & narrowing hooks (ADR-37 / ADR-52 / ADR-80) — `M`/`D`
 
 **Smell:** `flow_contribution_for` (deleted in ADR-52 WD3 — *defining it
-now raises `ArgumentError`*), or `type_specifier` (the pre-ADR-80 name).
+now raises `ArgumentError`*), or `type_specifier` (the pre-ADR-80 name,
+removed in 0.3.0 — it now raises `NoMethodError`).
 
 **Modern:** `dynamic_return(receivers:/methods:/file_methods:)` to
 *supply* a return type, `narrowing_facts(methods:)` to supply
-post-return narrowing facts. `type_specifier` survives as a
-deprecating alias removed in 0.3.0 — rename to `narrowing_facts`.
+post-return narrowing facts. Rename any surviving `type_specifier` to
+`narrowing_facts`.
 
 The gate resolves after `#init` when passed a callable
 (`methods: -> { [@method_name] }`), so config-derived method names work.
@@ -207,7 +208,7 @@ and put that in a CHANGELOG / migration note, not the class docstring.
   misuse. MUST be clean; fix the cause, never disable the rule.
 - `rigor plugins --strict` — the plugin still activates.
 - `rigor plugins --capabilities` — `node_rule_types` /
-  `dynamic_return_receivers` / `type_specifier_methods` reflect the
+  `dynamic_return_receivers` / `narrowing_facts_methods` reflect the
   declarations.
 - The integration / unit spec — green, and byte-identical across every
   mechanical step.

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

@@ -17,9 +17,10 @@ and — if the project chooses it — a `.rigor-baseline.yml` snapshot.
 This skill is for **users adopting Rigor on their own project**. It
 uses the published `rigor` executable, installed standalone — Rigor
 is a tool, not a library, so it does **not** go in the project's
-`Gemfile`. See the manual's
-[Installing Rigor](../../docs/manual/01-installation.md)
-chapter for the install channels (`mise` recommended). This skill
+`Gemfile`. For the install channels (`mise` recommended) see the
+manual's Installing Rigor chapter — `rigor docs manual/01-installation`
+once any `rigor` is on `PATH`, or (pre-install)
+<https://github.com/rigortype/rigor/blob/master/docs/manual/01-installation.md>. This skill
 references only public CLI flags and config keys — the same surface
 `rigor --help` documents.
 
@@ -98,6 +99,29 @@ 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
+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)
+§ "Severity profile").
+
+## 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:
+
+- The **mode** the user pre-declared is settled; record it and skip the
+  Phase 2 presentation.
+- 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.
+- **Never commit or push under a general delegation.** Run the Final
+  step's file inventory as a *report* (what was created, what to
+  commit) instead of a question, and leave the commits to the user.
+
 ## Phase outline
 
 | Phase | What | Reference |
@@ -126,6 +150,7 @@ 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. |
+| — (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)
 
@@ -201,6 +226,7 @@ only in acknowledge mode). For each, give the commit recommendation:
 | `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. |
 
 Recommend the two concrete actions and **ask before doing them**
 (both touch the user's repo): (1) add `.rigor/` — and `.rigor.yml`

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

@@ -102,7 +102,7 @@ user as a list they can trim — do not silently enable everything.
 | Rails | `rigor-actionpack`, `rigor-activerecord`, `rigor-actionmailer`, `rigor-rails-routes`, `rigor-rails-i18n`, plus `rigor-activesupport-core-ext` (almost always needed — see below) |
 | dry-rb | `rigor-dry-types`, `rigor-dry-struct`, and `rigor-dry-schema` / `rigor-dry-validation` when those gems are present |
 | Sinatra | `rigor-sinatra` |
-| RSpec | `rigor-rspec` |
+| RSpec | `rigor-rspec` — **only if `paths:` will include `spec/`**. The conventional scope (see "Path scope" above) excludes `spec/`, and a plugin whose rules only fire on spec files contributes nothing outside it. Skip it under the default scope; add it later if the project opts spec files into analysis. |
 | Devise / Pundit / Sidekiq present | `rigor-devise` / `rigor-pundit` / `rigor-sidekiq` |
 | Sorbet present | `rigor-sorbet` (ingests existing `sig` blocks / RBI as type sources) |
 | plain Ruby | none required — the core analyzer covers it |

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

@@ -37,8 +37,11 @@ automatically and emit the message described:
 
 ## Severity profile — follows the mode
 
-The `severity_profile:` key re-stamps every rule's severity. Set it
-from the Phase 2 mode:
+The `severity_profile:` key sets every rule's severity — and for some
+rules, whether they fire at all: a rule can be *off* under `lenient`
+and surface under `balanced` / `strict` (e.g. the toplevel
+unresolved-call rule). Switching profiles can therefore **change the
+diagnostic count**, not just the labels. Set it from the Phase 2 mode:
 
 | Mode | `severity_profile` | Why |
 | --- | --- | --- |
@@ -48,6 +51,14 @@ from the Phase 2 mode:
 
 `balanced` is the built-in default — omit the key to get it.
 
+**The Phase 4 choice is provisional.** The ">100 errors" condition is
+measured by Phase 6's triage, which has not run yet — so write the
+best guess now and **revisit it when the triage counts land**: if the
+measured `error` count is small, prefer `balanced` even for a large
+acknowledge-mode app. Make any profile change **before** generating
+the baseline (Phase 7), and re-run `rigor triage` after changing it —
+the count the baseline snapshots must come from the final profile.
+
 ## No separate installation needed
 
 All plugins ship **bundled inside the `rigortype` gem**. The
@@ -57,9 +68,10 @@ the gem's own load path. No Gemfile entry, no `bundle install`,
 no separate gem channel.
 
 **The `rigortype` gem itself stays out of the project's
-`Gemfile`** — install it standalone per the manual's
-[Installing Rigor](../../docs/manual/01-installation.md) chapter
-(`mise use gem:rigortype` is the recommended channel). The
+`Gemfile`** — install it standalone per the manual's Installing
+Rigor chapter (`rigor docs manual/01-installation`, or pre-install
+<https://github.com/rigortype/rigor/blob/master/docs/manual/01-installation.md>;
+`mise use gem:rigortype` is the recommended channel). The
 project's Gemfile is untouched by this workflow.
 
 ## The template
@@ -191,6 +203,28 @@ shape):
 rigor plugins --strict
 ```
 
+### `rigor plugins` verifies activation, not analysis-time health
+
+A plugin that activates cleanly can still degrade **during
+analysis** — e.g. its model-index / routes-parsing stage fails on
+this machine — and that failure surfaces only as a
+`plugin.<id>.load-error` **warning inside the diagnostic stream**,
+easy to miss among hundreds of lines. After the first full
+`rigor check` / `rigor triage` run (Phase 6), check for it
+explicitly:
+
+```sh
+rigor check --format json | jq '[.diagnostics[] | select(.rule | endswith("load-error"))]'
+```
+
+Any hit means that plugin contributed **no diagnostics and no
+types** for the capability that failed — reduced coverage, silently.
+Surface it to the user rather than letting it slide into the
+baseline: a `load-error` bucket in `.rigor-baseline.yml` would hide
+the degradation permanently. If the error reproduces across runs,
+report it upstream (<https://github.com/rigortype/rigor/issues>)
+with the message text.
+
 ## Output of this module
 
 A committed `.rigor.dist.yml` with `paths:`, `exclude:`,

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

@@ -14,6 +14,14 @@ the triage command instead:
 rigor triage --format json
 ```
 
+> **Parsing the JSON from a script**: diagnostic messages can carry
+> non-ASCII bytes from the project's own strings (i18n content,
+> comments), which makes a naive `File.read` + `JSON.parse` raise
+> `Encoding::InvalidByteSequenceError`. Force UTF-8 and scrub —
+> `JSON.parse(File.read(f, encoding: "UTF-8").scrub)` — or use `jq`,
+> which handles it natively. The same applies to
+> `rigor check --format json`.
+
 `rigor triage` runs the same analysis as `rigor check`, then returns
 a structured summary instead of the per-line dump. It is read-only
 and advisory — it never edits config and never writes a baseline.
@@ -79,6 +87,18 @@ If triage flags `activesupport-core-ext` (or any config gap),
 baseline and the real-bug review should both run against the
 post-config diagnostic set, not the inflated one.
 
+### Check for analysis-time plugin failures before baselining
+
+Scan the `distribution` for any `plugin.<id>.load-error` rule (or run
+the `jq` one-liner in
+[`02-configure.md`](02-configure.md) § "`rigor plugins` verifies
+activation, not analysis-time health"). A `load-error` means the
+plugin activated but one of its capabilities failed while analysing
+*this* project — its diagnostics and types are silently absent from
+the stream you are about to snapshot. Surface it to the user and
+resolve (or at least record) it **before** Phase 7: a `load-error`
+bucket baked into the baseline hides the degradation permanently.
+
 ## Phase 6a — Pre-baseline cleanup
 
 Before generating the baseline, **apply every quick fix that triage

data/skills/rigor-project-init/references/05-jit-performance.md

@@ -0,0 +1,125 @@
+# Reference 05 — JIT and run speed (YJIT / ZJIT)
+
+Operational, not part of onboarding proper: how Rigor uses a Ruby JIT to
+speed up analysis, how to tell whether it is active in your install, and the
+trade-off (and break-even point) if you want to override the default. Read
+this when a project is large enough that `rigor check` wall time matters —
+Rails monorepos especially. On a small project you can ignore it entirely:
+Rigor already does the right thing with no configuration.
+
+## TL;DR
+
+- **You usually do nothing.** Rigor enables YJIT automatically once a run has
+  been going long enough to be worth it, and leaves it off for short runs
+  where it would only add warm-up cost. This is on by default.
+- **Break-even is ~5 seconds.** A JIT pays for its warm-up only on longer
+  runs; below it, JIT-on is *slower*. Rigor's 5-second deadline is set at
+  that crossover.
+- **YJIT, not ZJIT.** Ruby 4.0 ships both JITs, but YJIT is faster for Rigor's
+  workload — measurably so on every run large enough for a JIT to help. Rigor
+  uses YJIT; there is no reason to force ZJIT.
+
+## How Rigor uses a JIT
+
+`rigor check` and `rigor coverage` arm a background timer at the start of a
+run. If the run is still going after ~5 seconds, YJIT is switched on for the
+remainder; a run that finishes first never pays any JIT cost. So:
+
+- A quick check (a small project, or a warm cache hit) runs on the plain
+  interpreter — no warm-up penalty.
+- A long cold analysis of a large project gets YJIT for its dominant tail,
+  where the speed-up more than repays the warm-up.
+
+Diagnostics and their counts are identical whether or not the JIT engages —
+a JIT changes wall time only, never results.
+
+The long-running servers `rigor lsp` and `rigor mcp` turn YJIT on at start
+instead, since they always run long.
+
+## Is a JIT available in my install?
+
+The deferred-YJIT feature only helps if the Ruby your `rigor` runs on was
+built with YJIT support. Rigor is installed standalone (see the manual's
+Installing Rigor chapter: `rigor docs manual/01-installation`), so this is a
+property of *that* Ruby, which may differ from your project's Ruby.
+
+Check the Ruby that runs `rigor`:
+
+```sh
+ruby --yjit -e 'require "rbconfig"; puts "YJIT: #{RbConfig::CONFIG["YJIT_SUPPORT"]}"; puts "ZJIT: #{RbConfig::CONFIG["ZJIT_SUPPORT"]}"'
+# YJIT: yes   → the deferred-YJIT engages automatically on long runs
+# YJIT: no    → the feature is a silent no-op; runs use the interpreter
+```
+
+- Most prebuilt CRuby 3.3+ (mise / rbenv / asdf, the recommended install
+  channels) ship with YJIT built in but **not** ZJIT — a prebuilt
+  mise Ruby 4.0, for example, reports `YJIT: yes` / `ZJIT: no`, because
+  ZJIT needs `rustc` at build time and the prebuilt binary omits it. That
+  is exactly the configuration Rigor wants: YJIT is the faster JIT for
+  Rigor (see the YJIT-vs-ZJIT section below), so a missing ZJIT costs you
+  nothing.
+- The Nix flake package of Rigor bundles a Ruby with **both** JITs; that
+  is the only common install where `ZJIT: yes` — and Rigor still uses
+  YJIT there.
+- A YJIT-less Ruby is not an error — Rigor just runs interpreted, correctly.
+
+## Overriding the default
+
+Three environment variables, documented in the CLI reference's
+"Environment variables" section (`rigor docs manual/02-cli-reference`):
+
+| Want | Do |
+| --- | --- |
+| Force YJIT on for the **whole** run (including the first 5 s) | `RUBYOPT="--yjit" rigor check …` |
+| Turn Rigor's JIT off entirely | `RIGOR_DISABLE_YJIT=1 rigor check …` |
+| Change the deadline (advanced) | `RIGOR_YJIT_DEADLINE=<seconds> rigor check …` |
+
+When would you override?
+
+- **Force-on** helps only if *every* run you care about is long (a big
+  monorepo in CI where even the fast path is > 5 s). On mixed workloads the
+  default deadline is better — it protects your quick local re-checks.
+- **Off** is the escape hatch if a JIT ever misbehaves on your platform, or to
+  get a clean interpreter baseline when measuring.
+
+## Why the ~5-second break-even (the trade-off)
+
+A JIT compiles hot code to machine code, which costs time up front and repays
+it over the rest of the run. On a short run the compilation never amortizes,
+so JIT-on loses. Measured cold `rigor check`, by project size:
+
+| run size | interpreter | YJIT | effect |
+| --- | --- | --- | --- |
+| ~1.6 s (small lib) | baseline | **+67 %** | JIT-on loses badly |
+| ~4 s (medium lib) | baseline | ~break-even | a wash |
+| ~8 s | baseline | **−13 %** | JIT-on wins |
+| ~19 s (Rails monorepo) | baseline | **−20 %** | wins more |
+| ~17 s (large Rails app) | baseline | **−28 %** | biggest win |
+
+The deadline parks the enable point just past the loss zone: runs that finish
+before ~5 s never pay warm-up; longer runs collect the win on their tail.
+
+## YJIT vs ZJIT (Ruby 4.0)
+
+Ruby 4.0 ships a second JIT, **ZJIT** (a newer method-based JIT;
+[upstream docs](https://docs.ruby-lang.org/en/master/jit/zjit_md.html)). It
+is real and correctness-safe on Rigor (identical diagnostics), but **slower
+than YJIT for Rigor's workload** at Ruby 4.0. Measured cold, on the runs where
+a JIT helps at all:
+
+| target | YJIT vs interpreter | ZJIT vs interpreter | ZJIT vs YJIT |
+| --- | --- | --- | --- |
+| ~8 s | −13 % | −4 % | +10 % |
+| ~19 s (monorepo) | −20 % | −13 % | +10 % |
+| ~17 s (large app) | −28 % | −14 % | +21 % |
+
+YJIT wins on every workload large enough to warrant a JIT; ZJIT's peak
+speed-up is roughly half. ZJIT only edges YJIT on tiny runs — the zone where
+you want no JIT at all. **Do not force ZJIT** (`RUBYOPT="--zjit"`) for Rigor;
+the automatic YJIT is faster. Full measurement + methodology (a
+contributor-side note, web only):
+<https://github.com/rigortype/rigor/blob/master/docs/notes/20260714-jit-evaluation-yjit-zjit-ruby40.md>.
+
+This verdict is Ruby-4.0-specific; ZJIT is younger than YJIT and improving, so
+it may close the gap in a later Ruby. Until then YJIT is the right default —
+which is what Rigor already does.