rigortype 0.3.9 → 0.4.0

data/lib/rigor/cache/engine_source.rb

@@ -3,6 +3,7 @@
 require "digest"
 
 require_relative "../version"
+require_relative "descriptor"
 
 module Rigor
   module Cache
@@ -63,6 +64,9 @@ module Rigor
       # to whatever else happened to be there, which is exactly the weakening this module forbids.
       REQUIRED_DIRECTORY = "lib"
 
+      # The config-row key every computed-value slot carries the identity under.
+      CONFIG_KEY = "engine-source"
+
       module_function
 
       # @return the gem root — the directory holding `lib/`, three levels above this file.
@@ -100,10 +104,34 @@ module Rigor
       # exists at all. The same reading covers the long-running `rigor lsp` process.
       #
       # {Unavailable} propagates and is deliberately NOT memoised: the ivar is only assigned on success.
+      #
+      # The memo is FROZEN because a Ractor-pool worker reads it (#1055): the auto-wired ADR-93
+      # `rigor-rbs-inline` synthesizer reaches `.key_config_entries` from inside
+      # `Environment.for_project`, which is inside `WorkerSession#initialize`, which is inside the worker's
+      # own Ractor — and a non-main Ractor may read a class/module ivar only when its value is shareable.
+      # An unfrozen digest String therefore killed every worker in its constructor on any run with the
+      # synthesizer on, which is every real CLI run (the spec suite pins it off). The worker never WRITES
+      # it: `PoolCoordinator#analyze_files_in_pool` pre-warms this on the main Ractor first, which is where
+      # the argument above already says the value belongs.
       def process_identity
         return @process_identity if defined?(@process_identity)
 
-        @process_identity = identity
+        @process_identity = identity.freeze
+      end
+
+      # The `engine-source` key row for a cache whose value this engine computed, built from
+      # {.process_identity}: empty for a version-pinned tree, so a released gem's keys stay byte-identical.
+      #
+      # Issue #1009 — a slot keyed only on its inputs and a plugin's manifest version outlives the engine
+      # that filled it. The per-file synthesizer slot and every plugin producer were keyed that way, so after
+      # an engine or bundled-plugin edit the run-result key moved and the run re-analysed, but through the
+      # previous build's synthesized RBS and producer values. {Unavailable} propagates, so a caller that
+      # cannot identify the engine bypasses its cache instead of falling back to the weaker key.
+      def key_config_entries
+        identity = process_identity
+        return [] if identity.nil?
+
+        [Descriptor::ConfigEntry.new(key: CONFIG_KEY, value_hash: Digest::SHA256.hexdigest(identity))]
       end
 
       # Discards the {.process_identity} memo; production code MUST NOT call this — a run that recomputed

data/lib/rigor/cache/incremental_snapshot.rb

@@ -106,7 +106,39 @@ module Rigor
       # blob has no such section and would deserialise it as nil, which reads as "nothing cached" and is
       # therefore not misread — but a snapshot written by an engine that did not yet REPLAY them was also
       # written by one whose narrowed runs under-reported, so the gate rejects it and the next run is cold.
-      SCHEMA = 22
+      # 23: issue #992 gives each seed bundle a `parameter_envelopes` table — the joined positional envelope
+      # of every method a file records, plus its module / dynamic-surface marks — which `call.wrong-arity`
+      # reads for a method no signature declares. A pre-23 bundle folds as "no envelopes", which only ever
+      # withholds a check, but a warm run that withholds where a cold run fires is still the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 24: issue #1097 gives each seed bundle a `deferred_ranges` table — the per-file def / block /
+      # lambda body ranges `Scope#*_def_shadows_call?` orders a project-defined `sig` override
+      # against. A pre-24 bundle would fold as "no ranges", which the predicate reads as "cannot
+      # order → shadow" — a warm run declining the binding where a cold run binds.
+      # 25: issue #1097 extends each `deferred_ranges` row to `[start, end, name, kind, owner]` —
+      # owner-scoped ordering. A 24 bundle folds as "owner = nil", which the predicate reads as
+      # "cannot order", under-shadowing `module_function` defs whose only table evidence is the row
+      # itself.
+      # 26: issue #1123 gives each seed bundle a `prepends` table — the instance-ancestor ORDER of a
+      # class's `prepend`ed modules, which `Scope#user_def_through_ancestors` searches ahead of the
+      # class's own `def`s. A pre-26 bundle would fold as "prepends nothing": the warm run would answer
+      # the pre-fix MRO where a cold run answers the prepended module, exactly the `--verify-incremental`
+      # divergence 14 was bumped for (and a silently WRONG dispatch answer, not a withheld check).
+      # 27: issue #1173 re-MEANs each seed bundle's `includes` VALUES without changing their shape: the
+      # lists now store instance-ancestor SEARCH order (nearest first, prepends ahead of includes)
+      # instead of call order — the same flip 17 made for def-row `nesting`. A pre-27 blob deserialises
+      # cleanly and would serve the old call order on a warm run while a cold run searches nearer-first:
+      # `include A; include B` would resolve A's methods where a cold run resolves B's — the
+      # `--verify-incremental` divergence 14 was bumped for.
+      # 28: issue #1120 gives each seed bundle a `refinements` table — the `def`s of every `refine X do … end`
+      # body, which `call.undefined-method` reads where a `using` of the refining module is in effect. A
+      # pre-28 bundle would fold as "refines nothing", and a warm run would report a refined call a cold run
+      # declines.
+      # 29: issue #1367 gives each seed bundle a `global_write_census` — the globals its `alias` statements name and
+      # the `write` / `to_str` / `to_int` / hatch definitions and top-level mixins it holds, which the `global.*`
+      # write rules decline on project-wide. A pre-29 bundle would fold as "none of those", and a warm run would
+      # report a write a cold run exempts.
+      SCHEMA = 29
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -29,6 +29,10 @@ module Rigor
         # files, same libraries), so the loader memoises one build per process instead of re-digesting every
         # .rbs file once per producer.
         descriptor = loader.rbs_cache_descriptor
+        # Issue #1014 — nil is an engine the descriptor could not identify ({EngineSource::Unavailable}).
+        # Compute uncached rather than keying the value without the engine that produced it.
+        return compute(loader) if descriptor.nil?
+
         store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor,
                                generation_cap: generation_cap) do
           compute(loader)

data/lib/rigor/cache/rbs_descriptor.rb

@@ -3,20 +3,47 @@
 require "digest"
 
 require_relative "descriptor"
+require_relative "engine_source"
 require_relative "file_digest"
 
 module Rigor
   module Cache
     # Shared descriptor builder for cache producers that depend on the RBS environment (constant table,
-    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same three
-    # slots, so factoring the construction here keeps the producers small and ensures invalidation behaves
-    # identically across them.
+    # known-class set, future Marshal-clean reflection artefacts). Every consumer attaches the same slots —
+    # the `rbs` gem row, a digest row per signature file, and the `rbs.libraries` / `rbs.virtual_rbs` /
+    # `rbs.deferred_signature_paths` / `engine-source` config rows — so factoring the construction here keeps
+    # the producers small and ensures invalidation behaves identically across them.
     module RbsDescriptor
+      # The key every `rbs.*` producer shares ({RbsCacheProducer#fetch}): `rbs.environment`,
+      # `rbs.constant_type_table`, `rbs.class_ancestor_table`, `rbs.known_class_names`,
+      # `rbs.class_type_param_names`.
+      #
+      # Issue #1014 — the engine-source row is here, not in {.config_entries}, because these are
+      # computed-value slots: what they hold is not the RBS the descriptor digests but what Rigor's own code
+      # made of it. `rbs.constant_type_table` stores `Inference::RbsTypeTranslator.translate` output and
+      # `rbs.class_ancestor_table` the chains `RbsClassAncestorTable.compute` walks out of
+      # `instance_definition`, so an engine edit to either moved the value while the key stood still: the
+      # run-result key moved (#285) and the run re-analysed, then read the previous build's table. Both were
+      # reproduced cross-build on a fixture — a true positive dropped, and a `flow.unreachable-clause` false
+      # positive served — before this row was added.
+      #
+      # {.config_entries} deliberately does NOT get it: that half is what the ADR-45 run cache key reads
+      # ({.build_run}), and `RunCacheKey` already contributes the identical row from
+      # `EngineSource.key_config_entries` itself. Adding it there would duplicate the row in the run key and
+      # would have to be reconstructible by the boot-slimming probe, which builds `config_entries` without a
+      # loader.
+      #
+      # @raise EngineSource::Unavailable — an engine that cannot be identified must not be keyed by its
+      #   inputs alone; {RbsCacheProducer.fetch} turns this into an uncached compute.
       def self.build(loader)
+        # FIRST, before {.file_entries} digests the whole signature tree: the {EngineSource::Unavailable}
+        # path discards this descriptor entirely, and a SHA-256 of every `.rbs` under every signature root is
+        # the expensive way to reach that conclusion.
+        engine = EngineSource.key_config_entries
         Descriptor.new(
           gems: [rbs_gem_entry],
           files: file_entries(loader),
-          configs: config_entries(loader) + env_only_config_entries(loader)
+          configs: config_entries(loader) + env_only_config_entries(loader) + engine
         )
       end
 
@@ -25,8 +52,10 @@ module Rigor
       # MISS, by the dependency descriptor ({Runner#run_dependency_descriptor}). So a warm HIT never digests
       # the (large, vendored) RBS tree. {RunDescriptor} is NOT a {Descriptor} — it is never composed, hashed,
       # or `==`'d, only its four readers are consulted — so deferring `files` costs no soundness, and `gems`
-      # / `configs` match {.build}'s shared slots (the key is unchanged; the one slot the env key adds on
-      # top, {.env_only_config_entries}, is never read here).
+      # / `configs` match {.build}'s shared slots (the key is unchanged; the slots the env key adds on top,
+      # {.env_only_config_entries} and the #1014 `engine-source` row, are never read here — `RunCacheKey`
+      # contributes the identical engine-source row itself, from the same
+      # `EngineSource.key_config_entries`).
       def self.build_run(loader)
         RunDescriptor.new(loader: loader, gems: [rbs_gem_entry], configs: config_entries(loader))
       end
@@ -112,7 +141,8 @@ module Rigor
       # overlays. Rigor's own `data/` trees ({RbsLoader.vendored_gem_sig_paths}, `.core_overlay_sig_paths`,
       # `.capability_role_sig_paths`) are engine-owned: a file appears under one only when the engine tree is
       # edited, which normally arrives with the `lib/` change that reads it and so re-keys every
-      # computed-value slot through {EngineSource}. They get file rows and no glob — a glob there would cost
+      # computed-value slot through {EngineSource} — including, since #1014, this descriptor itself, which
+      # until then carried no such row. They get file rows and no glob — a glob there would cost
       # every project a stat walk of the vendored gem-signature tree per warm run to catch an
       # engine-development edit.
       def self.glob_entries(loader)

data/lib/rigor/cache/store.rb

@@ -65,7 +65,6 @@ module Rigor
 
       VALID_PRODUCER_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      # @param root — cache root directory.
       # @param read_only — when true, every disk-side side-effect is suppressed: `fetch_or_compute`
       #   still reads existing entries (hits, gated on a current `schema_version.txt` marker — see
       #   {#ensure_schema_version!}) and still runs the producer block on miss, but it does NOT write the

data/lib/rigor/ci_detector.rb

@@ -61,6 +61,7 @@ module Rigor
       { id: "ci", name: "CI", format: nil, tier: :reviewdog,
         var: "CI", match: :truthy }
     ].freeze
+    Ractor.make_shareable(PROVIDERS)
 
     module_function
 

data/lib/rigor/cli/doc_links.rb

@@ -31,7 +31,7 @@ module Rigor
       private_constant :MARKDOWN_LINK
 
       # Where the gem's `docs/` tree sits, so a rendered path can be made repository-relative.
-      GEM_ROOT = File.expand_path("../../..", __dir__)
+      GEM_ROOT = File.expand_path("../../..", __dir__).freeze
       private_constant :GEM_ROOT
 
       module_function

data/lib/rigor/cli/docs_command.rb

@@ -47,10 +47,10 @@ module Rigor
       USAGE
 
       # The bundled docs live at `<gem_root>/docs/`. From `lib/rigor/cli/docs_command.rb` that is three directories up.
-      DOCS_ROOT = File.expand_path("../../../docs", __dir__)
-      MANUAL_ROOT = File.join(DOCS_ROOT, "manual")
-      HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
-      LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
+      DOCS_ROOT = File.expand_path("../../../docs", __dir__).freeze
+      MANUAL_ROOT = File.join(DOCS_ROOT, "manual").freeze
+      HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook").freeze
+      LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt").freeze
 
       # @return CLI exit status.
       def run

data/lib/rigor/cli/plugin_command.rb

@@ -60,9 +60,9 @@ module Rigor
 
       # The bundled plugins/examples/source live at `<gem_root>/...`. From `lib/rigor/cli/plugin_command.rb` the gem
       # root is three directories up (matching SkillCommand::SKILLS_ROOT).
-      GEM_ROOT     = File.expand_path("../../..", __dir__)
-      PLUGINS_ROOT = File.join(GEM_ROOT, "plugins")
-      EXAMPLES_ROOT = File.join(GEM_ROOT, "examples")
+      GEM_ROOT     = File.expand_path("../../..", __dir__).freeze
+      PLUGINS_ROOT = File.join(GEM_ROOT, "plugins").freeze
+      EXAMPLES_ROOT = File.join(GEM_ROOT, "examples").freeze
 
       # @return CLI exit status.
       def run

data/lib/rigor/cli/prism_colorizer.rb

@@ -35,7 +35,6 @@ module Rigor
 
       VARIABLE_TOKENS = %i[INSTANCE_VARIABLE CLASS_VARIABLE GLOBAL_VARIABLE].freeze
 
-      # @param source — Ruby source.
       # @return the source with ANSI colour escapes, or
       #   the input unchanged when lexing surfaces an error.
       def colorize(source)

data/lib/rigor/cli/sig_gen_command.rb

@@ -3,6 +3,8 @@
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "../effects/config_envelopes"
+require_relative "../effects/registry"
 require_relative "options"
 require_relative "../sig_gen"
 require_relative "command"
@@ -22,21 +24,27 @@ module Rigor
     # AND the candidate is a `tighter-return`.
     #
     # Parameter policy defaults to `untyped`. `--params=observed` (slice 3) opts in to caller-side observation
-    # harvesting: the `ObservationCollector` walks `--observe=PATH...` (default `spec/` when no flag is given AND a
-    # `spec/` directory exists), unions per-position arg types, and the generator emits the union per ADR-5 clause 2.
+    # harvesting: the `ObservationCollector` walks `--observe=PATH...` (default: the project's test roots,
+    # {Configuration#resolved_test_paths}), unions per-position arg types, and the generator emits the union per ADR-5
+    # clause 2.
     # `--params=observed-strict` stays reserved-but-inert until the capability-role catalog ships (rejected with a usage
     # error so the surface stays stable).
-    class SigGenCommand < Command
+    #
+    # `--check` (ADR-112 WD4) is the CI freshness gate: it runs the `--write` merge with every other flag as given,
+    # writes nothing, prints what would change, and exits 1 when anything would.
+    class SigGenCommand < Command # rubocop:disable Metrics/ClassLength
       USAGE = "Usage: rigor sig-gen [options] [paths]"
 
-      VALID_MODES = %w[print diff write].freeze
+      VALID_MODES = %w[print diff write check].freeze
       VALID_PARAM_POLICIES = %w[untyped observed observed-strict].freeze
       VALID_FORMATS = %w[text json].freeze
 
-      # The skip reasons {#report_skipped} counts. The two left out each have a detailed report of their own
-      # ({#report_unrenderable}, {#report_unresolvable_superclasses}), so a method never shows up in two tallies.
+      # The skip reasons {#report_skipped} counts. The four left out each have a report of their own
+      # ({#report_unrenderable}, {#report_unresolvable_superclasses}, {#report_inline_declared}, and the refusal
+      # lines `--write` / `--check` print for `inline_differs`), so a method never shows up in two tallies.
       SUMMARISED_SKIP_REASONS = (SigGen::Classification::SKIP_DIAGNOSTIC_IDS.keys -
-                                 %i[unrenderable_rbs unresolvable_superclass]).freeze
+                                 %i[unrenderable_rbs unresolvable_superclass inline_declared
+                                    inline_differs]).freeze
       private_constant :SUMMARISED_SKIP_REASONS
 
       # @return CLI exit status.
@@ -50,17 +58,22 @@ module Rigor
         observations = collect_observations(configuration, options)
         generator = SigGen::Generator.new(configuration: configuration, paths: paths,
                                           observations: observations,
-                                          include_private: options.fetch(:include_private))
+                                          include_private: options.fetch(:include_private),
+                                          effect_annotator: effect_annotator(configuration, paths, options),
+                                          overwrite: options.fetch(:overwrite))
         candidates = generator.run
         mode = options.fetch(:mode).to_sym
 
-        status = if mode == :write
-                   dispatch_write(candidates, configuration, options)
+        status = case mode
+                 when :write then dispatch_write(candidates, configuration, options)
+                 when :check then dispatch_check(candidates, configuration, options)
                  else
                    dispatch_print_or_diff(candidates, mode, options)
                    0
                  end
         report_skipped(candidates, options)
+        report_inline_declared(candidates, options)
+        report_withheld_annotations(candidates, options)
         report_unrenderable(generator.unrenderable)
         report_unresolvable_superclasses(generator.unresolvable_superclasses)
         status
@@ -68,6 +81,74 @@ module Rigor
 
       private
 
+      # ADR-103 WD9 — the effect table sig-gen writes annotations from, or `nil`.
+      #
+      # The gate is the project's own `effects:` opt-in and nothing else. An annotation is read back as an
+      # enforced envelope, so turning emission on from a sig-gen flag alone would let one command commit a
+      # project to a contract `rigor check` was never asked to keep; and a project that has not opted in
+      # pays neither the analysis this needs nor a single changed byte of output.
+      #
+      # `--effect-envelopes` is the second, narrower switch: `%a{pure}` is the ecosystem's existing purity
+      # spelling and round-trips through Steep as well as Rigor, while `%a{rigor:v1:effect …}` is Rigor's
+      # own and belongs in a project's `sig/` only when the author asked for it by name.
+      def effect_annotator(configuration, paths, options)
+        unless configuration.effects_enabled?
+          if options.fetch(:effect_envelopes)
+            @err.puts("rigor sig-gen: --effect-envelopes needs the `effects:` opt-in in .rigor.yml; " \
+                      "no effect annotation was emitted.")
+          end
+          return nil
+        end
+
+        require_relative "check_runner_factory"
+        # Through the same factory `rigor check` and `rigor doctor` use, so the LRU cap, the worker
+        # resolution and the tolerated-effects switch cannot drift from the command whose cache this run
+        # shares. `workers: 0` because a collecting run is pinned to the sequential path anyway, and
+        # `--no-cache` mirrors `rigor check`'s flag of the same name.
+        runner = CheckRunnerFactory.build(
+          configuration: configuration,
+          options: { no_cache: options.fetch(:no_cache), explain: false, stats: false, workers: 0 },
+          buffer: nil, cache_root: configuration.cache_path
+        )
+        runner.run((configuration.paths + paths).uniq)
+        SigGen::EffectAnnotation::Annotator.new(
+          table: runner.effect_table, envelopes: options.fetch(:effect_envelopes),
+          envelope_index: runner.effect_envelopes, config_envelopes: config_envelopes(configuration)
+        )
+      end
+
+      # The project's `effects.envelopes:` entries, for gate 0's `match:` half. Built with a plain
+      # registry rather than the run's: gate 0 asks only WHETHER an entry selects this class, never what
+      # it bounds, so the vocabulary a plugin would add cannot change the answer.
+      def config_envelopes(configuration)
+        Effects::ConfigEnvelopes.build(
+          entries: configuration.effects_envelopes,
+          registry: Effects::Registry.for_configuration(configuration)
+        )
+      rescue StandardError
+        []
+      end
+
+      # The withheld half of the emission, counted the way {#report_skipped} counts a skip: a method that
+      # did NOT get `%a{pure}` is the interesting case for a reader who expected one, and silence would
+      # read as "sig-gen does not do this" rather than "this method did not earn it".
+      def report_withheld_annotations(candidates, options)
+        return unless options.fetch(:format) == "text"
+
+        counts = candidates.each_with_object(Hash.new(0)) do |candidate, acc|
+          reason = candidate.effect_reason
+          acc[reason] += 1 if reason && reason != :emitted
+        end
+        return if counts.empty?
+
+        breakdown = counts.map { |reason, n| "#{SigGen::EffectAnnotation::DIAGNOSTIC_IDS.fetch(reason)}: #{n}" }
+        @err.puts(
+          "rigor sig-gen: withheld an effect annotation from #{counts.values.sum} method(s) " \
+          "(#{breakdown.join(', ')}). An annotation is enforced once written, so it is emitted only " \
+          "from an exhaustive, undischarged summary."
+        )
+      end
+
       # Issue #778 — one stderr line per run saying how many methods the generator declined and why, so a
       # method missing from the output is never a silent absence. Text mode only: under `--format=json` every
       # skipped row is already in the payload with its `skip_reason`, and stderr stays clean for the consumer.
@@ -90,6 +171,18 @@ module Rigor
         )
       end
 
+      # ADR-112 WD4 — `sig_gen.inline_declared: skip` leaving methods out is the project's own choice, not a
+      # method sig-gen "could not type or would not overwrite", so it is counted on a line of its own.
+      def report_inline_declared(candidates, options)
+        return unless options.fetch(:format) == "text"
+
+        count = candidates.count { |c| c.skip_reason == :inline_declared }
+        return if count.zero?
+
+        @err.puts("rigor sig-gen: left #{count} method(s) declared inline out of sig/, as " \
+                  "`sig_gen.inline_declared: skip` asks (sig.skipped.inline-declared).")
+      end
+
       # A method whose rendered RBS does not parse is a Rigor rendering defect, not a fact about the user's
       # code — the generator skipped it (so the rest of the signatures are still usable and still valid), but
       # staying silent would leave the user with a quietly incomplete `sig/` and us with an unreported bug.
@@ -137,30 +230,99 @@ module Rigor
 
       # @return exit status — non-zero when a file the user asked to write could not be written.
       def dispatch_write(candidates, configuration, options)
-        layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
-        path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)
-        writer = SigGen::Writer.new(path_mapper: path_mapper, overwrite: options.fetch(:overwrite))
-
-        results = writer.write_all(candidates)
+        results = build_writer(configuration, options).write_all(candidates)
 
-        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
-        # A refused write (an assembled file that does not parse, or an existing target that is not valid
-        # UTF-8) means the user asked for a write and did not get one, so the command must not report
-        # success — a green `sig-gen --write` in CI would otherwise mean nothing.
+        refused = refused_candidates(candidates)
+        SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format), refused: refused)
+        SigGen::Renderer.refusal_lines(refused).each { |line| @err.puts(line) }
+        # A refused write (an assembled file that does not parse, an existing target that is not valid UTF-8,
+        # or a method whose inline and `sig/` declarations disagree without `--overwrite`) means the user asked for a
+        # write and did not get one, so the command must not report success — a green `sig-gen --write` in CI
+        # would otherwise mean nothing.
         refusals = %i[skipped_invalid_rbs skipped_invalid_encoding]
-        results.any? { |result| refusals.include?(result.action) } ? 1 : 0
+        results.any? { |result| refusals.include?(result.action) } || !refused.empty? ? 1 : 0
+      end
+
+      # ADR-112 WD4 — the methods whose inline and `sig/` declarations disagree, refused because the run did not
+      # pass `--overwrite`. Unlike every other skip, `sig/` contradicts the source while one stands.
+      def refused_candidates(candidates)
+        candidates.select { |candidate| candidate.skip_reason == :inline_differs }
+      end
+
+      # ADR-112 WD4 — the same writer as {#dispatch_write}, flags included, in dry-run mode. Defined by what
+      # `--write` would do rather than by whether `--diff` prints anything: a tighter return against an existing
+      # declaration is a proposal `--write` declines without `--overwrite`, and a gate that counted it could
+      # never pass on a project that reviewed it and said no. With `--overwrite` it counts, because `--write
+      # --overwrite` would apply it.
+      #
+      # @return 1 when `sig/` is out of date (or a write would be refused), 0 when it is current.
+      def dispatch_check(candidates, configuration, options)
+        results = build_writer(configuration, options, dry_run: true).write_all(candidates)
+        refused = refused_candidates(candidates)
+        SigGen::Renderer.new(out: @out).render_check(results: results, format: options.fetch(:format),
+                                                     refused: refused)
+        stale = SigGen::Renderer.out_of_date(results)
+        return 0 if stale.empty? && refused.empty?
+
+        report_check_failure(stale, refused) if options.fetch(:format) == "text"
+        1
+      end
+
+      def report_check_failure(stale, refused)
+        unless stale.empty?
+          @err.puts("rigor sig-gen --check: #{stale.size} signature file(s) out of date; " \
+                    "run `rigor sig-gen --write` with the same options to update them.")
+        end
+        return if refused.empty?
+
+        @err.puts("rigor sig-gen --check: #{refused.size} method(s) whose inline declaration and sig/ copy " \
+                  "disagree; make them agree, or pass --overwrite to replace the sig/ member.")
+      end
+
+      def build_writer(configuration, options, dry_run: false)
+        layout_index = SigGen::LayoutIndex.new(signature_paths: configuration.signature_paths)
+        path_mapper = SigGen::PathMapper.new(configuration: configuration, layout_index: layout_index)
+        SigGen::Writer.new(path_mapper: path_mapper, overwrite: options.fetch(:overwrite), dry_run: dry_run)
       end
 
       # Slice 3 — collect call-site argument observations when `--params=observed` is set. When `--observe=PATH` is not
-      # specified, default to `spec/` (skipped silently when the directory is absent).
+      # specified, observe the project's test roots: `test_paths:`, or whichever of `spec/` and `test/` exist. With no
+      # root at all the run still succeeds, but says so — otherwise every parameter stays `untyped` with nothing
+      # naming the reason.
       def collect_observations(configuration, options)
         return {} if options.fetch(:params) != "observed"
 
         observe_paths = options.fetch(:observe)
-        observe_paths = ["spec"] if observe_paths.empty? && File.directory?("spec")
+        observe_paths = configuration.resolved_test_paths if observe_paths.empty?
+        if observe_paths.empty?
+          warn_no_test_roots(configuration)
+        else
+          warn_missing_test_roots(observe_paths)
+        end
         SigGen::ObservationCollector.new(configuration: configuration, paths: observe_paths).collect
       end
 
+      # A declared root that does not exist is read as empty, so name it: `sig-gen` is the only command that reads
+      # the test roots, and without this the run looks exactly like one whose tests pass no typed arguments.
+      def warn_missing_test_roots(observe_paths)
+        missing = observe_paths.reject { |path| File.exist?(path) }
+        return if missing.empty?
+
+        consequence = missing.size == observe_paths.size ? "; every parameter stays untyped" : ""
+        @err.puts("rigor sig-gen: no call sites are observed from #{missing.map(&:inspect).join(', ')}, " \
+                  "which does not exist#{consequence}. Check `test_paths:` or --observe=PATH.")
+      end
+
+      def warn_no_test_roots(configuration)
+        reason = if configuration.test_paths.nil?
+                   "no spec/ or test/ directory was found and `test_paths:` is unset"
+                 else
+                   "`test_paths:` is empty"
+                 end
+        @err.puts("rigor sig-gen: --params=observed has no test roots to observe (#{reason}); every parameter " \
+                  "stays untyped. Declare `test_paths:` in the configuration or pass --observe=PATH.")
+      end
+
       def parse_options
         options = {
           mode: "print",
@@ -170,6 +332,8 @@ module Rigor
           overwrite: false,
           observe: [],
           include_private: false,
+          effect_envelopes: false,
+          no_cache: false,
           config: nil
         }
         build_option_parser(options).parse!(@argv)
@@ -181,23 +345,33 @@ module Rigor
         nil
       end
 
-      def build_option_parser(options) # rubocop:disable Metrics/AbcSize
+      def build_option_parser(options) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         OptionParser.new do |opts| # rubocop:disable Metrics/BlockLength
           opts.banner = USAGE
-          opts.on("--print", "Write RBS skeletons to stdout (default)") { options[:mode] = "print" }
-          opts.on("--diff", "Write a unified diff against existing RBS") { options[:mode] = "diff" }
-          opts.on("--write", "Write generated RBS to sig/<path>.rbs files") { options[:mode] = "write" }
-          opts.on("--overwrite", "Allow tighter-return updates to replace user-authored RBS") do
+          opts.on("--print", "Write RBS skeletons to stdout (default)") { select_mode(options, "print") }
+          opts.on("--diff", "Write a unified diff against existing RBS") { select_mode(options, "diff") }
+          opts.on("--write", "Write generated RBS to sig/<path>.rbs files") { select_mode(options, "write") }
+          opts.on("--check", "Exit 1 when --write would change sig/; write nothing") { select_mode(options, "check") }
+          opts.on("--overwrite", "Allow tighter-return updates, and inline declarations that disagree with sig/, " \
+                                 "to replace user-authored RBS") do
             options[:overwrite] = true
           end
           opts.on("--include-private", "Emit private / protected instance methods (default: public only)") do
             options[:include_private] = true
           end
+          opts.on("--effect-envelopes", "Also emit %a{rigor:v1:effect ...} for effectful methods " \
+                                        "(requires the effects: opt-in)") do
+            options[:effect_envelopes] = true
+          end
+          opts.on("--no-cache", "Do not read or write the analysis cache (effect collection only)") do
+            options[:no_cache] = true
+          end
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
           opts.on("--params=POLICY", "Parameter policy: untyped (default), observed, observed-strict") do |value|
             options[:params] = value
           end
-          opts.on("--observe=PATH", "Directory / file to scan for call-site observations (repeatable)") do |value|
+          opts.on("--observe=PATH", "Directory / file to scan for call-site observations (repeatable; " \
+                                    "default: the configured test_paths)") do |value|
             options[:observe] << value
           end
           opts.on("--new-files", "Emit only new-file classifications") do
@@ -213,12 +387,19 @@ module Rigor
         end
       end
 
+      # A second, different mode flag is a usage error rather than last-one-wins: `--check --write` must not
+      # quietly write in a CI job that meant to gate, nor `--write --check` quietly not.
+      def select_mode(options, mode)
+        options[:mode] = options[:mode_given] && options[:mode] != mode ? "conflict" : mode
+        options[:mode_given] = true
+      end
+
       def validation_error(options)
         mode = options.fetch(:mode)
         format = options.fetch(:format)
         params = options.fetch(:params)
 
-        return "--print, --diff, and --write are mutually exclusive flags; pick one" unless VALID_MODES.include?(mode)
+        return "--print, --diff, --write, and --check are mutually exclusive flags; pick one" if mode == "conflict"
         return "unsupported --format=#{format}" unless VALID_FORMATS.include?(format)
         return "unsupported --params=#{params}" unless VALID_PARAM_POLICIES.include?(params)
         if params == "observed-strict"

data/lib/rigor/cli/skill_command.rb

@@ -74,7 +74,7 @@ module Rigor
 
       # The bundled skills live at `<gem_root>/skills/`. From `lib/rigor/cli/skill_command.rb` that is three directories
       # up.
-      SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
+      SKILLS_ROOT = File.expand_path("../../../skills", __dir__).freeze
 
       # @return CLI exit status.
       def run

data/lib/rigor/cli/skill_describe.rb

@@ -148,7 +148,6 @@ module Rigor
         @deep = deep
       end
 
-      # @return the full describe report.
       def render
         catalog = catalog_skills
         state = ProjectStateProbe.new(@root).to_h