rigortype 0.2.0 → 0.2.2

data/docs/handbook/10-sorbet.md

@@ -0,0 +1,347 @@
+# Coexisting with Sorbet
+
+If your project already uses [Sorbet](https://sorbet.org/),
+the [`rigor-sorbet`](../../plugins/rigor-sorbet/) plugin
+lets Rigor read your existing `sig` blocks, RBI files, and
+`T.let` / `T.cast` / `T.must` / `T.unsafe` assertions as type
+sources. You do not have to rewrite anything in RBS to start
+running `rigor check` alongside `srb tc`.
+
+This chapter is for users arriving from a Sorbet-using
+project. If you have never used Sorbet, you can skip it; the
+core handbook material in chapters 1–9 covers Rigor's native
+RBS-based path.
+
+## What gets translated
+
+Given a method preceded by a `sig` block:
+
+```ruby
+class Slug
+  extend T::Sig
+
+  sig { params(name: String).returns(String) }
+  def normalise(name)
+    name.downcase.gsub(/\s+/, "-")
+  end
+
+  sig { returns(Integer) }
+  def self.default_length
+    32
+  end
+end
+```
+
+Rigor lifts the parsed sig at every call site, so chained
+calls resolve through the analyzer's normal dispatch:
+
+```ruby
+slug = Slug.new
+slug.normalise("Alice").upcase  # ✓ String#upcase resolves
+Slug.default_length.even?       # ✓ Integer#even? resolves
+```
+
+No `.rbs` file required. The plugin walks every Ruby file
+under `paths:` (and every `.rbi` file under `sorbet/rbi/` —
+see "RBI files" below), pairs each `sig { ... }` block with
+the `def` immediately following it, and contributes the
+return type at the matching call sites.
+
+## The Sorbet type vocabulary
+
+The plugin translates the dense middle of Sorbet's type DSL.
+Most everyday sigs land precisely; rare or
+class-introspection-heavy forms degrade to `Dynamic[top]`.
+
+| Sorbet form              | Rigor representation                     |
+| ------------------------ | ---------------------------------------- |
+| `Integer` etc.           | `Nominal["Integer"]`                     |
+| `::Foo::Bar`             | `Nominal["Foo::Bar"]`                    |
+| `T.untyped`              | `Dynamic[top]`                           |
+| `T.anything`             | `Top`                                    |
+| `T.noreturn`             | `Bot`                                    |
+| `T.nilable(X)`           | `Union[X, Constant<nil>]`                |
+| `T.any(A, B, ...)`       | `Union[A, B, ...]`                       |
+| `T.all(A, B, ...)`       | `Intersection[A, B, ...]`                |
+| `T::Boolean`             | `Union[Constant<true>, Constant<false>]` |
+| `T::Array[E]`            | `Nominal["Array", [E]]`                  |
+| `T::Hash[K, V]`          | `Nominal["Hash", [K, V]]`                |
+| `T::Set[E]`              | `Nominal["Set", [E]]`                    |
+| `T::Range[E]`            | `Nominal["Range", [E]]`                  |
+| `T::Enumerable[E]`       | `Nominal["Enumerable", [E]]`             |
+| `T::Class[T]`            | `Singleton[T-class-name]` (lossy)        |
+| `T.class_of(C)`          | `Singleton[C]`                           |
+| `[A, B]` (tuple in sig)  | `Tuple[A, B]`                            |
+| `{a: A, b: B}`           | `HashShape{a: A, b: B}` (closed)         |
+
+Anything outside this table — `T.proc`, `T.attached_class`,
+`T.self_type`, `T.type_parameter`, `T::Struct` / `T::Enum`
+subclasses — silently degrades to `Dynamic[top]` for now.
+
+## Inline type assertions
+
+Sorbet's `T.let` / `T.cast` / `T.must` / `T.unsafe`
+expressions are recognised at every call site, not only inside
+`sig` blocks:
+
+```ruby
+counter = T.let(0, Integer)        # widens Constant<0> to Integer
+counter.even?                       # ✓ Integer#even? resolves
+
+T.cast(some_value, String).upcase   # ✓ String#upcase resolves
+
+maybe = T.let(nil, T.nilable(Integer))
+T.must(maybe).bit_length            # ✓ nil stripped → Integer
+                                     #   then Integer#bit_length resolves
+
+T.unsafe(opaque).any_method_at_all  # ✓ silenced — return is Dynamic[top]
+```
+
+`T.must_because(expr, "explanation")` is recognised as an
+alias of `T.must` — the static behaviour is identical (strip
+`nil`); the second-argument string is informational only.
+
+`T.reveal_type(expr)` returns `expr` unchanged at runtime AND
+surfaces the inferred static type as a
+`plugin.sorbet.reveal-type` `:info` diagnostic at the call
+site, so chained calls keep working while you eyeball what
+the analyzer sees:
+
+```ruby
+n = T.let(3, Integer)
+T.reveal_type(n).even?  # info: T.reveal_type inferred type: Integer
+                        # ✓ Integer#even? still resolves
+```
+
+`T.assert_type!(expr, T)` is `T.cast` plus a static subtype
+check. The call returns the asserted type so chained calls
+resolve through it; if the inferred type is provably
+incompatible (`Inference::Acceptance.accepts(...)` returns
+`:no`), the plugin emits `plugin.sorbet.assert-type-mismatch`
+as `:error`. Gradual consistency rules apply — `Dynamic[top]`
+inferred types and `:maybe`-compatible shapes are silenced
+because the runtime check covers them.
+
+```ruby
+T.assert_type!("hello", Integer)  # error: provably incompatible
+T.assert_type!(some_obj, String)  # silent: trust the user
+```
+
+`T.bind(self, T)` narrows `self` to `T` for the rest of the
+current scope (typically a block body):
+
+```ruby
+arr.each do |x|
+  T.bind(self, MyHelper)
+  do_something(x)  # ✓ self is now MyHelper for the rest of this block
+end
+```
+
+The narrowing is implemented via the engine's plugin-side
+`post_return_facts` wiring — the same substrate any future
+PHPStan-style Type-Specifying Extension plugin would use to
+narrow argument variables after a custom assertion call.
+
+`T.bind` rejects non-`self` first arguments silently (matches
+Sorbet's contract — bind is self-only).
+
+## RBI files
+
+The plugin walks `sorbet/rbi/**/*.rbi` recursively by default
+and treats each `.rbi` as Ruby source. The standard Tapioca
+subdirectories (`gems/`, `annotations/`, `dsl/`, `shims/`)
+all participate as a side effect of recursing into the parent
+root. Override the location via `config.rbi_paths:` in
+`.rigor.yml`, or set it to `[]` to opt out:
+
+```yaml
+plugins:
+  - gem: rigor-sorbet
+    config:
+      rbi_paths: []                              # disable RBI loading
+      # rbi_paths: ["sorbet/rbi", "vendor/rbi"]  # add a vendored tree
+```
+
+Project sigs (`.rb` files under `paths:`) and RBI sigs
+(`.rbi` files under `rbi_paths:`) feed the same per-run
+catalog, so a method declared in either source resolves the
+same way at the call site.
+
+## Sorbet `# typed:` sigils
+
+The plugin reads Sorbet's `# typed:` magic comment from the
+top of each file. Behaviour depends on the `enforce_sigil`
+config knob (default `true`):
+
+| Sigil               | `enforce_sigil: true` (default)             | `enforce_sigil: false` |
+| ------------------- | ------------------------------------------- | ---------------------- |
+| `# typed: ignore`   | Skipped entirely; no sigs / parse errors recorded. | Same.            |
+| no sigil / `false`  | Walked for parse-error diagnostics, but sigs are NOT recorded. | Sigs recorded. |
+| `# typed: true`+    | Sigs recorded.                              | Sigs recorded.          |
+
+The default mirrors Sorbet's own contract: types aren't
+enforced at `# typed: false`, so Rigor doesn't surface
+narrowing from those files either. Set `enforce_sigil: false`
+in the plugin config to opt into the pre-gate behaviour
+(every parseable file's sigs land in the catalog regardless
+of sigil).
+
+**Assertion recognisers** (`T.let`, `T.cast`, `T.must`,
+`T.must_because`, `T.unsafe`, `T.reveal_type`,
+`T.assert_type!`, `T.bind`) are NOT gated by
+`enforce_sigil`. The user wrote those calls deliberately, so
+they fire regardless of the file's sigil.
+
+Sorbet-strict's "every method must have a sig" requirement
+and strong-mode's `T.untyped` rejection are intentionally NOT
+mirrored. Those checks live with `srb tc`. Rigor's own
+`severity_profile` setting in `.rigor.yml` covers the
+analogous filtering.
+
+## Tapioca DSL — the mixin pattern
+
+Tapioca's standard DSL RBI shape declares sigs on a generated
+module that is `include`d / `extend`ed into the host class:
+
+```rbi
+class Post
+  include GeneratedAttributeMethods
+  module GeneratedAttributeMethods
+    sig { returns(::String) }
+    def body; end
+  end
+end
+```
+
+The plugin records the sig under the module's qualified name
+during the walk and lifts it to the host class at lookup
+time. So `post.body` correctly resolves through
+`Post::GeneratedAttributeMethods#body` — no manual
+flattening required, and the same trick works for
+hand-written shims under `sorbet/rbi/shims/` and community
+annotations under `rbi-central`.
+
+`extend M` correctly lifts `M`'s instance methods to the
+extending class's singleton side, matching Ruby's runtime
+behaviour:
+
+```rbi
+class Post
+  extend GeneratedClassMethods
+  module GeneratedClassMethods
+    sig { params(id: Integer).returns(Post) }
+    def find(id); end
+  end
+end
+```
+
+`Post.find(42)` resolves through the extended module's
+instance side.
+
+## `T.absurd` exhaustiveness
+
+`T.absurd(x)` is Sorbet's idiom for case/when exhaustiveness:
+"if I got here, the type system has lost the plot." The
+plugin treats every `T.absurd` call as `Bot` (the empty
+type — no possible value) AND raising, so the engine's
+existing flow analysis treats code after the call as
+unreachable:
+
+```ruby
+case x
+when A then handle_a(x)
+when B then handle_b(x)
+else
+  T.absurd(x)  # asserts the else branch is unreachable
+end
+```
+
+When the discriminant is fully exhausted, the `T.absurd`
+call sits in dead code and contributes nothing. When a case
+branch is missing, the discriminant's type at the `T.absurd`
+call still has admissible inhabitants, and the plugin
+surfaces `plugin.sorbet.absurd-reachable` as a warning:
+
+```text
+demo.rb:42:5: warning: `T.absurd` is reachable: the discriminant did not
+                       narrow to `T.noreturn`. Either add the missing case
+                       branch above the `else`, or remove the `T.absurd(...)` call.
+                       [plugin.sorbet.absurd-reachable]
+```
+
+The detection's accuracy follows Rigor's flow-sensitive
+narrowing — `is_a?` / `kind_of?` / `nil?` work precisely;
+narrowing over symbol enums is less precise as of v0.1.3,
+so fully-exhausted symbol cases may emit false-positive
+warnings until the engine's case narrowing improves.
+
+## Tier ordering — what wins on conflict
+
+When a method has both a Sorbet `sig` and an RBS sig, RBS
+wins. Sorbet sigs sit at Rigor's plugin tier:
+
+1. **Precision tiers** — constant fold, shape dispatch,
+   block fold, etc.
+2. **Plugin contributions** — including `rigor-sorbet`'s
+   sig and assertion translations.
+3. **RBS-backed dispatch** — project `sig/`,
+   `RBS::Inline`, bundled stdlib.
+4. **Dependency-source inference** (ADR-10's opt-in walker).
+5. **User-class fallback** (`Object` / `Class` ancestors).
+
+The contribution merger (a v0.1.0 substrate documented in
+[`docs/internal-spec/flow-contribution-merger.md`](../internal-spec/flow-contribution-merger.md))
+keeps RBS authoritative on conflict — the Sorbet sig is
+allowed to refine but not contradict it. Users who want
+their Sorbet sig to override should remove the conflicting
+RBS, not the other way around. The reverse direction
+(Sorbet wins) would let third-party-DSL annotations
+override authored RBS, which inverts the trust model.
+
+## Migration patterns
+
+The plugin is designed for **gradual coexistence**, not a
+forced migration. Three common shapes:
+
+1. **Run both static checkers side by side.** `srb tc`
+   keeps producing its diagnostics; `rigor check`
+   produces its own. They overlap on shape errors and
+   complement each other on what each finds — Sorbet
+   covers `T.let` / `T.cast` / RBI more deeply; Rigor
+   covers literal-string narrowing, refinement carriers,
+   plugin DSLs, and dependency-source inference.
+2. **Sorbet for sigs, Rigor for narrowing.** Authoritative
+   sigs stay in `sig { ... }` blocks (or the
+   sorbet-runtime-friendly RBI tree); Rigor reads them as
+   input and adds its own narrowing on top.
+3. **Sorbet → RBS over time.** New code lands as RBS;
+   existing Sorbet sigs stay until the surrounding
+   subsystem changes. The plugin keeps running while the
+   Sorbet surface shrinks.
+
+## What the plugin doesn't replace
+
+Rigor's `rigor-sorbet` adapter is **input-side only**. It
+reads Sorbet's syntax and translates the vocabulary; it does
+not run Sorbet's type checker, doesn't ship
+`sorbet-runtime`, and doesn't enforce Sorbet's runtime
+guarantees. If you remove `sorbet` and `sorbet-runtime` from
+your `Gemfile`, the plugin keeps reading the sigs (the
+adapter's mini-interpreter doesn't load Sorbet) but `T.let` /
+`T.cast` / `T.must` / `T.unsafe` calls will raise
+`NameError` at runtime unless you keep at least the runtime
+gem (or stub the four singleton methods on a top-level `T`
+constant — the plugin's demo does this for its own
+unit tests).
+
+## Where to go next
+
+- The full feature matrix and architectural surface live in
+  [`plugins/rigor-sorbet/README.md`](../../plugins/rigor-sorbet/README.md).
+- The design rationale + slice plan is at
+  [`docs/adr/11-sorbet-input-adapter.md`](../adr/11-sorbet-input-adapter.md).
+- The cross-checker triage report at
+  [`docs/notes/20260503-steep-cross-check-triage.md`](../notes/20260503-steep-cross-check-triage.md)
+  shows how Rigor's analyzer routinely surfaces sig drift
+  that other static checkers miss — useful when comparing
+  what each tool finds in practice.

data/docs/handbook/11-sig-gen.md

@@ -0,0 +1,312 @@
+# Generating RBS with rigor sig-gen
+
+When `rigor check` is happy with your code but `sig/` is still
+mostly empty, the analyzer is doing useful inference that
+never reaches anyone but itself. `rigor sig-gen` is the
+companion command that emits the inferred signatures as RBS
+so the rest of the toolchain — Steep cross-checks, IDE
+tooltips, downstream consumers reading your gem's `sig/` —
+sees what Rigor sees.
+
+This chapter is a walkthrough of the command's UX, the
+classification model, the three output modes, and the
+`--params` policy trade-off that comes straight out of
+[ADR-5](../adr/5-robustness-principle.md)'s asymmetric
+"strict on returns, lenient on parameters" rule.
+
+## When to reach for it
+
+- You inherited a Ruby project with zero RBS coverage and
+  want a starting point that is more honest than `rbs
+  prototype rb`'s syntactic skeleton.
+- You added a method, `rigor check` recognises it, and now
+  you want the corresponding sig file updated without
+  retyping the signature by hand.
+- Your existing RBS declares `() -> Numeric` but Rigor
+  proves `() -> Integer`. You want the tighter spelling
+  applied to `sig/` (after review).
+
+What it is **not**: a replacement for hand-authored RBS
+that captures intent the source code does not. If a public
+method should accept `_ToStr` because the contract is
+"anything that responds to `to_s`" but the current callers
+only happen to pass `String`, `sig-gen` will not invent
+`_ToStr` for you — the [`--params` policy](#the---params-policy-and-adr-5)
+section below and ADR-5 explain why.
+
+## A first run
+
+Given a `lib/calc.rb`:
+
+```ruby
+class Calc
+  def add(a, b)
+    "sum"
+  end
+
+  def greet(name)
+    "hi"
+  end
+end
+```
+
+and an empty `sig/`, `rigor sig-gen` prints RBS skeletons:
+
+```
+$ rigor sig-gen
+# lib/calc.rb
+class Calc
+  # [new]
+  def add: (untyped, untyped) -> String
+  # [new]
+  def greet: (untyped) -> String
+end
+```
+
+By default the command writes nothing — it prints the
+proposal so you can review it. Pass `--write` to apply the
+proposal to `sig/`.
+
+## The three output modes
+
+| Mode | Behaviour |
+| --- | --- |
+| `--print` (default) | Print RBS to stdout, grouped by source file + class declaration. |
+| `--diff` | Show a unified-style diff comparing the existing-declared spelling (if any) against the inferred spelling. Read-only. |
+| `--write` | Apply the proposal to `sig/<path>.rbs`. Creates files, inserts new methods into existing class declarations, appends new class blocks to files that don't declare them yet. |
+
+`--write` is the only mode that touches the filesystem. It
+operates **only** inside `configuration.signature_paths`
+(default `sig/`); anything outside that tree is reported as
+`skipped_outside_sig_root` without being written to.
+
+## The classification model
+
+Every method `rigor sig-gen` considers lands in one of five
+states:
+
+| Classification | Meaning |
+| --- | --- |
+| `new-file` | No RBS file declares the receiver class at all. |
+| `new-method` | RBS file declares the class but not this method. |
+| `tighter-return` | RBS file declares the method, but the inferred return is a strict subtype of the declared return. |
+| `equivalent` | The inferred return is not a strict subtype of the declared one — identical, wider, or unrelated — so there is nothing to tighten. Silently skipped. |
+| `skipped` | Disqualified for one of the reasons below. |
+
+The three `sig.skipped.*` reasons are:
+
+- `sig.skipped.complex-shape` — the method has optional, rest,
+  keyword, block, or forwarding parameters. The MVP's
+  body-typing path only handles required positional
+  parameters; complex shapes need a future slice.
+- `sig.skipped.untyped-return` — the method body's last
+  expression types as `Dynamic[top]`. Emitting `untyped` as
+  a tightening would be noise rather than help.
+- `sig.skipped.user-authored` — `--overwrite` was not set
+  and the method's existing RBS declaration would have to
+  be replaced.
+
+The three `sig.generated.*` identifiers
+(`sig.generated.new-file` / `new-method` / `tighter-return`)
+are emitted as JSON fields under `--format=json` so CI
+gating consumers can route them.
+
+## What method shapes the generator covers
+
+Slice-by-slice (each shipped via a CHANGELOG entry — this
+list is the current state):
+
+- **Plain instance `def foo`** with required positional
+  parameters. Both new-method and tighter-return paths
+  apply.
+- **Singleton-side `def self.foo`** and
+  `class << self; def foo; end`. Rendered as
+  `def self.foo: ...`; matched against
+  `Reflection.singleton_method_definition` for existing
+  RBS.
+- **`attr_reader` / `attr_writer` / `attr_accessor`** with
+  literal Symbol arguments. The return type is the
+  accumulated ivar type from `Scope#class_ivars_for`. The
+  generator emits the long-form `def name: () -> T`
+  spelling so the writer's merge path applies unchanged;
+  existing short-form `attr_reader name: T` declarations
+  are recognised as user-authored and never produce a
+  duplicate `def` insertion.
+
+Method shapes the generator does **not** cover yet (and
+silently skips):
+
+- Optional / rest / keyword / block / forwarding parameters.
+- `define_method(:name) { ... }`.
+- Methods whose body types as `Dynamic[top]` (the body
+  inference cannot prove a useful return type).
+
+These are tracked as ADR-14 follow-ups.
+
+## The `--params` policy and ADR-5
+
+The `--params=POLICY` flag controls how parameter positions
+are spelled in the emitted RBS. There are three policies;
+two are wired today, one is reserved.
+
+| Policy | Behaviour |
+| --- | --- |
+| `untyped` (default) | Every parameter is spelled `untyped`. No inference-derived parameter contract is imposed on future callers. The user retains complete authorship over parameter typing. |
+| `observed` | Collect argument types from every call site under `--observe=PATH...` (defaults to `spec/` when present), union per parameter position, erase to RBS, emit the union. |
+| `observed-strict` | Reserved. Will additionally widen to capability roles (`_ToStr`, `_ToS`, …) once the role catalog ships. Currently rejected with a usage error. |
+
+The default deliberately favours `untyped` because of
+[ADR-5](../adr/5-robustness-principle.md)'s clause 2: a
+method's parameter contract should be the **most permissive**
+shape the body's logic justifies, not the most specific
+shape the current callers happen to use. Locking in
+`observed` would silently freeze "what the existing specs
+happen to pass" as the contract, which is the precision /
+adoption trade-off the chapter introduction hinted at.
+
+`--params=observed` is the deliberate opt-in: you are
+saying *"the union of what my callers pass today IS the
+parameter contract I want."* That is a correctness-
+preserving widening — every existing caller still passes —
+but it does narrow the contract relative to `untyped`.
+
+## RSpec-aware observations
+
+When you point `--observe` at a `spec/` directory, the
+generator recognises three RSpec-shaped binding patterns
+and uses them to type receivers that would otherwise
+degrade to `Dynamic[top]`:
+
+```ruby
+RSpec.describe Calc do
+  subject { Calc.new }         # binds :subject → Nominal[Calc]
+  let(:other) { Calc.new }     # binds :other   → Nominal[Calc]
+
+  it "..." do
+    subject.greet("Alice")     # observed: Calc#greet receives String
+    other.greet("Bob")         # observed: same
+    described_class.new.add(1, 2)  # observed: Calc#add receives Integer, Integer
+  end
+end
+```
+
+The recogniser handles `RSpec.describe Foo`, bare
+`describe Foo` (no `RSpec.` receiver), `subject { … }`,
+`subject(:name) { … }`, `let(:name) { … }`, `let!(:name)`,
+and `described_class.new(...)`. Same-name `let` bindings
+across nested scopes are last-wins; the recogniser does not
+re-implement RSpec's full scope rules — the typical
+one-spec-file shape is the target.
+
+The recogniser is part of the generator itself; you do not
+need to install `rigor-rspec` to benefit from it. If you
+already use `rigor-rspec` for diagnostics, the two run side
+by side without coordination.
+
+## Safety: what `--write` will and will not do
+
+- **Will** create new `*.rbs` files mirroring `lib/<path>.rb`'s
+  layout (basename of `configuration.paths.first` stripped,
+  placed under `configuration.signature_paths.first`).
+- **Will** insert new method declarations just before a
+  class declaration's closing `end` keyword, preserving
+  every other byte of the file verbatim.
+- **Will** append a new `class Foo … end` block when the
+  target file does not declare the class yet.
+- **Will not** touch files outside the configured signature
+  tree.
+- **Will not** replace an existing method declaration
+  unless `--overwrite` is set AND the candidate is a
+  `tighter-return`. Without `--overwrite`, existing
+  declarations are user-authored and the new method is
+  silently skipped.
+- **Will not** touch `attr_reader` / `attr_writer` /
+  `attr_accessor` declarations in existing RBS — those are
+  always treated as user-authored.
+
+The recommended workflow is `--diff` first, review, then
+`--write` (or `--write --overwrite` if you decided that
+the tightening is intentional).
+
+### When tightening is *probably* incomplete inference
+
+The strict-subtype check is a *necessary* condition for
+emitting a tighter-return — it's not a sufficient signal
+that the existing RBS is wrong. Slice 1's body-typing path
+only inspects the implicit-return expression, so a method
+like:
+
+```ruby
+def find(key)
+  return nil unless @table.key?(key)
+  @table[key]
+end
+```
+
+types as the return of `@table[key]` alone. If the existing
+RBS declares `(K) -> V | nil`, the inferred `V` looks
+strictly tighter — but it's tighter for the wrong reason
+(the `nil` branch is unreachable in the body-typer's eyes,
+not in the runtime's). Applying it would silently delete
+the `nil` arm.
+
+**Heuristic**: when a tightening DROPS union members that
+the existing RBS declares — `T | nil → T`, `false | true →
+true`, `Float | Integer → Float`, `Array[T] → [T]` — treat
+it as a contradiction signal, not a precision win, and
+leave the existing RBS alone. The generator does not yet
+classify these automatically; the `--diff` review step is
+where the human gate sits.
+
+For `rigor`'s own `sig/` tree this is the load-bearing
+policy: every tighter-return that contradicts an existing
+declaration is suspected incomplete inference until proven
+otherwise.
+
+## Putting it together
+
+A typical iteration on a new file:
+
+```sh
+# 1. See what Rigor would propose.
+rigor sig-gen lib/calc.rb
+
+# 2. Run with the observed-params policy to use spec/ as
+#    a parameter-type signal.
+rigor sig-gen --params=observed lib/calc.rb
+
+# 3. Compare against the current sig/ tree.
+rigor sig-gen --params=observed --diff lib/calc.rb
+
+# 4. Apply.
+rigor sig-gen --params=observed --write lib/calc.rb
+
+# 5. Re-run rigor check to confirm no regressions.
+rigor check
+```
+
+The five steps map to the five ADR-14 slices the command
+is built from. If any step shows results you didn't expect,
+the diagnostic the analyzer would emit for the same code is
+the source of truth — `sig-gen` is a downstream consumer of
+inference, not a separate analysis.
+
+## Limits today
+
+- Methods with optional / rest / keyword / block /
+  forwarding parameters silently skip
+  (`sig.skipped.complex-shape`).
+- `define_method` and `Data.define`-specific emission are
+  deferred follow-ups (`Data.define`-derived readers come
+  through if a method body exists).
+- The strict-subtype check uses gradual-mode acceptance
+  today; the `:strict` mode reserved on
+  `Inference::Acceptance` arrives in a follow-up.
+- Round-trip through `RBS::Writer` is not used (it drops
+  comments by upstream design); the generator's
+  byte-range insertion preserves untouched declarations
+  verbatim but cannot preserve comments interleaved
+  *inside* a touched declaration's range.
+
+These are the ADR-14 deferred items; the design rationale
+is in [`docs/adr/14-rbs-sig-generation.md`](../adr/14-rbs-sig-generation.md).