rigortype 0.2.1 → 0.2.3

data/docs/handbook/08-understanding-errors.md

@@ -0,0 +1,373 @@
+# Understanding errors
+
+This chapter is the catalogue of diagnostics Rigor ships, the
+families they belong to, and how to suppress one when it is
+wrong (or move its severity around). It is the page to land on
+when a diagnostic surprises you, in either direction.
+
+## Anatomy of a diagnostic
+
+```text
+lib/user.rb:42:7: error: undefined method `upcas' for "alice" [call.undefined-method]
+                  ↑      ↑                                   ↑
+                  │      │                                   └─ qualified rule
+                  │      └─ message
+                  └─ severity (error / warning / info)
+```
+
+The qualified rule (`call.undefined-method`,
+`flow.always-raises`, `def.return-type-mismatch`, …) is the
+stable identifier for the rule. Use it in:
+
+- `# rigor:disable <rule>` end-of-line suppressions in source
+- `# rigor:disable-file <rule>` file-scope suppressions
+- `severity_overrides:` in `.rigor.yml`
+- `disable:` in `.rigor.yml`
+
+Wildcards work — `# rigor:disable call` suppresses every
+`call.*` rule on that line.
+
+Need to look up what a rule does without leaving the shell?
+`rigor explain <rule>` prints the rule's summary, when it
+fires, when it doesn't, the suppression token, the authored
+severity, and the per-profile severity. `rigor explain` with
+no argument prints the index of every shipped rule.
+
+### Confidence and reference fields
+
+Two extra fields ride along on every built-in diagnostic, for
+agents and dashboards consuming `rigor check --format json`
+(and on each rule in `rigor explain --format json`):
+
+- **`evidence_tier`** — `high` / `medium` / `low`: Rigor's own
+  confidence that the firing is a true positive, derived from
+  the rule's gates, not its severity. `high` means a concrete,
+  statically-known type with no metaprogramming escape (e.g.
+  `call.undefined-method`); `medium` rests on a flow / inference
+  proof with a documented false-positive envelope (e.g.
+  `flow.always-truthy-condition`); `low` is a resolution- or
+  coverage-gap signal that often means missing context rather
+  than a bug (e.g. `call.unresolved-toplevel`). The tier never
+  feeds severity — that stays the `severity_profile:` decision.
+  Informational helpers (`dump.type`) carry no tier.
+- **`documentation_url`** — a stable link to the rule's entry in
+  the published diagnostics catalogue.
+
+Both are presentation metadata. They never change whether a
+diagnostic fires.
+
+## The rule catalogue
+
+Five families, each with one or more rules:
+
+### `call.*` — call-site rules
+
+Fire when a method call's shape is wrong.
+
+| Rule | Fires when | Default severity |
+| --- | --- | --- |
+| `call.undefined-method` | The receiver class is statically known and the method is not defined on it (RBS or in-source). | error |
+| `call.wrong-arity` | The number of positional arguments does not satisfy any overload's arity. | error |
+| `call.argument-type-mismatch` | An argument's type provably does not satisfy the parameter contract (RBS or `RBS::Extended` `param:`). | error |
+| `call.possible-nil-receiver` | The receiver type is `T \| nil` and the method is not defined on `NilClass`. | error (warning under `lenient`) |
+| `call.unresolved-toplevel` | An implicit-self call at the top level (outside any `def` / `class` / `module`) resolves against no same-file `def`, `pre_eval:` monkey-patch, or `Kernel` / `Object` method — surfacing typos in standalone scripts. | warning under `balanced`, error under `strict`, suppressed under `lenient` |
+
+`call.*` rules are the highest-volume diagnostics on
+real-world code. They are also the most refined — every one
+fires only when Rigor can prove the underlying fact.
+
+### `flow.*` — flow-analysis rules
+
+Fire when the control flow itself is unsound.
+
+| Rule | Fires when | Default severity |
+| --- | --- | --- |
+| `flow.always-raises` | Every reachable evaluation of an expression raises (e.g. `n / 0` where `n: Integer`). | error |
+| `flow.unreachable-branch` | An `if` / `unless` / ternary's predicate is a syntactic literal AND the corresponding dead branch is non-empty. | warning |
+| `flow.always-truthy-condition` | The predicate of an `if` / `unless` / ternary is provably truthy (or falsey) by inferred type, with surgical skips inside loop bodies and on defensive predicate calls. | warning |
+| `flow.unreachable-clause` | A `case <local>; when <Class>` (or bare-class `case`/`in`) clause whose subject narrowing proves it can never match — disjoint from the subject's type, or already exhausted by an earlier clause. | info under `balanced`, warning under `strict`, info under `lenient` |
+| `flow.dead-assignment` | A plain local-variable write whose target name is never read in the same `def` body. | warning |
+
+`flow.unreachable-branch`, `flow.always-truthy-condition`, and
+`flow.unreachable-clause` are the **reachability family** — each
+proves a branch or `case` clause is dead. `unreachable-clause`
+is the newest member: it watches `case <local>; when <Class>`
+(and bare-class `case`/`in`) and fires when an earlier clause
+already covered a member's type or the clause is disjoint from
+the subject. It ships at `:info` under `balanced` (one notch
+below its siblings) while its corpus false-positive gate
+finishes; bump it with `severity_overrides:` if you want it
+louder.
+
+### `def.*` — method-definition rules
+
+Fire when the body of a method violates its declared
+contract.
+
+| Rule | Fires when | Default severity |
+| --- | --- | --- |
+| `def.return-type-mismatch` | The body's last expression's inferred type cannot satisfy the RBS-declared return type. Honors `%a{rigor:v1:return: <refinement>}` overrides. | warning under `balanced` profile, error under `strict` |
+| `def.ivar-write-mismatch` | A later `@var = ...` write's concrete class disagrees with the first write's class in the same class body (NilClass-to-clear is allowlisted). | warning under `balanced` profile, error under `strict` |
+| `def.method-visibility-mismatch` | An explicit-receiver call targets a `Nominal[X]` whose discovered method is `:private` in the surrounding class body. | error |
+| `def.override-visibility-reduced` | An override reduces the visibility it inherits from a project-defined ancestor (public → protected/private, protected → private), breaking a caller that holds the supertype. | warning under `balanced`, error under `strict`, suppressed under `lenient` |
+| `def.override-return-widened` | An override's declared return widens the inherited return (covariance). Fires only on a proven violation when both sides carry an authored RBS signature. | warning under `balanced`, error under `strict`, suppressed under `lenient` |
+| `def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance), comparing matching positional parameters. Requires an authored single-overload RBS signature on both sides. | warning under `balanced`, error under `strict`, suppressed under `lenient` |
+
+The three `def.override-*` rules are the Liskov Substitution
+Principle signature rule applied across a project-defined
+class/module hierarchy (superclass chain + included/prepended
+modules, resolved cross-file). They are the conceptual subject of
+[appendix: Liskov substitution](appendix-liskov.md).
+
+### `assert.*` — runtime assertion rules
+
+| Rule | Fires when | Default severity |
+| --- | --- | --- |
+| `assert.type-mismatch` | An `assert_type("expected", value)` call's actual inferred type does not match the expected string. | error |
+
+### `dump.*` — debug helpers
+
+| Rule | Fires when | Default severity |
+| --- | --- | --- |
+| `dump.type` | `dump_type(value)` was called — emits an info diagnostic naming the inferred type. | info |
+
+`dump_type` is your introspection probe during debugging:
+sprinkle it through suspicious code, run `rigor check`, read
+the inferred types from the diagnostic stream.
+
+## Severity profiles
+
+Rigor ships three named severity profiles that re-stamp the
+shipped severities:
+
+| Profile | Behaviour |
+| --- | --- |
+| `lenient` | Most rules → `warning`; uncertain rules drop to `info`. CI-friendly for legacy code. |
+| `balanced` (default) | Most rules → `error`; `dump.type` → `info`. The shipped behaviour. |
+| `strict` | Everything → `error` including the `:warning` rules under `balanced`. Suitable for new projects with no legacy noise. |
+
+Set in `.rigor.yml`:
+
+```yaml
+severity_profile: strict
+```
+
+## Per-rule overrides
+
+Override a single rule's severity:
+
+```yaml
+severity_overrides:
+  call.argument-type-mismatch: warning
+  def.return-type-mismatch: off
+```
+
+`off` drops the diagnostic from the result entirely — useful
+when you want a profile-wide setting for most rules but
+silence one specifically.
+
+Family wildcards work in overrides too:
+
+```yaml
+severity_overrides:
+  call: warning   # demote every call.* rule
+  dump: off       # drop every dump.* rule
+```
+
+Per-rule entries beat family-wildcard entries:
+
+```yaml
+severity_overrides:
+  call: warning                    # every call.* → warning
+  call.undefined-method: error     # except undefined-method, still error
+```
+
+YAML reserves the bareword `off`. If the stripped severity
+seems not to apply, quote it: `"off"`. Same for `on`.
+
+## In-source suppression
+
+```ruby
+"hello".no_such_method  # rigor:disable call.undefined-method
+```
+
+The comment must be on the same line as the diagnostic. Use
+the qualified rule, the family wildcard, or `all`:
+
+```ruby
+"hello".no_such_method   # rigor:disable call
+"hello".no_such_method   # rigor:disable all
+```
+
+For multiline blocks, suppress at every line — Rigor does
+not yet ship a `disable-block` syntax.
+
+### File-scope suppression
+
+When you need to silence a rule everywhere in a file —
+typically a generated file, a fixture, or a vendored snippet
+that triggers a known false positive — drop a single
+`# rigor:disable-file` comment anywhere in the file:
+
+```ruby
+# rigor:disable-file call.undefined-method
+
+# This whole file is generated; the analyzer's call surface
+# is mismatched with the runtime layer for these stubs.
+```
+
+Convention is to put the comment near the top, but Rigor
+scans every comment in the file so any placement works. The
+same token forms apply: qualified rule, family wildcard, or
+`all`. The line-scope `# rigor:disable` form continues to
+work — the two compose, and any project-wide
+`disable: [...]` in `.rigor.yml` also still applies.
+
+## Project-wide suppression
+
+```yaml
+# .rigor.yml
+disable:
+  - call.possible-nil-receiver
+```
+
+Drops the rule project-wide. Heavier hammer than
+`severity_overrides: { call.possible-nil-receiver: off }` —
+both work; the choice is stylistic.
+
+## Baseline diffing for CI
+
+When you adopt Rigor on an existing codebase, you usually
+inherit a long tail of legitimate-but-pre-existing diagnostics
+that nobody is going to fix today. The pragmatic move is to
+**snapshot the current state as a baseline** and then have CI
+fail only on *new* diagnostics introduced by a PR:
+
+```sh
+# Once: capture the current diagnostic surface.
+rigor check --format=json > rigor.baseline.json
+git add rigor.baseline.json
+git commit
+
+# Per PR: compare against the committed baseline.
+rigor diff rigor.baseline.json
+```
+
+`rigor diff` prints `+ NEW` rows for each diagnostic that
+wasn't in the baseline and `- FIXED` rows for each that has
+been resolved since. The exit code is `1` when any new
+diagnostic appears and `0` otherwise — so adding a new
+violation fails CI, but the legacy diagnostics recorded in
+the baseline don't.
+
+When you fix a row in the baseline, regenerate it with the
+same `rigor check --format=json > rigor.baseline.json` so
+the project tightens monotonically over time. The
+`--format=json` form of `rigor diff` itself is also
+available for editor / dashboard integrations.
+
+`rigor diff` is the lightweight, ad-hoc form — a JSON file you
+diff by hand in a CI script. Most projects instead adopt the
+**managed baseline**: `rigor baseline generate` writes a
+`.rigor-baseline.yml`, you point at it with the `baseline:`
+config key, and from then on `rigor check` itself exits clean
+on recorded diagnostics and surfaces only new ones — no
+separate diff step. That is the path the
+[`rigor-project-init` skill](../manual/14-rails-quickstart.md)
+sets up for you; see [Baselines](../manual/06-baseline.md) for
+the full workflow ([ADR-22](../adr/22-baseline-and-project-onboarding.md)
+for the design).
+
+## Why a diagnostic might NOT fire when you expected one
+
+The most common reasons:
+
+1. **The receiver is `Dynamic[top]`.** Rigor stays silent on
+   gradual receivers. Run `rigor type-of <file>:<line>:<col>`
+   to confirm what the engine sees.
+2. **The method exists somewhere in the hierarchy.** Even one
+   matching def in any ancestor class / module silences
+   `call.undefined-method`.
+3. **The call is implicit-self inside a method body.** Rigor
+   does not flag implicit-self calls — too much noise on
+   metaprogramming-heavy code.
+4. **The literal might be empty / nil at runtime in a way the
+   analyzer cannot prove.** `s = ARGV.first; s.upcase`
+   silently passes because `s` could legitimately be a
+   non-empty string at runtime, and Rigor will not flag what
+   it cannot prove. Add an explicit guard or a `param:`
+   tightening.
+5. **The target rule is disabled by configuration.** Check
+   your `.rigor.yml` and any `# rigor:disable` comments in
+   the offending file.
+6. **The severity profile dropped it.** Under `lenient`, rules
+   that fire as `:warning` may have been further demoted to
+   `:info` and filtered out of your CI script.
+
+When in doubt, run with `--explain`:
+
+```sh
+rigor check --explain lib
+```
+
+This adds an `:info` diagnostic for every fail-soft fallback
+the engine took — every place it widened to `Dynamic[top]`
+because it could not see further. The output is noisy on
+realistic code but invaluable when "I expected a diagnostic
+here" debugging.
+
+## Why a diagnostic IS firing when you think it should not
+
+Almost always one of:
+
+1. **Rigor is right.** The classic case: a method's RBS sig
+   says `String?` but the project's runtime invariants
+   guarantee non-nil. Either fix the sig (preferred), add a
+   `RBS::Extended` `return:` directive, or add a `# rigor:disable`
+   on the line.
+2. **An RBS sig is missing or wrong.** The class lives in a
+   gem with no `.rbs`, or the project's own `sig/` is out of
+   date with the source. Update or add the sig.
+3. **A constant is being looked up wrong.** Constant
+   resolution can fall back to RBS-core or in-source class
+   discovery; if both miss, the call goes through
+   `Dynamic[top]` and you see no diagnostic, but a sibling
+   call against the wrong class might fire.
+4. **A diagnostic is genuinely false-positive.** Rare
+   (Rigor's design priority is no-false-positives) but
+   possible. File an issue with the smallest reproducer you
+   can extract.
+
+## A helpful workflow
+
+The pragmatic loop on a project that just adopted Rigor:
+
+1. Run `rigor check lib` once to see the baseline.
+2. Skim every diagnostic. Triage as one of:
+   a. **Real bug.** Fix the code.
+   b. **Missing / wrong RBS.** Update the sig or add a new
+      one.
+   c. **Genuine noise.** Add `# rigor:disable <rule>` on the
+      line, or `disable:` to `.rigor.yml`.
+3. Re-run. Repeat until the diagnostic stream is clean.
+4. Add `rigor check lib` to CI under the
+   `balanced` profile (or stricter).
+5. As the project's invariants get more proven, demote
+   `# rigor:disable` lines into `RBS::Extended` directives
+   so the analyzer learns the real contract.
+
+A clean `rigor check` run is the goal; a green CI badge says
+"every diagnostic that fires is one we accept."
+
+## What's next
+
+[Chapter 9 — Plugins](09-plugins.md) is a one-page pointer to
+the `examples/` directory. Plugins extend Rigor for
+project-specific DSLs (units of measure, route helpers,
+deprecations, …). Most projects will never write one; the
+chapter exists so you know the option is there.
+[Chapter 10 — Coexisting with Sorbet](10-sorbet.md) is for
+projects arriving from a Sorbet codebase: the
+[`rigor-sorbet`](../../plugins/rigor-sorbet/) adapter reads
+`sig { ... }` blocks, RBI files, and `T.let` / `T.cast` /
+`T.must` / `T.unsafe` assertions as type sources.

data/docs/handbook/09-plugins.md

@@ -0,0 +1,241 @@
+# Plugins
+
+Plugins exist for one reason: some methods' types depend on
+the **shape of their arguments at runtime** in ways that no
+RBS sig can express. This chapter helps you decide when that
+is worth a plugin, and when it is not.
+
+It does **not** teach plugin *authoring*. That lives in
+[`examples/`](../../examples/README.md) — six tutorial
+walkthroughs, each spotlighting one extension surface.
+Ready-to-install gems for real frameworks live in
+[`plugins/`](../../plugins/README.md). Read on to decide
+whether you need a plugin; go to `examples/` once you want to
+write one, or `plugins/` to install an existing one.
+
+## When you reach for a plugin
+
+The classic case is a domain-specific evaluator:
+
+```ruby
+Lisp.eval([:+, 1, 2])           # Integer at runtime
+Lisp.eval([:<, 1, 2])           # bool at runtime
+Lisp.eval([:if, true, "a", 0])  # String | Integer at runtime
+```
+
+The return type depends on the literal first symbol of the
+argument array. RBS can only say `untyped` here; Rigor's
+inference can do nothing about it; an `RBS::Extended`
+directive cannot vary by argument shape. **A plugin can.**
+
+Other shapes that fit the plugin niche:
+
+- **Units-of-measure DSLs** — `100.kilometers / 2.hours`
+  produces a `Speed`, but Ruby's runtime sees a method on
+  Integer that returns a user class.
+- **Route helpers** — `users_path` returns a String, but
+  whether the helper exists at all depends on a YAML file
+  the analyzer has to read.
+- **State machines** — `transition_to(:foo)` is fine if
+  `:foo` is in a `state_machine do ... end` block declared
+  somewhere; otherwise it is a typo.
+- **Custom validators** — `validate(:email, value)` should
+  catch a literal that does not match the named pattern at
+  lint time.
+
+Each of these has a worked example in
+[`examples/`](../../examples/README.md). The
+[`examples/README.md`](../../examples/README.md) page
+compares the six worked examples on architectural axes
+(config schema, file I/O, cache producers,
+engine-collaboration via `Scope#type_of`, cross-plugin facts,
+return-type contributions, …) and recommends a reading order.
+
+## What a plugin can do today
+
+> Still here? Most readers should jump to
+> [Should you write one?](#should-you-write-one) first — the
+> answer is usually "no, RBS and `RBS::Extended` get you
+> there." The surfaces below are for when it is "yes."
+
+The v0.1.0+ plugin contract — pinned at
+[`docs/internal-spec/plugin.md`](../internal-spec/plugin.md)
+and laid out across a handful of slice specs in the same
+directory — gives a plugin five primary surfaces:
+
+1. **`#diagnostics_for_file(path:, scope:, root:)`** — the
+   per-file emission hook. Walk the parsed AST, return an
+   array of `Rigor::Analysis::Diagnostic` rows. The runner
+   stamps each with `source_family: "plugin.<your-id>"`.
+2. **`dynamic_return(receivers:, methods:, file_methods:)` /
+   `type_specifier(methods:)`** — the per-call-site return-type
+   and flow-narrowing contribution surface (ADR-37 Slice 2).
+   A `dynamic_return` block names the inferred return type at a
+   matching call site; the analyzer's dispatcher merges the
+   contribution and uses it as if it were RBS-declared. A
+   `type_specifier` block contributes branch-narrowing facts.
+   (These replaced the removed `flow_contribution_for` hook —
+   ADR-52 WD3; a plugin that still defines it raises at load.)
+3. **`Plugin::IoBoundary#read_file`** / **`#open_url`** —
+   sandboxed file and (since v0.1.2) HTTPS reads under the
+   active `TrustPolicy`. Use this when the plugin needs to
+   read project files (route tables, schemas, locale files)
+   or fetch a stable URL.
+4. **`Plugin::Base.producer` + `#cache_for`** — plugin-side
+   cache producers. Use these for parses / lookups expensive
+   enough to want cross-run caching. Auto-invalidates on
+   the digest of every file (and content hash of every URL)
+   the IoBoundary read while building the result.
+5. **`Plugin::FactStore` + `#prepare(services)`** — the
+   cross-plugin fact-publication surface (v0.1.1 Track 2,
+   ADR-9). Plugins publish facts in `prepare`; downstream
+   plugins consume them through `services.fact_store` so
+   producer-side parsing (e.g., `config/routes.rb`) can be
+   reused by every consumer (controller-side validators,
+   factory-side validators, …).
+
+Several worked examples (`rigor-lisp-eval`, `rigor-pattern`,
+`rigor-units`, `rigor-activerecord`) contribute a narrowed
+return type via `dynamic_return` rather than only emitting
+diagnostics, so chained calls on plugin-typed values resolve
+through the analyzer's normal dispatch rather than the
+RBS-level `untyped` envelope. See the per-plugin README for
+which surface each one demonstrates.
+
+## Macro / DSL expansion substrate (ADR-16)
+
+A second authoring path was added on top of the hand-rolled
+walker contract above: the **macro expansion substrate**
+(ADR-16). For metaprogramming-heavy DSLs — Rails-style
+`has_one_attached`, dry-struct's `attribute`, Devise's
+`devise :strategy`, Sinatra's `get '/foo' do ... end` — the
+substrate lets a plugin author **declare** the call shape
+instead of walking the AST by hand. The plugin's body becomes
+a single manifest entry; the substrate handles literal-symbol
+extraction, name interpolation, registry lookup, and per-method
+synthesis.
+
+Four tier shapes are recognised. The
+[per-library survey](../notes/20260515-macro-expansion-library-survey.md)
+identifies which libraries fit each tier and which fall
+outside the substrate's scope.
+
+| Tier | Shape | Manifest declaration | Worked example |
+| --- | --- | --- | --- |
+| **A — block-as-method** | DSL call's block runs as an instance method on the receiver class (`Sinatra::Base#generate_method`) | `block_as_methods: [Macro::BlockAsMethod.new(receiver_constraint:, method_names:)]` | [`rigor-sinatra`](../../plugins/rigor-sinatra/) |
+| **B — trait-inlining registry** | Class-level call enumerates symbols → bundled registry maps each to a module → substrate explodes the module's RBS methods onto the calling class | `trait_registries: [Macro::TraitRegistry.new(receiver_constraint:, method_name:, modules_by_symbol:, always_included:)]` | [`rigor-devise`](../../plugins/rigor-devise/) |
+| **C — heredoc template** | Class-level call interpolates a literal symbol into a method-name template; substrate emits synthetic readers | `heredoc_templates: [Macro::HeredocTemplate.new(receiver_constraint:, method_name:, symbol_arg_position:, emit:)]` | [`rigor-dry-struct`](../../plugins/rigor-dry-struct/) |
+
+The three Tier-A/B/C plugins above are each ~60–110 LoC of
+**purely declarative** Ruby — no walker, no
+`diagnostics_for_file`, no plugin-side state. The substrate's
+pre-pass + dispatcher integration do the work.
+
+### Concern re-targeting
+
+`ActiveSupport::Concern.included do ... end` is a *deferred
+class_eval*: any DSL calls inside the block fire on whoever
+includes the concern, not on the concern module itself. The
+substrate's scanner handles this re-targeting automatically.
+For source like:
+
+```ruby
+module Auditable
+  extend ActiveSupport::Concern
+  included do
+    attribute :audited_at, Types::Time
+  end
+end
+
+class Address < Dry::Struct
+  include Auditable
+  attribute :city, Types::String
+end
+```
+
+`Address` gets BOTH `city` (direct) AND `audited_at` (re-targeted
+from `Auditable`) as synthetic readers. The same pattern works
+for Tier B traits (Devise modules included via Concerns).
+
+### Floor / ceiling
+
+Per ADR-16 § WD13, the **floor** is that synthetic methods emit
+by NAME so cross-file dispatch resolves (no more
+`call.undefined-method`). The common cases also recover precise
+return types: **Tier B** redispatches on the origin module's
+authored RBS (a Devise `valid_password?` resolves to `bool`,
+not `Dynamic[T]`), and **Tier C** resolves a plain class-name
+return to its `Nominal`. What still degrades to `Dynamic[T]` is
+the parameterised / utility-type-shaped Tier C return
+(`Array[String]`, `Pick<T, K>`); routing those through the
+[ADR-13](../adr/13-typenode-resolver-plugin.md) resolver chain
+is the **ceiling**, demand-driven. The substrate never
+*fabricates* precision per ADR-5 robustness.
+
+### Choosing between the substrate and a hand-rolled walker
+
+| If the DSL is… | Use the substrate | Use a hand-rolled walker |
+| --- | --- | --- |
+| `class-level call with literal symbol args + framework class_eval'd heredoc` | ✓ Tier C | — |
+| `class-level call with literal symbol args + registry-driven module include` | ✓ Tier B | — |
+| `class-level call with do…end block running as an instance method` | ✓ Tier A | — |
+| `external Ruby files instance_eval'd under a declared self` | ✓ Tier D (contract only as of v0.1.x) | — |
+| `domain DSL whose return type depends on argument shape` | — | `dynamic_return` ([`rigor-lisp-eval`](../../examples/rigor-lisp-eval/)) |
+| `cross-file validation (collect declarations, then validate uses)` | — | Two-pass walker ([`rigor-statesman`](../../plugins/rigor-statesman/)) |
+| `parsing an external project file (routes, schema, locale)` | — | `IoBoundary` + cache producer ([`rigor-routes`](../../examples/rigor-routes/)) |
+| `schema-graph recorder (GraphQL-Ruby-style)` | — | Schema-resolution pass (no plugin authored yet) |
+
+The substrate and the hand-rolled walker contract coexist —
+a plugin can mix `manifest`-declared substrate entries with a
+`diagnostics_for_file` walker. The
+[`skills/rigor-plugin-author/SKILL.md`](../../skills/rigor-plugin-author/SKILL.md)
+SKILL captures the decision flow in detail; the survey at
+[`docs/notes/20260515-macro-expansion-library-survey.md`](../notes/20260515-macro-expansion-library-survey.md)
+records which Ruby libraries the substrate covers and which
+fall outside.
+
+## Should you write one?
+
+Probably not — most projects benefit from RBS and
+`RBS::Extended` long before they hit the plugin niche.
+Reach for a plugin only when:
+
+- A domain DSL's typing depends on argument shape, file
+  contents, or cross-method declarations.
+- You are willing to maintain the plugin gem alongside your
+  application.
+- The team can read the plugin's source — it is not a black
+  box anyone can ignore.
+
+If those are true, [`examples/README.md`](../../examples/README.md)
+is your starting point. The
+[`rigor-deprecations`](../../examples/rigor-deprecations/)
+example is the smallest fully-shaped plugin — manifest +
+single per-file walk + a couple of diagnostic emissions —
+and is the recommended template for "I want to author my
+first plugin."
+
+## What's next
+
+If your project uses [Sorbet](https://sorbet.org/), the
+[next chapter](10-sorbet.md) covers the `rigor-sorbet`
+adapter — Rigor reads `sig { ... }` blocks, RBI files, and
+`T.let` / `T.cast` / `T.must` / `T.unsafe` assertions as
+type sources, so you do not have to rewrite anything in RBS
+to start running `rigor check` alongside `srb tc`. If you do
+not use Sorbet, chapter 10 is safe to skip.
+
+From here:
+
+- Cover-to-cover re-reading is rarely useful — most readers
+  return to specific chapters as questions arise.
+- The [Handbook index](README.md) has the cross-references
+  to deeper material in
+  [`docs/type-specification/`](../type-specification/README.md),
+  [`docs/internal-spec/`](../internal-spec/README.md), and
+  [`docs/adr/`](../adr/).
+- The [`CHANGELOG.md`](../../CHANGELOG.md) is the per-release
+  truth for what shipped when.
+
+Welcome to the small, growing community of static-Ruby
+believers.