rigortype 0.2.9 → 0.3.1

data/docs/manual/04-diagnostics.md

@@ -41,18 +41,26 @@ carries no `documentation_url`.
 | <a id="rule-call-wrong-arity"></a>`call.wrong-arity` | The positional-argument count matches no signature. | high |
 | <a id="rule-call-argument-type-mismatch"></a>`call.argument-type-mismatch` | An argument's type provably violates the parameter contract. | high |
 | <a id="rule-call-possible-nil-receiver"></a>`call.possible-nil-receiver` | The receiver is `T \| nil` and the method is not defined on `NilClass`. | high |
+| <a id="rule-call-raise-non-exception"></a>`call.raise-non-exception` | A `raise` / `fail` argument's concrete type is provably not an Exception class, an Exception instance, a String, or an object defining `#exception` — a runtime `TypeError`. | high |
 | <a id="rule-call-unresolved-toplevel"></a>`call.unresolved-toplevel` | A top-level implicit-self call resolves against no same-file `def`, `pre_eval:` patch, or `Kernel` / `Object` method. | low |
 | <a id="rule-flow-always-raises"></a>`flow.always-raises` | The expression provably raises on every reachable path. | high |
 | <a id="rule-flow-unreachable-branch"></a>`flow.unreachable-branch` | An `if` / `unless` / ternary branch is statically dead. | high |
 | <a id="rule-flow-always-truthy-condition"></a>`flow.always-truthy-condition` | A condition is provably always truthy or always falsey. | medium |
 | <a id="rule-flow-dead-assignment"></a>`flow.dead-assignment` | A local is written but never read in the same method. | medium |
 | <a id="rule-flow-unreachable-clause"></a>`flow.unreachable-clause` | A `case`/`when` or `case`/`in` clause is statically dead — its subject type is disjoint with the pattern, or a prior clause already exhausted the subject. | medium |
+| <a id="rule-flow-duplicate-hash-key"></a>`flow.duplicate-hash-key` | A Hash literal repeats a literal key (symbol, plain string, integer, float, `true`/`false`/`nil`) — the last entry silently overwrites the earlier one at runtime. Literal keys only; symbol vs string and `1` vs `1.0` never collide, and interpolated / constant / computed keys are never compared. A `**splat` between two identical literal keys does not rescue the pair. | high |
+| <a id="rule-flow-return-in-ensure"></a>`flow.return-in-ensure` | An explicit `return` inside an `ensure` clause — it overrides the method's in-flight return value and silently swallows any in-flight exception. A `return` in a nested `def`, lambda, or `define_method` block inside the `ensure` does not fire (it exits that inner frame). | high |
+| <a id="rule-flow-shadowed-rescue-clause"></a>`flow.shadowed-rescue-clause` | A `rescue` clause can never run because an earlier clause of the same chain already catches a superclass (or the same class) of every exception class it names. | high |
 | <a id="rule-def-return-type-mismatch"></a>`def.return-type-mismatch` | The method body's result violates its declared RBS return type. | medium |
 | <a id="rule-def-ivar-write-mismatch"></a>`def.ivar-write-mismatch` | An instance variable is written with a type disagreeing with its first write. | high |
 | <a id="rule-def-method-visibility-mismatch"></a>`def.method-visibility-mismatch` | An explicit-receiver call reaches a private method. | high |
 | <a id="rule-def-override-visibility-reduced"></a>`def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor. | high |
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
+| <a id="rule-static-value-use-void"></a>`static.value-use.void` | A value recovered from an author-declared `-> void` return is used in value context (an assignment right-hand side, a call receiver, or a call argument). Off by default; reaches a run only through the `use-of-void-value` bleeding-edge feature (ADR-100). A bare-statement `void` call and a legitimate `top` value both stay silent. | high |
+| <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
+| <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
+| <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |
 | <a id="rule-rbs_extended-unsatisfied-conformance"></a>`rbs_extended.unsatisfied-conformance` | A class declares `%a{rigor:v1:conforms-to _Interface}` in its RBS but is missing a method the interface requires. Presence-based: only definitively-absent required methods fire. | — |
 | <a id="rule-assert-type-mismatch"></a>`assert.type-mismatch` | An `assert_type` expectation does not match the inferred type. | high |
 | <a id="rule-dump-type"></a>`dump.type` | A `dump_type` call — informational, prints the inferred type. | — |
@@ -89,7 +97,21 @@ re-stamps it for the run. Three profiles, set with the
 | --- | --- |
 | `lenient` | Only proven diagnostics are errors; uncertain ones drop to `warning` / `info`. For incremental adoption on legacy code. |
 | `balanced` *(default)* | Most rules `error`; `dump.type` `info`; uncertain rules `warning`. |
-| `strict` | Nearly every rule is an `error` — the exceptions are `call.self-undefined-method` (stays `off`, opt-in only) and `flow.unreachable-clause` (`warning`, pending its false-positive gate). CI-friendly. |
+| `strict` | Nearly every rule is an `error`. The exceptions: `call.self-undefined-method` and `static.value-use.void` stay `off` (both opt-in only), `flow.unreachable-clause` stays `warning` pending its false-positive gate, and the three `suppression.*` rules stay `warning` — a stale suppression comment is worth telling you about, but it is not a reason to fail a build. CI-friendly. |
+
+Under `balanced`, the rules that do **not** emit as `error`
+are:
+
+| Severity | Rules |
+| --- | --- |
+| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker` |
+| `info` | `flow.unreachable-clause`, `dump.type` |
+| `off` | `call.self-undefined-method`, `static.value-use.void` |
+
+Everything else emits as `error`. For one rule under all three
+profiles, `rigor explain <rule>` prints `Authored severity:` and
+`Severity by profile:` — that output is generated from the rule
+catalogue itself, so it is the per-rule source of truth.
 
 For finer control, `severity_overrides:` maps a rule ID or a
 family to one of `error`, `warning`, `info`, or `off`:
@@ -101,7 +123,15 @@ severity_overrides:
   call: warning
 ```
 
-A rule-specific override beats a family override.
+A rule-specific override beats a family override. `off` drops
+the diagnostic from the result entirely, which makes
+`severity_overrides:` the lighter-touch sibling of `disable:`
+below — both silence a rule; the override reads as "this one
+rule, at this severity" alongside the rest of the profile.
+
+YAML reserves the bareword `off` as a boolean. If an override
+that names it seems not to apply, quote it — `"off"` — and the
+same for `on`.
 
 ## Machine-readable output (`--format json`)
 
@@ -190,11 +220,36 @@ config.merge(extra)  # rigor:disable call.undefined-method
 ```
 
 It accepts qualified IDs, family wildcards (`call`), a
-comma- or space-separated list, or `all`.
+comma- or space-separated list, or `all`. The comment must sit
+on the line the diagnostic points at; there is no
+`disable-block` form, so an expression spread over several
+lines needs the comment on each line that fires.
+
+A marker that cannot work is flagged rather than silently
+ignored: a token that names no known rule (a typo like
+`call.undefined-metod`) fires
+[`suppression.unknown-rule`](#rule-suppression-unknown-rule),
+a bare marker with no rules at all fires
+[`suppression.empty`](#rule-suppression-empty), and a marker
+word outside Rigor's grammar (the RuboCop reflex
+`# rigor:disable-next-line <rule>`, or `# rigor:enable`)
+fires
+[`suppression.unknown-marker`](#rule-suppression-unknown-marker)
+— all `:warning` in every profile. Tokens under the `plugin.`
+prefix are never flagged (plugin rule vocabularies load
+dynamically), and the surveillance diagnostics are themselves
+suppressible like any other rule.
 
 **In-source, whole file.** `# rigor:disable-file <rules>`
 anywhere in a file suppresses those rules for every line;
-`# rigor:disable-file all` silences the file.
+`# rigor:disable-file all` silences the file. Convention is to
+put it near the top — typically on a generated file, a fixture,
+or a vendored snippet — but every comment in the file is
+scanned, so any placement works.
+
+The three layers **compose**: a file-scope marker does not
+cancel a line-scope one, and a project-wide `disable:` still
+applies to a file that carries neither.
 
 **Project-wide.** The `disable:` config key turns rules off
 across the whole run:

data/docs/manual/06-baseline.md

@@ -4,7 +4,11 @@ A **baseline** records the diagnostics a project already has,
 so `rigor check` can stay silent about them and surface only
 what is *new*. It is the pragmatic on-ramp for adopting Rigor
 on an existing codebase: you do not have to reach zero
-diagnostics before the check becomes useful in CI.
+diagnostics before the check becomes useful in CI. It is also
+what the [`rigor-project-init` skill](08-skills.md) snapshots
+for you at onboarding
+([ADR-22](../adr/22-baseline-and-project-onboarding.md) is the
+design).
 
 ## The baseline file
 
@@ -89,6 +93,36 @@ unless you specifically need per-message discrimination, and
 expect to `regenerate` a `message`-mode baseline after upgrading
 Rigor.
 
+## The ad-hoc form — `rigor diff`
+
+A managed baseline is not the only way to fail CI on *new*
+diagnostics only. The lightweight alternative keeps a plain JSON
+snapshot in the repository and compares against it explicitly:
+
+```sh
+# Once: capture the current diagnostic surface.
+rigor check --format=json > rigor.baseline.json
+git add rigor.baseline.json
+
+# Per PR: compare against the committed snapshot.
+rigor diff rigor.baseline.json
+```
+
+[`rigor diff`](02-cli-reference.md#rigor-diff) prints a `+ NEW`
+row for every diagnostic absent from the snapshot and a
+`- FIXED` row for every one resolved since, and exits `1` when
+anything is new — so a PR that adds a violation fails while the
+recorded legacy ones stay quiet. `--format=json` is available
+for editor and dashboard integrations. Regenerate the snapshot
+with the same `rigor check --format=json` redirection whenever
+you fix a row, and the project tightens monotonically.
+
+The difference from a managed baseline is where the knowledge
+lives: `rigor diff` is a separate step your CI script has to
+run, while a `baseline:` file makes `rigor check` itself exit
+clean on recorded diagnostics. Prefer the managed form unless
+you specifically want the raw JSON snapshot.
+
 ## Working a baseline down
 
 `rigor triage` summarises a diagnostic stream — rule

data/docs/manual/07-plugins.md

@@ -40,10 +40,10 @@ each plugin's options — but the families today are:
 - **Rails** — `rigor-activerecord`, `rigor-actionpack`,
   `rigor-rails-routes`, `rigor-rails-i18n`,
   `rigor-actionmailer`, `rigor-activejob`,
-  `rigor-activestorage`, `rigor-actioncable`. The
-  `rigor-rails` meta-gem bundles the Rails set for Gemfile
-  convenience; you still enumerate the individual plugins you
-  want under `plugins:`.
+  `rigor-activestorage`, `rigor-actioncable`. Enumerate the ones
+  you want under `plugins:` — there is no umbrella entry that
+  turns on the Rails set as a group
+  ([ADR-96](../adr/96-plugin-target-gems.md) WD3 proposes one).
 - **Testing** — `rigor-rspec`, `rigor-rspec-rails`,
   `rigor-minitest`, `rigor-shoulda-matchers`,
   `rigor-factorybot`.

data/docs/manual/08-skills.md

@@ -106,6 +106,7 @@ source checkout. The `rigor skill` command surfaces them:
 
 ```sh
 rigor skill describe        # probe the project + recommend the next skill (alias: rigor describe)
+rigor skill describe --deep # same, but run `rigor check` first and route on its result
 rigor skill --list          # name + absolute path for each bundled skill
 rigor skill <name>          # print the SKILL.md body (with a references/ header)
 rigor skill --full <name>   # the body + every references/*.md inline (complete procedure)
@@ -113,7 +114,11 @@ rigor skill --path <name>   # one-line absolute SKILL.md path, for a file-readin
 ```
 
 `rigor skill describe` is the recommendation engine driven by
-`rigor-next-steps`; `rigor skill rigor-project-init` is the
+`rigor-next-steps`. It is a presence-only probe by default — cheap and
+side-effect-free; add `--deep` when you want the recommendation to come
+from a real analysis instead
+([CLI reference](02-cli-reference.md#describe---deep)).
+`rigor skill rigor-project-init` is the
 canonical way to hand an agent the onboarding workflow without pointing
 it at the repository. The `list` / `print` / `path` verb spellings are
 deprecated (removed in v0.3.0). See [CLI reference](02-cli-reference.md#rigor-skill).

data/docs/manual/09-editor-integration.md

@@ -18,6 +18,7 @@ design + capability matrix lives in
 
 | LSP method | Behaviour |
 |---|---|
+| `textDocument/didOpen` / `didChange` / `didClose` | Incremental sync (`TextDocumentSyncKind::Incremental`): a `didChange` carries range edits, which are spliced into the buffer the server already holds instead of re-sending and re-parsing the whole document on every keystroke. Positions are read as UTF-16 code-unit offsets (`positionEncoding: "utf-16"`), so an emoji or other non-BMP character counts as two. The full-text change form stays supported. |
 | `textDocument/publishDiagnostics` | Pushed on every `didChange`, 200ms debounced. Severity / rule / source map directly to Rigor's diagnostic taxonomy. |
 | `textDocument/hover` | Type-aware markdown. Per-node-class dispatch surfaces receiver type + RBS signature for method calls, FQN + singleton type + defined-in path for constants, narrowed type + bound-at for locals, canonical refinement names (`non-empty-string`, …) for `Refined` / `Difference` carriers. |
 | `textDocument/completion` | Method completion after `.` (driven by inferred receiver type), constant-path completion after `::`. Composite receivers (Union → intersection of methods, Tuple / HashShape → ancestor nominal, Refined → underlying nominal) handled. Parse-recovery sentinel makes mid-edit `obj.` / `Foo::` buffers work. |
@@ -201,8 +202,8 @@ For a legacy bundler-based install, swap the connection list to
   analyzer assigns the receiver.
 - Mid-edit buffer support is best-effort. If parse fails AND the
   cursor isn't right after `.` / `::`, the v1 LSP returns no
-  completions; deeper recovery is queued (see ROADMAP §
-  "Editor / IDE integration").
+  completions; deeper recovery is queued (see the open
+  [`area:editor` issues](https://github.com/rigortype/rigor/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%3Aeditor)).
 
 **Hover shows `untyped` everywhere.**
 
@@ -234,10 +235,10 @@ Cold start is dominated by RBS environment build; warm starts
 
 LSP v1 + v2 landed in v0.1.6 and ship in the `0.1.x` line. Queued
 follow-ups (`textDocument/signatureHelp`, hash-key completion,
-`textDocument/definition`, incremental `didChange` sync, Ractor
-pool dispatch, codeAction / rename / semanticTokens / inlayHint)
-are demand-driven; see ROADMAP § "Editor / IDE integration" for
-the current queue.
+`textDocument/definition`, Ractor pool dispatch,
+codeAction / rename / semanticTokens / inlayHint)
+are demand-driven; the current queue is the open
+[`area:editor` issues](https://github.com/rigortype/rigor/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%3Aeditor).
 
 To request a queued feature or report an LSP issue, open a GitHub
 issue with: the editor + version, the Rigor version

data/docs/manual/11-ci.md

@@ -246,6 +246,57 @@ updates:
 extra files — but Dependabot does not see a version inside a `run:`
 step, so updates to the pin are manual.
 
+## Persisting the analysis cache across runs
+
+By default each CI run starts cold and re-analyses everything. The
+templates leave it that way on purpose — cold runs are simple,
+deterministic, and fast enough for most projects. When the Rigor
+job's runtime starts to matter (a large codebase, many plugins),
+persist [the analysis cache](12-caching.md) between runs.
+
+**Restore and save the cache directory** with your CI's cache
+facility, keyed on anything that changes the analysis wholesale
+(the Rigor version / lockfile). That is the whole setup: Rigor
+detects CI and switches its cache freshness check from stat
+metadata (which a fresh checkout regenerates, and which would
+otherwise force parts of the restored cache to recompute every
+run) to content hashes, which are identical across checkouts.
+Details: [How a file is checked for changes](12-caching.md#how-a-file-is-checked-for-changes).
+
+GitHub Actions:
+
+```yaml
+      - uses: actions/cache@v4
+        with:
+          path: .rigor/cache
+          key: rigor-cache-${{ runner.os }}-${{ hashFiles('.github/rigor/Gemfile.lock') }}-${{ github.sha }}
+          restore-keys: rigor-cache-${{ runner.os }}-${{ hashFiles('.github/rigor/Gemfile.lock') }}-
+      - run: bundle exec rigor check
+```
+
+GitLab CI:
+
+```yaml
+rigor:
+  cache:
+    key: rigor-cache
+    paths:
+      - .rigor/cache
+```
+
+Two refinements:
+
+- A **self-hosted runner that reuses its workspace** keeps stable
+  stat metadata, so the faster stat check works there — opt back
+  into it with `cache.validation: stat`.
+- On Rigor versions before the `auto` default, set
+  `RIGOR_STRICT_VALIDATION: "1"` on the job explicitly.
+
+The cache is content-keyed and self-invalidating — a stale or
+corrupt restore degrades to a recompute, never a wrong result. If
+you would rather guarantee every run is independent, pass
+`--no-cache` instead and skip this section.
+
 ## Container image
 
 A standalone image is published to GHCR with Ruby 4.0 and Rigor

data/docs/manual/12-caching.md

@@ -38,6 +38,49 @@ The cache is also schema-versioned: after a Rigor upgrade that
 changes the cache format, the stale cache is purged on the
 first writable run.
 
+## How a file is checked for changes
+
+To decide whether a cached entry is still valid, Rigor needs to
+know which of your files changed since the entry was written. By
+default it checks each file's **stat metadata** first — size,
+nanosecond modification and change timestamps, and inode — and
+only re-hashes a file's content when that metadata moved. On a
+large project an unchanged run then reads *zero* content bytes to
+validate the cache, instead of re-hashing every file.
+
+The content hash stays the sole authority on whether a file
+actually changed: the stat check only decides whether the hash
+needs recomputing. A file that was merely `touch`ed (new
+timestamp, identical content) is re-hashed once and correctly
+found unchanged. Editing a file always moves its timestamps, so
+an edit is never missed.
+
+The stat check is skipped where it cannot work: the default
+setting is `validation: auto`, which behaves as `stat` on your
+machine and switches to hashing every file (`digest`) when a CI
+environment is detected. CI is the common case of untrustworthy
+stat metadata — a fresh checkout regenerates every timestamp and
+inode, so a cache restored across CI runs (for example with
+`actions/cache`) never passes the stat check, and parts of it
+(plugin watch-glob entries, which are stat-signature only) would
+be recomputed on every run. Content hashes are identical across
+checkouts, so under `digest` the restored cache simply hits.
+
+The setting can be forced either way:
+
+```yaml
+cache:
+  validation: digest    # hash always — for any filesystem whose
+                        # timestamps or inodes cannot be trusted
+  # validation: stat    # stat always — e.g. a self-hosted CI
+                        # runner that reuses its workspace, where
+                        # stat metadata IS stable across runs
+```
+
+For a single run, `RIGOR_STRICT_VALIDATION=1` forces `digest`
+and wins over the config key; `RIGOR_CI_DETECT=0` turns off the
+CI detection that `auto` relies on.
+
 ## Controlling the cache
 
 | Flag | Effect |
@@ -90,6 +133,28 @@ gate, `rigor check --verify-incremental`, asserts this on every
 build: it runs the incremental analyzer and a full analysis and
 fails if they disagree on a single diagnostic.
 
+Rigor is also precise about *what* an edit changed. Re-checking a
+file that many others depend on — a base class, a widely-used
+concern, a shared utility — used to re-check every dependent.
+Now, if your edit did not change the file's declaration shape
+(the signatures of its methods, its superclass and includes) or
+the types its methods return, the files that only depend on those
+things are left untouched: a comment, a formatting change, or an
+internal refactor that preserves every method's return type stops
+at the edited file. An edit that *does* change a return type or a
+signature still propagates to the dependents that consume it, so
+the result stays identical to a full run.
+
+Types contributed by plugins (a Sorbet signature, an
+ActiveRecord column type, a dry-types alias) are validated too:
+if a plugin's cross-file contributions change between runs, the
+snapshot is dropped and the next run is a full one, so a plugin
+edit can never leave a dependent stale.
+
+An `--incremental` re-check honours `--workers=N` (and
+`RIGOR_RACTOR_WORKERS` / `parallel.workers:`), analysing the
+affected files in parallel just as a full run does.
+
 The snapshot lives under the cache directory (`.rigor/cache`)
 and is keyed by a fingerprint of your configuration, your locked
 gems, your project's own `sig/` RBS, and the Rigor version.

data/docs/manual/plugins/rigor-actioncable.md

@@ -44,6 +44,30 @@ or `stream_for record`) — the absence of a literal match doesn't prove
 the stream is invalid. Non-`Channel` receivers and non-literal stream
 arguments pass through silently.
 
+## `#receive(data)` parameter typing
+
+The plugin also carries an [ADR-28](../../adr/28-path-scoped-protocol-contracts.md)
+path-scoped protocol contract: inside any `#receive(data)` defined
+under `channel_search_paths`, `data` types as `Hash` instead of
+`Dynamic[Top]`. `#receive` is ActionCable's framework-dispatched
+catch-all action — invoked with the decoded JSON payload when an
+incoming message carries no `"action"` key — so the parameter shape is
+uniform across every channel.
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  def receive(data)
+    data["body"]           # data: Hash
+    data.no_such_method    # error: call.undefined-method
+  end
+end
+```
+
+Custom action methods (`def speak(data)`) are not covered — their
+names are project-chosen, and a protocol contract names a single fixed
+method. Only `#receive` is a reserved, uniformly-shaped hook.
+
 ## Configuration
 
 ```yaml
@@ -54,6 +78,11 @@ plugins:
       channel_base_classes: ["ApplicationCable::Channel", "ActionCable::Channel::Base"] # default
 ```
 
+`channel_search_paths` also retargets the `#receive` protocol
+contract's glob — including for multiple configured roots — so a
+custom channel directory gets the same `data: Hash` typing as the
+default.
+
 ## Limitations
 
 - **Direct-superclass match only.** An indirect chain (`AdminChannel <
@@ -68,6 +97,9 @@ plugins:
   than directly in the channel body) is out of scope.
 - **Bare `broadcast(...)`** without an explicit `ActionCable.server`
   receiver is skipped to avoid false positives on unrelated methods.
+- **The `#receive` contract is path-scoped, not class-scoped** (ADR-28):
+  any `def receive(data)` defined anywhere under `channel_search_paths`
+  is typed, even on a class that isn't an ActionCable channel.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-devise.md

@@ -64,7 +64,9 @@ The macro manifest (the trait registry mapping each strategy to its
 module), the concern re-targeting walk, the demo, and the
 contract surfaces this plugin exercises are in the
 [plugin's README](../../../plugins/rigor-devise/README.md);
-[handbook chapter 9](../../handbook/09-plugins.md) covers the Tier B
-macro substrate generally. To write a plugin, see
+[`docs/internal-spec/macro-substrate.md`](../../internal-spec/macro-substrate.md)
+specifies the Tier B trait registry generally, and
+[handbook chapter 9](../../handbook/09-plugins.md) is the
+orientation. To write a plugin, see
 [`examples/`](../../../examples/README.md) and the
 [`rigor-plugin-author`](../08-skills.md) skill.

data/lib/rigor/analysis/check_rules/always_truthy_condition_collector.rb

@@ -2,6 +2,9 @@
 
 require "prism"
 
+require_relative "../../source/node_children"
+require_relative "inferred_param_guard"
+
 module Rigor
   module Analysis
     module CheckRules
@@ -81,7 +84,7 @@ module Rigor
           visit(node) if conditional_node?(node) && !in_loop_or_block
 
           child_in_loop_or_block = in_loop_or_block || enters_loop_or_block?(node)
-          node.compact_child_nodes.each { |child| walk(child, in_loop_or_block: child_in_loop_or_block) }
+          node.rigor_each_child { |child| walk(child, in_loop_or_block: child_in_loop_or_block) }
         end
 
         def conditional_node?(node)
@@ -100,6 +103,11 @@ module Rigor
           scope = @scope_index[node]
           return if scope.nil?
 
+          # ADR-67 WD6b — a predicate rooted at an inferred parameter (`opts.key?(:x)`) folds to a constant only
+          # because the seed's lower-bound type pinned it; a wider real caller would not. Declining preserves
+          # the precision-additive contract.
+          return if InferredParamGuard.rooted?(predicate, scope)
+
           predicate_type = scope.type_of(predicate)
           return unless predicate_type.is_a?(Type::Constant)
 

data/lib/rigor/analysis/check_rules/dead_assignment_collector.rb

@@ -2,6 +2,8 @@
 
 require "prism"
 
+require_relative "../../source/node_children"
+
 module Rigor
   module Analysis
     module CheckRules
@@ -65,7 +67,7 @@ module Rigor
           return unless node.is_a?(Prism::Node)
 
           collect_def_assignments(node) if node.is_a?(Prism::DefNode)
-          node.compact_child_nodes.each { |child| walk_for_def_nodes(child) }
+          node.rigor_each_child { |child| walk_for_def_nodes(child) }
         end
 
         def collect_def_assignments(def_node)
@@ -92,7 +94,7 @@ module Rigor
           # / similar shapes don't trip the rule.
           accumulator << node.name if reading_assignment?(node)
 
-          node.compact_child_nodes.each { |child| gather_read_names(child, accumulator) }
+          node.rigor_each_child { |child| gather_read_names(child, accumulator) }
           accumulator
         end
 
@@ -110,7 +112,7 @@ module Rigor
           # outer walker visits them separately.
           return accumulator if node.is_a?(Prism::DefNode) && !accumulator.last.equal?(node)
 
-          node.compact_child_nodes.each { |child| gather_write_nodes(child, accumulator) }
+          node.rigor_each_child { |child| gather_write_nodes(child, accumulator) }
           accumulator
         end
 

data/lib/rigor/analysis/check_rules/duplicate_hash_key_collector.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../source/node_children"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # Walks a parse tree and collects every Hash-literal entry whose LITERAL key repeats an earlier
+      # literal key in the same literal. Ruby's runtime keeps the LAST entry silently (the interpreter
+      # itself only warns under `-w`), so the earlier value is dead — almost always a copy-paste or merge
+      # leftover. Modeled on PHPStan's `DuplicateKeysInLiteralArraysRule`.
+      #
+      # The collector is the read-side companion to the `flow.duplicate-hash-key` rule. The envelope is
+      # purely syntactic and deliberately narrow so it cannot fire on working code:
+      #
+      # - Only keys whose VALUE is pinned at parse time participate: symbols (including the `key:`
+      #   shorthand and the `:key =>` hashrocket spelling of the same symbol), plain non-interpolated
+      #   strings, integers, floats, and the `true` / `false` / `nil` literals. Any other key form —
+      #   interpolated strings/symbols, constants, method calls, locals — is never compared and never
+      #   fires.
+      # - Key spaces are tagged by literal kind, matching `Hash`'s `eql?`-based lookup: `:a` and `"a"`
+      #   are different keys, and `1` and `1.0` are different keys (`1.eql?(1.0)` is false), so Integer
+      #   and Float literals are never cross-compared.
+      # - A `**splat` element is itself never a key, and it does NOT rescue a literal duplicate around
+      #   it: in `{ a: 1, **h, a: 2 }` the second `a:` overwrites whatever the earlier entries (literal
+      #   or splatted) contributed, so the pair still collides and still fires.
+      # - Both `Prism::HashNode` (braced literals) and `Prism::KeywordHashNode` (bare keyword arguments,
+      #   `m(a: 1, a: 2)` — Prism parses these with only a `-w`-level warning, same as braced literals)
+      #   are scanned. Each literal is scanned independently; nested Hash literals are their own scope.
+      class DuplicateHashKeyCollector
+        # ADR-53 Track B — the node classes the shared {RuleWalk} dispatches to this collector. Prism node
+        # classes are leaves, so class-equality dispatch matches the legacy walk's `is_a?` gate. The
+        # collector needs no context gate: it is purely syntactic and fires wherever the full DFS reaches
+        # a Hash literal, loops and blocks included.
+        NODE_CLASSES = [Prism::HashNode, Prism::KeywordHashNode].freeze
+
+        # Returns `Array<{hash_node:, key_node:, first_key_node:, key_label:}>` — one entry per LATER
+        # occurrence of a repeated literal key (`key_node` is the repeat the diagnostic points at;
+        # `first_key_node` is the earliest occurrence its message references). Empty when the tree has no
+        # qualifying duplicates.
+        def initialize(scope_index)
+          @scope_index = scope_index
+          @results = []
+        end
+
+        # Legacy single-collector walk — kept as the oracle the ADR-53 Track B equivalence harness
+        # compares {RuleWalk} against.
+        def collect(root)
+          walk_for_hash_nodes(root)
+          @results.freeze
+        end
+
+        # {RuleWalk} entry point: the legacy walk's per-literal logic, invoked at every Hash literal under
+        # the shared traversal contract. The `context` is unused — this collector processes all literals.
+        def visit(hash_node, _context = nil)
+          collect_duplicate_keys(hash_node)
+        end
+
+        # The accumulated result, frozen the same way `#collect` returns it — used by {RuleWalk}-driven
+        # callers after the walk completes.
+        def results
+          @results.freeze
+        end
+
+        private
+
+        def walk_for_hash_nodes(node)
+          return unless node.is_a?(Prism::Node)
+
+          collect_duplicate_keys(node) if node.is_a?(Prism::HashNode) || node.is_a?(Prism::KeywordHashNode)
+          node.rigor_each_child { |child| walk_for_hash_nodes(child) }
+        end
+
+        def collect_duplicate_keys(hash_node)
+          seen = {}
+          hash_node.elements.each do |element|
+            # `**splat` elements (AssocSplatNode) contribute no literal key; they are skipped WITHOUT
+            # resetting `seen` — a splat between two identical literal keys does not rescue the collision.
+            next unless element.is_a?(Prism::AssocNode)
+
+            key = literal_key(element.key)
+            next if key.nil?
+
+            first = seen[key]
+            if first
+              @results << {
+                hash_node: hash_node,
+                key_node: element.key,
+                first_key_node: first,
+                key_label: key_label(element.key)
+              }
+            else
+              seen[key] = element.key
+            end
+          end
+        end
+
+        # Maps a key node to a comparable `[kind, value]` tag, or nil for any non-value-pinned key form.
+        # The kind tag keeps the literal spaces separate (`:a` ≠ `"a"`, `1` ≠ `1.0`); within a kind the
+        # parsed Ruby value is compared under Hash's own `eql?`/`hash` semantics, exactly reproducing the
+        # runtime collision.
+        def literal_key(key_node)
+          case key_node
+          when Prism::SymbolNode then [:symbol, key_node.unescaped]
+          when Prism::StringNode then [:string, key_node.unescaped]
+          when Prism::IntegerNode then [:integer, key_node.value]
+          when Prism::FloatNode then [:float, key_node.value]
+          when Prism::TrueNode then [:true_literal]
+          when Prism::FalseNode then [:false_literal]
+          when Prism::NilNode then [:nil_literal]
+          end
+        end
+
+        # Renders the key for the diagnostic message in its canonical Ruby spelling, so the `a:` shorthand
+        # and `:a =>` hashrocket occurrences of one symbol read as the same key.
+        def key_label(key_node)
+          case key_node
+          when Prism::SymbolNode then ":#{key_node.unescaped}"
+          when Prism::StringNode then key_node.unescaped.inspect
+          else key_node.slice
+          end
+        end
+      end
+    end
+  end
+end