rigortype 0.3.0 → 0.3.2

data/docs/handbook/07-rbs-and-extended.md

@@ -100,27 +100,24 @@ Rigor sees a tightening.
 
 ## The directive grammar
 
-`RBS::Extended` lives at
+There are seven per-method directives, and they divide by
+*when* the fact they carry becomes true: `return:` and `param:`
+retype the signature itself, `predicate-if-true` /
+`predicate-if-false` narrow a variable across the branches of a
+condition, and `assert` / `assert-if-true` / `assert-if-false`
+narrow one after the call returns. Each is one
+`%a{rigor:v1:…}` annotation above the `def` it refines; they
+stack, and order does not matter.
+
+The exhaustive table — every directive, its payload syntax, and
+what the `<type>` slot accepts (RBS class names, refinement
+payloads, the parameterised and bounded forms, and where `~T`
+negation is and is not allowed) — is
+[manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md#per-method-directives);
+the normative rules for conflicts, merging and provenance are
 [`docs/type-specification/rbs-extended.md`](../type-specification/rbs-extended.md).
-The per-method directives:
-
-| Directive | Says |
-| --- | --- |
-| `%a{rigor:v1:return: <type>}` | Tighten the method's return type. |
-| `%a{rigor:v1:param: <name> is <type>}` | Tighten a parameter's accepted type at the call site, AND narrow the local in the body. |
-| `%a{rigor:v1:assert <name> is <type>}` | After this method returns, the named local in the caller's scope is `<type>`. |
-| `%a{rigor:v1:predicate-if-true <name> is <type>}` | When this method returns truthy, the named local in the caller's scope is `<type>`. (Symmetric `predicate-if-false`.) |
-| `%a{rigor:v1:assert-if-true <name> is <type>}` | When this method returns a truthy value, the named local in the caller's scope is `<type>`. (Symmetric `assert-if-false` for `false` / `nil` returns.) |
-
-The `<type>` slot accepts:
-
-- **RBS class names** — `String`, `Integer`, `::Foo::Bar`.
-- **Imported refinement names** —
-  `non-empty-string`, `lowercase-string`, `numeric-string`,
-  `int<5, 10>`, `non-empty-array[Integer]`, `literal-string`,
-  …
-- **Negation `~T`** — `~lowercase-string` means
-  "non-lowercase-string."
+The rest of this chapter works through the directives one
+example at a time.
 
 ## Refinement names
 
@@ -140,9 +137,8 @@ A short reference:
 ## Declaring conformance — `conforms-to`
 
 The directives above attach to a `def`. One more attaches to a
-`class` / `module` declaration and asserts the whole class
-satisfies a named structural interface, as a checked design
-assertion — whether or not any call site exercises it:
+`class` / `module` declaration and asserts that the whole class
+satisfies a named structural interface:
 
 ```rbs
 %a{rigor:v1:conforms-to _RewindableStream}
@@ -153,13 +149,21 @@ end
 ```
 
 If `MyBuffer` is missing a method the `_RewindableStream`
-interface requires (or the signature is incompatible), Rigor
-reports `rbs_extended.unsatisfied-conformance`; a class that
-satisfies the interface is silent. Multiple `conforms-to`
-directives on one class combine like an intersection of
-interfaces. The directive is purely additive — implicit
-structural compatibility at call sites keeps working with or
-without it.
+interface requires, Rigor reports
+`rbs_extended.unsatisfied-conformance`; a class that satisfies
+the interface is silent.
+
+The reason to reach for this is that Rigor already checks
+structural compatibility *implicitly*, wherever a value flows
+into a position that needs a structural interface — so a class
+nobody currently passes anywhere is never checked at all.
+`conforms-to` turns the contract into a design assertion that
+holds whether or not a call site exercises it, which is what a
+library wants when the structural shape is the point. It is
+purely additive: nothing that type-checked before stops doing
+so because you added it. The stacking and diagnostic semantics
+are in
+[manual — `conforms-to`](../manual/16-rbs-extended-annotations.md#conforms-to--a-checked-structural-contract).
 
 ## Worked example: an assertion gate
 
@@ -181,6 +185,45 @@ end
 The runtime side is whatever `assert_non_empty` does (raise
 on empty, log, ...) — Rigor only reads the directive.
 
+## Worked example: asserting a negative
+
+An assertion payload can be negated with `~T`, which is how you
+model the "this is definitely not nil any more" helper every
+codebase grows:
+
+```rbs
+# sig/asserts.rbs
+class Asserts
+  %a{rigor:v1:assert x is ~nil}
+  def self.not_nil: (untyped x) -> void
+end
+```
+
+```ruby
+# lib/configure.rb
+def configure(maybe)
+  Asserts.not_nil(maybe)
+  # maybe: (~nil), so .upcase resolves on the narrowed type
+  maybe.upcase
+end
+```
+
+The target can also be the receiver itself — name it with
+`self`, and the fact lands on the object the method was called
+on:
+
+```rbs
+class Connection
+  %a{rigor:v1:assert self is Connected}
+  def assert_connected!: () -> void
+end
+```
+
+If PHPDoc's `@phpstan-assert` family is your mental model for
+all of this, the reading is nearly one-for-one; the mapping
+table is in
+[appendix: Coming from PHPStan](appendix-phpstan.md#the-phpstan-assert-family).
+
 ## Worked example: a type predicate
 
 ```rbs
@@ -343,74 +386,6 @@ dynamic boundaries (deserialisation, `eval`, plugin entry
 points). The static analysis you lose is made up by the
 honesty of admitting "this could be anything."
 
-## Coming from PHPStan? The `@phpstan-assert` family
-
-If you are familiar with PHPStan's PHPDoc annotations,
-Rigor's `RBS::Extended` directives map directly onto the
-post-return / conditional narrowing primitives PHPStan calls
-"asserts" and "type-specifying functions." The behaviour is
-identical:
-
-> "After this method returns, the named argument is `T`."
-
-That is `@phpstan-assert` in PHPStan and
-`%a{rigor:v1:assert}` in Rigor.
-
-| PHPStan PHPDoc | Rigor RBS::Extended | Effect |
-| --- | --- | --- |
-| `@phpstan-assert T $x` | `%a{rigor:v1:assert x is T}` | After this method returns normally, the caller's `x` is `T`. |
-| `@phpstan-assert-if-true T $x` | `%a{rigor:v1:predicate-if-true x is T}` | If this method returns truthy, the caller's `x` is `T`. |
-| `@phpstan-assert-if-false T $x` | `%a{rigor:v1:predicate-if-false x is T}` | If this method returns falsey, the caller's `x` is `T`. |
-| `@phpstan-assert !T $x` | `%a{rigor:v1:assert x is ~T}` | After this method returns, the caller's `x` is **not** `T` (negation form). |
-| `@phpstan-assert-if-true !T $x` | `%a{rigor:v1:predicate-if-true x is ~T}` | Conditional negation. Symmetric with `predicate-if-false`. |
-
-Worked example — the canonical "assertNotNull" pattern from
-PHPStan's docs:
-
-```rbs
-# sig/asserts.rbs
-class Asserts
-  %a{rigor:v1:assert x is ~nil}
-  def self.not_nil: (untyped x) -> void
-end
-```
-
-```ruby
-# lib/configure.rb
-def configure(maybe)
-  Asserts.not_nil(maybe)
-  # maybe: (~nil), so .upcase resolves on the narrowed type
-  maybe.upcase
-end
-```
-
-Self-targeted forms are supported too — the PHPStan
-analogue would be a method on `$this` that narrows
-`$this`. Name the receiver with `self`:
-
-```rbs
-class Connection
-  %a{rigor:v1:assert self is Connected}
-  def assert_connected!: () -> void
-end
-```
-
-Rigor's directive grammar covers what PHPStan ships in the
-`@phpstan-assert*` family. The directives **only fire from
-RBS** (per ADR-5: strict on returns, lenient on parameters);
-in PHPStan-land you can also write `@phpstan-assert` in
-PHPDoc directly above the function — Rigor's equivalent is
-the same RBS file's `def` line.
-
-If you need plugin-side equivalents (when the assertion is
-recognised by **call shape** rather than by sig — PHPStan's
-"Type-Specifying Extensions"), see
-[Chapter 9](09-plugins.md). The plugin contract surfaces
-the same `Fact(target_kind: :self)` and
-`Fact(target_kind: :parameter)` carriers that the directives
-use, so a plugin author writes the equivalent of a PHPStan
-`StaticMethodTypeSpecifyingExtension` from Ruby.
-
 ## When RBS cannot help — the plugin escape hatch
 
 When a method's behaviour depends on the **shape of its
@@ -422,6 +397,6 @@ see [Chapter 9](09-plugins.md) and the
 
 ## What's next
 
-Chapter 8 covers the rule catalogue — what each diagnostic
-means, when it fires, and how to suppress it when it is wrong
-or noisy.
+Chapter 8 is about reading a diagnostic — what each rule
+family claims, why one fires when you did not expect it, and
+which layer to reach for when you want it quieter.

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

@@ -1,9 +1,16 @@
 # 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.
+A diagnostic is Rigor telling you something it proved about
+your code. This chapter is about *reading* one: what its parts
+mean, what each rule family is really claiming, why one fires
+when you did not expect it, why one stays silent when you did,
+and how to work a freshly-adopted project down to a clean run.
+
+The reference lives one door over. The full rule catalogue,
+each rule's evidence tier, the severity-profile table, and the
+exact syntax of every suppression form are in
+[Diagnostics](../manual/04-diagnostics.md) in the manual; this
+chapter links there rather than restating it.
 
 ## Anatomy of a diagnostic
 
@@ -33,251 +40,106 @@ 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.duplicate-hash-key` | Two entries of one Hash literal carry the same literal key (`{ a: 1, a: 2 }`, `m("x" => 1, "x" => 2)`) — the last entry wins silently at runtime. Literal keys only; `:a` vs `"a"` and `1` vs `1.0` are distinct keys and never compared. | 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
+### Confidence — reading the evidence tier
+
+Every built-in diagnostic carries an `evidence_tier` —
+`high` / `medium` / `low` — which is Rigor's own confidence
+that the firing is a *true positive*, derived from the rule's
+gates rather than from its severity. It is worth internalising
+as a reading habit rather than a config knob: a `high` firing
+(`call.undefined-method` on a concrete receiver) is almost
+always a real bug and can be acted on directly, while a `low`
+one (`call.unresolved-toplevel`) usually means the analyzer is
+missing context — an unanalyzed file, a monkey-patch it never
+saw — and reads better as "look at this" than "fix this". The
+tier never feeds severity, and never changes whether a
+diagnostic fires; it only routes your attention.
+
+The per-rule tiers, and the `documentation_url` field that
+rides alongside them in `--format json`, are in
+[manual — Evidence tier](../manual/04-diagnostics.md#evidence-tier).
+
+## The five families
+
+Every rule ID reads `family.rule`, and the family tells you
+what kind of proof failed. The catalogue — every rule, what it
+fires on, its evidence tier — is in
+[manual — Diagnostics](../manual/04-diagnostics.md#catalogue).
+What follows is what each family is *about*.
+
+**`call.*` — the call site's shape is wrong.** An undefined
+method, an arity no signature accepts, an argument whose type
+provably violates the parameter contract, a receiver that
+might be `nil`. These are the highest-volume diagnostics on
+real-world code, and also the most refined: every one of them
+fires only when Rigor can prove the underlying fact about a
+statically-known receiver, which is why a `call.*` firing is
+usually worth reading first.
+
+**`flow.*` — the control flow itself is unsound.** Something
+provably raises on every path, a branch is dead, a `case`
+clause can never match, a local is written and never read, a
+Hash literal repeats a key. `flow.unreachable-branch`,
+`flow.always-truthy-condition` and `flow.unreachable-clause`
+form the **reachability family** — each proves that a piece of
+code cannot run. `unreachable-clause` is the newest member and
+deliberately quieter than its siblings (`:info` under
+`balanced`) while its corpus false-positive gate finishes;
+bump it with `severity_overrides:` if you want it louder.
+
+**`def.*` — a definition violates the contract it declares.**
+A body whose return drifts from the declared RBS return, an
+instance variable written with two disagreeing types, an
+explicit-receiver call into a private method. The three
+`def.override-*` rules are the Liskov Substitution Principle's
+signature rule applied across a project-defined hierarchy
+(superclass chain plus included and prepended modules, resolved
+cross-file): returns may narrow, parameters may widen,
+visibility may not shrink. 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` | Only proven rules stay `error` (`call.undefined-method`, `wrong-arity`, `assert.type-mismatch`); uncertain rules drop to `warning`, and several to `off`. For incremental adoption on legacy code. |
-| `balanced` (default) | Most rules → `error`; uncertain rules → `warning`; `dump.type` → `info`. The shipped behaviour. |
-| `strict` | Nearly every rule → `error`. The exceptions: `call.self-undefined-method` stays `off` (opt-in only), and `flow.unreachable-clause` is `warning` (pending its false-positive gate). 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).
+**`assert.*` and `dump.*` — the introspection helpers.**
+`assert.type-mismatch` fires when an `assert_type("expected",
+value)` call disagrees with the inferred type, so a snippet in
+this handbook is a test of the engine as much as an
+illustration. `dump.type` is not a problem report at all — it
+is your probe during debugging: sprinkle `dump_type(value)`
+through suspicious code, run `rigor check`, and read the
+inferred types straight out of the diagnostic stream.
+
+## Turning a diagnostic down
+
+Rigor gives you five layers, and picking the right one is
+mostly a question of *how much* you want to say:
+
+1. **`severity_profile:`** — the project's overall stance.
+   `lenient` for a legacy codebase you are easing Rigor into,
+   `balanced` for everyday work, `strict` for a project with
+   no legacy noise.
+2. **`severity_overrides:`** — one rule (or one family) at a
+   different severity from the rest of the profile. The right
+   layer when a rule is *useful but not blocking* for you.
+3. **`disable:`** — the rule is off project-wide. Heavier than
+   an override to `off`; both work, and the choice is mostly
+   stylistic.
+4. **`# rigor:disable` / `# rigor:disable-file`** — this line,
+   or this file. The right layer when the analyzer is wrong
+   *here* and right everywhere else. Prefer it to a
+   project-wide switch: it keeps the exception visible next to
+   the code that needed it, and it is the thing you later
+   promote into an `RBS::Extended` directive.
+5. **A [baseline](../manual/06-baseline.md)** — the whole
+   existing backlog, recorded rather than hidden, so new
+   diagnostics still surface. This is the layer to reach for
+   on adoption day, and the one to reach for *instead of*
+   `disable:` when the rule is genuinely finding things you
+   have simply not fixed yet.
+
+The exact syntax of all five — profile table, override
+precedence, the three suppression forms, the baseline file and
+its `rigor baseline` commands — is in
+[manual — Diagnostics](../manual/04-diagnostics.md#severity-profiles)
+and [manual — Baselines](../manual/06-baseline.md).
 
 ## Why a diagnostic might NOT fire when you expected one
 
@@ -357,6 +219,11 @@ The pragmatic loop on a project that just adopted Rigor:
    `# rigor:disable` lines into `RBS::Extended` directives
    so the analyzer learns the real contract.
 
+On a codebase too large for step 2 in one sitting, record the
+existing diagnostics as a
+[baseline](../manual/06-baseline.md) first and run the loop
+against what CI newly surfaces.
+
 A clean `rigor check` run is the goal; a green CI badge says
 "every diagnostic that fires is one we accept."