rigortype 0.3.0 → 0.3.2

data/docs/handbook/09-plugins.md

@@ -9,9 +9,10 @@ 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.
+[`plugins/`](../../plugins/README.md), and activating one is
+[manual — Using plugins](../manual/07-plugins.md). Read on to
+decide whether you need a plugin; go to `examples/` once you
+want to write one.
 
 ## When you reach for a plugin
 
@@ -51,151 +52,60 @@ compares the six worked examples on architectural axes
 engine-collaboration via `Scope#type_of`, cross-plugin facts,
 return-type contributions, …) and recommends a reading order.
 
-## What a plugin can do today
+## Two authoring paths
 
 > 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:)` /
-   `narrowing_facts(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
-   `narrowing_facts` block contributes branch-narrowing facts.
-   (`narrowing_facts` was renamed from `type_specifier` in ADR-80;
-   `type_specifier` remains as a deprecating alias removed in 0.3.0,
-   so use `narrowing_facts` in new plugins.)
-   (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.
+> there." What follows is for when it is "yes."
+
+The decision that shapes everything else is *which* of the two
+authoring paths your DSL falls into.
+
+**Declare it.** If the DSL is a class-level call with literal
+symbol arguments — a Rails-style `has_one_attached`, a
+dry-struct `attribute`, a Devise `devise :strategy`, a Sinatra
+`get "/foo" do … end` — the **macro-expansion substrate**
+([ADR-16](../adr/16-macro-expansion.md)) already knows that
+shape. You write a manifest entry describing the call, and the
+substrate does the literal-symbol extraction, the name
+interpolation and the per-method synthesis. The three bundled
+plugins on this path are 60–110 lines of declarative Ruby with
+no AST walking at all. The substrate also understands
+`ActiveSupport::Concern`'s deferred `included do … end` block,
+so a DSL call written inside a concern lands on the class that
+includes it rather than on the concern.
+
+**Walk it.** If the type depends on something the shape of the
+call cannot tell you — argument *values* (`Lisp.eval` above), a
+declaration made elsewhere in the project, or the contents of
+an external file such as a route table or a schema dump — you
+write a walker instead, and the plugin contract gives you the
+hooks for it: a per-file emission pass, per-call-site
+return-type and flow-narrowing contributions, sandboxed file
+and HTTPS reads under a trust policy, cached producers for
+expensive parses, and a cross-plugin fact store so one plugin's
+parse feeds another plugin's checks.
+
+The two paths coexist — one plugin can declare substrate
+entries *and* walk files — and where you go next depends on
+which of them you need:
+
+- [`examples/README.md`](../../examples/README.md) — the six
+  walkthroughs, each spotlighting one contract surface, with a
+  map of which example demonstrates which one.
+- [`docs/internal-spec/plugin.md`](../internal-spec/plugin.md)
+  — the binding plugin contract: manifest, hooks, services,
+  registry, load order. Its siblings
+  [`plugin-trust.md`](../internal-spec/plugin-trust.md) and
+  [`plugin-cache-producers.md`](../internal-spec/plugin-cache-producers.md)
+  cover the I/O and caching surfaces.
+- [`docs/internal-spec/macro-substrate.md`](../internal-spec/macro-substrate.md)
+  — the substrate's tiers, the manifest field each one
+  declares, and how much return-type precision each recovers.
+- [The macro-expansion library survey](../notes/20260515-macro-expansion-library-survey.md)
+  — which real Ruby libraries fit which tier, and which fall
+  outside the substrate entirely.
 
 ## Should you write one?
 

data/docs/handbook/README.md

@@ -56,9 +56,11 @@ up the flag, key, or command that *acts* on it.
    how to nudge it through `.rbs` files and `%a{rigor:v1:…}`
    directives.
 8. [**Understanding errors**](08-understanding-errors.md) —
-   the rule catalogue (`call.undefined-method`,
-   `call.argument-type-mismatch`, `flow.always-raises`, …),
-   severity profiles, and `# rigor:disable` suppression.
+   reading a diagnostic: what each rule family claims, why one
+   fires when you did not expect it (and stays silent when you
+   did), and which layer to reach for when you want it quieter.
+   The catalogue itself is
+   [manual — Diagnostics](../manual/04-diagnostics.md).
 9. [**Plugins**](09-plugins.md) — when to author one,
    pointer to the [examples/](../../examples/README.md)
    landing page.

data/docs/handbook/appendix-liskov.md

@@ -571,8 +571,10 @@ model"](appendix-type-theory.md#what-rigor-does-not-model) records.
   authoring the declared contracts `def.return-type-mismatch` checks
   against.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md) for
-  the `def.return-type-mismatch` / `call.argument-type-mismatch`
-  rules and severity profiles.
+  what the `def.*` family claims, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  `def.return-type-mismatch` / `call.argument-type-mismatch`
+  entries and the severity profiles.
 
 If you want to compare against another *tool* rather than the
 *principle*, the sibling appendices cover

data/docs/handbook/appendix-phpstan.md

@@ -72,8 +72,10 @@ in another tab, almost every advanced refinement transfers.
 ## The `@phpstan-assert` family
 
 PHPStan's assertion-narrowing PHPDoc tags map directly onto
-Rigor's `RBS::Extended` directive grammar. Chapter 7 covers
-the table in depth; here it is again for reference:
+Rigor's `RBS::Extended` directive grammar. This is the mapping;
+[Chapter 7](07-rbs-and-extended.md) works the Rigor side
+through examples, and the directive reference itself is
+[manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md):
 
 | PHPStan PHPDoc | Rigor RBS::Extended | Effect |
 | --- | --- | --- |
@@ -149,7 +151,8 @@ Rigor has two baseline mechanisms: a **managed** baseline
 the next `rigor check` via the `baseline:` config key — the
 closest match to PHPStan's `--baseline`), and a **lightweight**
 ad-hoc snapshot (`rigor diff` over a `--format=json` dump).
-Chapter 8 has the walkthrough.
+[Manual — Baselines](../manual/06-baseline.md) walks through
+both.
 
 The `includes:` semantics also match PHPStan's: declaration
 order, later overrides earlier, the current file's keys win
@@ -322,11 +325,15 @@ You probably do not need to read the rest of this appendix
 section sequentially. Three useful pointers:
 
 - [Chapter 7 — RBS and `RBS::Extended`](07-rbs-and-extended.md)
-  has the full directive grammar, including the PHPStan-mapping
-  table that this page summarises.
+  works the directive grammar through examples; the reference
+  table is
+  [manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md).
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  covers the rule catalogue, severity profiles, baseline
-  diffing — every PHPStan onboarding analogue.
+  explains how to read a diagnostic and which knob to reach
+  for; the catalogue, severity profiles and baselines — every
+  PHPStan onboarding analogue — are
+  [manual — Diagnostics](../manual/04-diagnostics.md) and
+  [manual — Baselines](../manual/06-baseline.md).
 - [Chapter 9 — Plugins](09-plugins.md) for the
   Type-Specifying / Dynamic-Return analogues.
 

data/docs/handbook/appendix-steep.md

@@ -321,8 +321,10 @@ section sequentially. Three useful pointers:
   if you want to see how the directive grammar layers on top
   of the RBS you already write.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue, severity profiles, and baseline
-  diffing — the analogue to Steep's diagnostic config.
+  for how to read a diagnostic, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue and severity profiles — the analogue to
+  Steep's diagnostic config.
 - [`docs/notes/20260503-steep-cross-check-triage.md`](../notes/20260503-steep-cross-check-triage.md)
   for a worked side-by-side run of Steep and Rigor on the
   same project (the project itself).

data/docs/handbook/appendix-type-theory.md

@@ -1651,7 +1651,9 @@ practical companion:
   for the directive grammar that lets you teach Rigor about a
   custom predicate.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue (the user-visible end of the trinary
+  for how a diagnostic reads, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue (the user-visible end of the trinary
   certainty).
 
 If you want to compare against another *tool* rather than the

data/docs/manual/02-cli-reference.md

@@ -48,11 +48,38 @@ the `paths:` list from the configuration file.
 | `--treat-all-as-inline-rbs` | Force-load `rigor-rbs-inline` with `require_magic_comment: false`, so every analysed file is treated as inline-RBS without the `# rbs_inline: enabled` comment (ADR-32). |
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
-| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. |
+| `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
 any are reported, `64` on a usage error.
 
+### Editor mode scope
+
+`--tmp-file` / `--instead-of` on their own analyse **only** the
+buffer's file: fast, and blind to what the unsaved edit does to the
+rest of the project.
+
+Adding `--incremental` analyses the **whole project with the buffer
+substituted** — the edited file and the files that depend on it are
+re-analysed, everything else is served from the incremental snapshot.
+An unsaved change to a method's return type therefore surfaces in its
+callers, not just in the file being edited.
+
+Two things to know:
+
+- It needs a snapshot to reuse. Run `rigor check --incremental` once
+  (it is also what a normal terminal check should use) and every later
+  editor invocation gets whole-project scope. Without one, Rigor says
+  so on stderr and analyses the buffer alone.
+- An editor-mode run never writes the snapshot — the buffer's bytes
+  exist only in your editor, and recording them would make the next
+  ordinary run believe it had already analysed a file in a state it
+  was never in.
+
+`--verify-incremental` refuses a buffer: it compares against a full
+analysis of the files on disk, which a buffer contradicts by
+construction.
+
 ## `rigor init`
 
 Write a starter configuration file.
@@ -333,7 +360,10 @@ the effectiveness ratio and `--format=json` carries `mode`,
 `killed`, `survived`, `effectiveness_ratio`, per-file rows, and
 `add_a_type_here`. It is the truth tier behind the static
 `--protection` proxy, at the cost of many analyses — an opt-in CI
-deep-dive, not an interactive check.
+deep-dive, not an interactive check. `--workers=N` fork-parallelizes
+this tier too (the whole-project pre-pass is paid once on the parent
+and the per-file measurement is spread across workers), with the
+same precedence chain and the same byte-identical output.
 
 ```sh
 rigor coverage --protection --mutation [paths]
@@ -352,7 +382,10 @@ cost is proportional to the protection hole. `--format=json`
 carries `mode` (`protection-fused`), `type_killed`,
 `test_killed`, `unprotected`, `protected_ratio`, per-file rows,
 and `add_protection_here`; `--threshold` gates on the fused
-ratio.
+ratio. This tier is always sequential — the suite hook shells out
+to your test runner, and concurrent runs would race over one
+working tree — so `--workers` does not apply and an explicit one
+is reported as ignored on stderr.
 
 `--test-command=CMD` is the runner hook (default
 `bundle exec rake`). The suite must pass on clean code first, or
@@ -378,6 +411,18 @@ to a deterministic sample of `N` mutations per file, bounding the
 cost on large files. Per-file ratios then become estimates, noted
 on stderr so `--format=json` stdout stays clean.
 
+A re-run is served from a per-file measurement cache while
+nothing that could change a file's number has moved: the file
+itself, any file it was recorded as reading from, the resolved
+configuration, `sig/`, the gem set, the engine version, `--limit`
+/ `--seed`, and the adopted bleeding-edge features. It reads the
+cross-file edges a `rigor check --incremental` run records, so
+warm one once per project; without a usable snapshot every file
+is measured, never silently served. `--no-cache` measures
+everything from scratch. A one-line stderr report says which of
+those happened — see
+[Type-protection coverage](15-type-protection-coverage.md).
+
 ```sh
 rigor coverage --protection --mutation --with-tests \
   --test-command "bundle exec rspec" --include-dynamic [paths]
@@ -479,6 +524,7 @@ so a skill can never be shadowed by a verb.
 
 ```sh
 rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
+rigor skill describe [--deep]
 ```
 
 | Form | Purpose |
@@ -488,6 +534,33 @@ rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 | `--full <name>` | Print the `SKILL.md` body **followed by every `references/*.md` inline** — the complete, version-current procedure in one call. This is what a skill's "First: load the version-current copy" directive points at, so a copy vendored into a project (e.g. via `npx skills add`) re-fetches its current steps from the installed gem instead of following a frozen copy. |
 | `--path <name>` | Print the single-line absolute `SKILL.md` path, suitable as input to a file-reading tool. |
 | `--describe` | Probe the project's state (config / baseline / `sig/` / CI — presence only, never runs `rigor check`) and recommend the next skill to run. Also spelled `describe`; surfaced top-level as [`rigor describe`](#rigor-describe) below. |
+| `describe --deep` | The same report, except it **runs `rigor check` first** and routes the headline recommendation on the result. Opt-in, because it costs a full analysis and writes `.rigor/cache` — the un-flagged form stays presence-only and side-effect-free. |
+
+### `describe --deep`
+
+By default the recommendation comes from a presence-only probe, so it can
+tell that a project *has* a config but not whether the analysis is
+healthy. `--deep` runs the check for you and lets the result pick the
+headline, using the same routing the `## For the agent` section already
+teaches:
+
+| Deep check result | Headline becomes |
+| --- | --- |
+| RBS environment built to 0 classes, or a `configuration-error` diagnostic | `rigor-doctor` — the analysis is hollow until the setup is fixed. |
+| Call sites resolving to the project's own definitions (reopened core / gem classes), as at least a third of the errors | `rigor-monkeypatch-resolve` — list them in `pre_eval:` and they clear wholesale. |
+| Any remaining error diagnostics | `rigor-baseline-reduce`. Proven monkey-patch sites below that share are still reported here, so the finding survives even when the headline stays on the larger problem. |
+| Clean, or the project has no config yet | Unchanged — the presence-only recommendation stands. |
+
+If the check **cannot run at all** (no config, an unloadable plugin, a
+malformed config) `--deep` does not fail and does not pretend the project
+is clean: it reports what went wrong, falls back to the presence-only
+recommendation, and points you at `rigor doctor`. It deliberately does
+*not* route on weaker signals — "framework calls typing as `Dynamic`" is
+still a judgement call left to you and your agent.
+
+```sh
+rigor skill describe --deep   # also: rigor describe --deep
+```
 
 The verb spellings `rigor skill list` / `print <name>` / `path <name>`
 were **removed in v0.3.0** — the positional slot is a skill name, so
@@ -511,6 +584,10 @@ It reports a presence-only project-state probe (does a `.rigor.yml`,
 recommended next skill. It is read-only and side-effect-free — it never
 runs `rigor check`. Identical output to `rigor skill describe`.
 
+`rigor describe --deep` forwards to
+[`rigor skill describe --deep`](#rigor-skill), which opts into running the
+check first — slow, and it writes the cache.
+
 ## `rigor docs`
 
 Print the documentation bundled inside the `rigortype` gem
@@ -546,7 +623,7 @@ pages from the installed gem with no HTTP request.
 ## `rigor show-bleedingedge`
 
 Print the **bleeding-edge overlay** — the Rigor-maintained set of
-the next major's queued diagnostic disciplines ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
+the next major's queued changes ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md)
 § WD2) — and report which of them the project's
 [`bleeding_edge:`](03-configuration.md) configuration adopts. Read-only:
 it loads `.rigor.yml` to resolve the active selection but runs no
@@ -561,16 +638,31 @@ rigor show-bleedingedge [--config PATH] [--format text|json]
 | `--config PATH` | Use this `.rigor.yml` instead of auto-discovery. |
 | `--format text\|json` | Output format. Default `text`. |
 
-Each queued feature appears with its stable id, the severity it imposes,
-and whether your configuration adopts it. See
-[`docs/compatibility.md`](../compatibility.md) for how bleeding-edge fits
-the stability model.
+Each queued feature appears with its stable id, its **kind** — `severity`
+or `behaviour` — and whether your configuration adopts it. A `severity`
+feature also prints the rule → severity diff it imposes; a `behaviour`
+feature changes a measurement, an algorithm, or a default without moving
+any rule's severity, so it has no such diff and its summary is the whole
+description. See [`docs/compatibility.md`](../compatibility.md) for how
+bleeding-edge fits the stability model.
 
 Queued today:
 
-| Feature id | What it changes |
-| --- | --- |
-| `reject-unparseable-signatures` | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
+| Feature id | Kind | What it changes |
+| --- | --- | --- |
+| `reject-unparseable-signatures` | severity | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
+| `use-of-void-value` | severity | Using a value recovered from an author-declared `-> void` return in value context is reported as `static.value-use.void` (`warning`). |
+| `discovery-seeded-mutation-sites` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) measures against the same cross-file project discovery Tier 1 already uses — both when picking the sites and when deciding whether a breakage was caught — so a call on a project class declared in a *sibling* file is measured instead of dropped, and a breakage there can actually be caught. **Adds sites to the denominator, so the reported effectiveness ratio moves** — check it against any `--threshold` you pin in CI before adopting. |
+| `dependent-closure-kill-oracle` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) counts a breakage as caught when the diagnostic appears anywhere in the mutated file **or the files that depend on it**, instead of in the mutated file alone — so changing what a method returns counts as caught when the error lands in its callers. Can only **add** kills, so the ratio moves up or not at all; it costs about a third more wall time per mutant, and a ratio measured under it is not comparable with one measured without it. |
+
+Once a feature **graduates** — it becomes the default at a major
+([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7)
+— it leaves the queued list and appears under `Graduated`, an
+acknowledgement that naming it in `bleeding_edge:` no longer does
+anything: the behaviour is on for everyone. The section is absent while
+nothing has graduated. In `--format json` the same information is the
+`graduated` array, alongside `overlay` (every queued feature, each with
+its `kind`), `active`, and `unknown_selected`.
 
 ## `rigor doctor`
 

data/docs/manual/03-configuration.md

@@ -116,7 +116,22 @@ statically and may resolve at run time. The same findings appear in the
 | `severity_profile` | String | `"balanced"` | `lenient`, `balanced`, or `strict` — see [Diagnostics](04-diagnostics.md). |
 | `severity_overrides` | Hash | `{}` | Per-rule / per-family severity, e.g. `{ call: warning, flow.always-truthy-condition: off }`. |
 | `baseline` | String / `false` | `nil` | Path to a `.rigor-baseline.yml`, or `false` to disable an inherited one. See [Baselines](06-baseline.md). |
-| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued diagnostic disciplines early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
+| `bleeding_edge` | Boolean / Array / Hash | `false` | Adopt the next major's queued changes early ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD2). `false` adopts none; `true` adopts the whole overlay; a list of feature ids adopts only those; `{ all: true, except: [ids] }` adopts all but the named. Orthogonal to `severity_profile`. Override it for a single run with [`rigor check --bleeding-edge[=ids]`](02-cli-reference.md#rigor-check) / `--no-bleeding-edge`. Inspect with [`rigor show-bleedingedge`](02-cli-reference.md#rigor-show-bleedingedge). |
+
+A queued feature is one of two kinds, and `bleeding_edge:` selects both the
+same way:
+
+- A **severity** feature promotes one or more rules — a discipline Rigor
+  already reports quietly becomes an error or a warning. Its diff is a list
+  of rule ids, printed by `rigor show-bleedingedge`.
+- A **behaviour** feature changes a measurement, an algorithm, or a
+  default, and moves no rule's severity. There is no rule-id diff to read,
+  so its summary in `rigor show-bleedingedge` is the whole description of
+  what adopting it does.
+
+An id you name that this version of Rigor does not know is ignored rather
+than rejected, so a shared `.rigor.yml` can name a feature that only some
+of the versions in use have queued.
 
 ### Dependency RBS discovery
 

data/docs/manual/04-diagnostics.md

@@ -97,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`:
@@ -109,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`)
 
@@ -198,7 +220,10 @@ 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
@@ -217,7 +242,14 @@ 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: