rigortype 0.2.9 → 0.3.0

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet.rb

@@ -116,6 +116,18 @@ module Rigor
         errors.map { |error| parse_error_diagnostic(path, error) }
       end
 
+      # ADR-88 WD2 — the per-run catalog is an ADR-60 record-and-validate producer. Before this it was rebuilt
+      # unconditionally on every `--incremental` recheck (parse + walk every `.rb` / `.rbi` sig tree); as a
+      # producer it is cached to disk keyed on the plugin config, with `watch:` covering the scanned trees so an
+      # added / removed / edited sig file recomputes it. The producer VALUE (a Marshal-clean bundle of the
+      # catalog + the sigil map + the parse-error tuples) is what ADR-88 WD1 digests into the incremental
+      # fact-surface fingerprint, so a sig edit OUTSIDE `signature_paths:` invalidates the snapshot for free.
+      # The bundle is returned (not written to ivars) because a cache HIT does not run the block — the sigil map
+      # and parse errors would otherwise be lost on the warm path.
+      producer :catalog, watch: -> { catalog_watch_globs } do |_params|
+        build_catalog_bundle
+      end
+
       # ADR-52 slice 4 — per-call return-type path via the method-name-gated `dynamic_return` DSL. The
       # recognised name set is only known at run time (the catalog's `def` names come from the lazy
       # catalog build), so it is declared as a callable: the engine `instance_exec`s it once per run on
@@ -389,35 +401,69 @@ module Rigor
         end
       end
 
+      # ADR-88 WD2 — resolve the catalog from the `:catalog` producer (disk-cached) and unpack its Marshal-clean
+      # bundle into the ivars the return-type / sigil-gate / parse-error paths read. `producer_value` memoises
+      # per instance and rescues a producer failure to nil, hence the empty-bundle fallback.
       def ensure_catalog
         return @catalog if @catalog_built
 
+        bundle = producer_value(:catalog) || EMPTY_CATALOG_BUNDLE
+        @catalog = bundle[:catalog]
+        @sigil_by_path = bundle[:sigil_by_path]
+        @parse_errors_by_path = bundle[:parse_errors_by_path]
+        @catalog_built = true
+        @catalog
+      end
+
+      # ADR-88 WD2 — the `watch:` coverage for the `:catalog` producer: the `.rb` sig trees + the `.rbi` trees.
+      # An added / removed file under either invalidates the cached bundle even though the block globbed the
+      # tree itself. Evaluated at `cache_for` time (after `#init`), so `@configured_paths` / `@rbi_paths` are set.
+      def catalog_watch_globs
+        [[@configured_paths, "**/*.rb"], [@rbi_paths, "**/*.rbi"]]
+      end
+
+      # ADR-88 WD2 — build the Marshal-clean catalog bundle the `:catalog` producer caches. Harvests the `.rb`
+      # sig trees then the `.rbi` trees (last-wins ordering preserved from the ivar-mutating original) and
+      # returns `{ catalog:, sigil_by_path:, parse_errors_by_path: }`.
+      def build_catalog_bundle
         catalog = Catalog.new
+        sigil_by_path = {}
+        parse_errors_by_path = {}
         # Project source — `.rb` only.
-        @configured_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rb]) }
+        @configured_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rb]) }
         # Sorbet RBI tree — `.rbi` only. Slice 4 of ADR-11.
-        @rbi_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rbi]) }
+        @rbi_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rbi]) }
         catalog.freeze!
-        @catalog = catalog
-        @catalog_built = true
-        catalog
+        { catalog: catalog, sigil_by_path: sigil_by_path, parse_errors_by_path: parse_errors_by_path }
       end
 
+      # Frozen empty bundle used when the `:catalog` producer failed (e.g. a project I/O error) so downstream
+      # reads see a well-formed shape rather than nil.
+      EMPTY_CATALOG_BUNDLE = { catalog: Catalog.new.freeze!, sigil_by_path: {}, parse_errors_by_path: {} }.freeze
+      private_constant :EMPTY_CATALOG_BUNDLE
+
       # @param root [String] directory or single file.
       # @param catalog [Catalog]
+      # @param sigil_by_path [Hash{String=>Symbol}] accumulator: harvested file → detected sigil level.
+      # @param parse_errors_by_path [Hash{String=>Array<Hash>}] accumulator: file → `{kind:,line:,column:}` tuples.
       # @param extensions [Array<String>] file extensions to accept (e.g. `[".rb"]` for project source,
       #   `[".rbi"]` for Sorbet RBI tree).
-      def harvest_path(root, catalog, extensions:)
+      def harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, extensions)
         absolute = canonicalize(root)
         if File.directory?(absolute)
           extensions.each do |ext|
+            # ADR-88 WD2 — deterministic fold order matters now that the catalog VALUE is digested into the
+            # incremental fact-surface fingerprint: a duplicate `(class, method, kind)` sig's last-wins winner
+            # must not vary by machine / run. `Dir.glob` sorts its results by default on Ruby 3.0+, so the fold
+            # order is already stable (the slice-1 comment's "filesystem order" caveat predates that default);
+            # this walk relies on it rather than re-sorting.
             Dir.glob(File.join(absolute, "**", "*#{ext}")).each do |path|
-              harvest_file(canonicalize(path), catalog)
+              harvest_file(canonicalize(path), catalog, sigil_by_path, parse_errors_by_path)
             end
           end
         elsif File.file?(absolute) && extensions.any? { |ext| absolute.end_with?(ext) }
           # `paths:` may list individual files (the demos do this); walk them directly rather than skipping.
-          harvest_file(absolute, catalog)
+          harvest_file(absolute, catalog, sigil_by_path, parse_errors_by_path)
         end
       end
 
@@ -432,7 +478,7 @@ module Rigor
         expanded
       end
 
-      def harvest_file(path, catalog)
+      def harvest_file(path, catalog, sigil_by_path, parse_errors_by_path)
         contents = io_boundary.read_file(path)
         return if contents.nil?
 
@@ -441,7 +487,7 @@ module Rigor
         # Per-call-site assertion gating consults this map at recognition time. Recorded BEFORE the
         # ignored short-circuit so a `# typed: ignore` file still reports its level to the gate (the gate
         # then chooses to suppress assertions there too — `ignore` is stricter than `false`).
-        @sigil_by_path[path] = level
+        sigil_by_path[path] = level
         return if SigilDetector.ignored?(level)
 
         result = Prism.parse(contents)
@@ -460,13 +506,23 @@ module Rigor
                       end
 
         errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path)
-        @parse_errors_by_path[path] = errors unless errors.empty?
+        # ADR-88 WD2 — store Marshal-clean `{kind:, line:, column:}` tuples, not the `ParseError` (it holds a
+        # live Prism node the producer bundle could not serialise). `diagnostics_for_file` rebuilds the
+        # diagnostic from the tuple, at the same 1-based line / `start_column + 1` position `from_node` gave.
+        parse_errors_by_path[path] = errors.map { |error| parse_error_tuple(error) } unless errors.empty?
       rescue Plugin::AccessDeniedError, Errno::ENOENT
         # Skip files outside the trusted read scope or that vanished between glob and read; the plugin
         # produces no output for them.
         nil
       end
 
+      # ADR-88 WD2 — the Marshal-clean position tuple for a `CatalogWalker::ParseError`, capturing the node's
+      # location at harvest time so the producer bundle carries no live Prism node.
+      def parse_error_tuple(error)
+        location = error.node.location
+        { kind: error.kind, line: location.start_line, column: location.start_column + 1 }
+      end
+
       # Emits a `plugin.sorbet.absurd-reachable` warning for the `T.absurd(x)` call recorded in
       # `@reachable_absurd_nodes` during inference; the node rule above does the identity match and pop.
       def absurd_diagnostic(path, call_node)
@@ -535,11 +591,15 @@ module Rigor
         )
       end
 
+      # ADR-88 WD2 — `error` is a Marshal-clean `{kind:, line:, column:}` tuple (the pre-computed node
+      # location), not a Prism-node-bearing `ParseError`; build the diagnostic directly at that position (the
+      # `line` / `column` `from_node` would have derived).
       def parse_error_diagnostic(path, error)
-        Rigor::Analysis::Diagnostic.from_node(
-          error.node,
+        Rigor::Analysis::Diagnostic.new(
           path: path,
-          message: parse_error_message(error.kind),
+          line: error[:line],
+          column: error[:column],
+          message: parse_error_message(error[:kind]),
           severity: :warning,
           rule: "parse-error"
         )

data/sig/prism_node_children.rbs

@@ -0,0 +1,9 @@
+# Declares the reopening `Rigor::Source::NodeChildren` performs at load: a compiled `#rigor_each_child` is defined on
+# every concrete `Prism::*Node` class (allocation-free equivalent of `compact_child_nodes.each`). Declared on the
+# abstract base so every subclass resolves; the runtime definition is per-concrete-class, generated from
+# `Prism::Reflection` in lib/rigor/source/node_children.rb.
+module Prism
+  class Node
+    def rigor_each_child: () { (Prism::Node) -> void } -> void
+  end
+end

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

@@ -28,8 +28,7 @@ class Rigor::Plugin::Base
 
   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]
+  def self.narrowing_facts_rules: () -> Array[untyped]
 
   def self.suggest: (untyped name, untyped candidates) -> String?
 
@@ -48,7 +47,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