rigortype 0.3.3 → 0.3.5

data/data/effects/registry.yml

@@ -0,0 +1,95 @@
+# Effect-label registry — the shared vocabulary of ADR-103 WD2, normative in
+# `docs/type-specification/effect-labels.md`.
+#
+# Hand-written, NOT generated: every row is a deliberate vocabulary decision. The generated
+# `data/builtins/ruby_core/*.yml` `purity:` facet answers fold-safety, not effects, and is never
+# read as a label source (ADR-103 WD3).
+#
+# `vocabulary` bumps only on a rename or a removal, never on a leaf addition — adding a leaf can
+# never change what a recognised bound admits, because subsumption is a segment-aware prefix test.
+# A renamed or removed spelling is recorded in `retired:` so a snapshot written by an older Rigor
+# still reads.
+vocabulary: 1
+
+# What each root means, in one line. Read by `rigor effects --list-labels` (#429), which is the only
+# way an installed Rigor can tell a reader what to write in `effects.envelopes:`, `effects.tolerated:`,
+# `effects.attribution:` or an `%a{rigor:v1:effect …}` annotation — four surfaces that all require
+# typing a label. `docs/manual/19-effect-labels.md`'s vocabulary table is the same wording for the same
+# reason; a root without a line here simply prints without one, which is what a plugin-opened root does.
+descriptions:
+  io: talks to something outside the process — a file, a socket, a database, a terminal, a subprocess
+  mutate: changes state in place, in the frame's own objects, the receiver, another object, or the class
+  nondet: reads something that differs between two otherwise identical runs
+  global: process-wide state — ENV, $stdout, a class variable
+  exit: can end the process
+  ffi: calls out through a foreign-function interface
+  telemetry: reports on the program rather than doing its work — logs, metrics, traces
+  email: sends mail, whatever the transport underneath is
+  job: hands work to a queue for another process to run
+  cache: reads or writes a cache, whatever backs it
+  failure: registered so a policy written for Steins, the sibling PHP analyzer, parses here; Rigor never
+    produces one, so a bound naming it is satisfied vacuously
+
+labels:
+  # Steins v1, verbatim (rigortype/steins `docs/type-specification/effects.md`). Shared vocabulary:
+  # a policy naming these labels must read the same against a PHP service and a Rails app.
+  - exit
+  - ffi
+  - global.read
+  - global.write
+  - io
+  - io.db
+  - io.fs
+  - io.fs.read
+  - io.fs.write
+  - io.input
+  - io.ipc
+  - io.net
+  - io.net.http
+  - io.output
+  - io.output.buffer
+  - io.output.header
+  - io.output.stdout
+  - io.output.stderr
+  - io.process
+  - io.signal
+  - mutate
+  - mutate.local
+  - nondet
+  - nondet.random
+  - nondet.time
+
+  # Ruby leaves under `mutate` (Steins ADR-0055's names; ADR-103 WD14). `mutate.self` is self's
+  # state, `mutate.instance` a receiver that is neither self nor frame-owned, `mutate.static`
+  # class-level state. Unknown ownership taints rather than producing a bare `mutate`.
+  - mutate.self
+  - mutate.instance
+  - mutate.static
+
+  # Proposed shared core leaves, to raise with Steins: a `SELECT` is a read whichever language
+  # issued it, an `INSERT` a write, `BEGIN`/`COMMIT` neither.
+  - io.db.read
+  - io.db.write
+  - io.db.transaction
+
+  # Steins carries these (its ADR-0042) and Rigor does not produce them: they name a failure arm's
+  # value provenance rather than an effect. Registered for the same reason `io.output.buffer` is —
+  # so a policy written against Steins parses here — and never inferred (ADR-103 WD16).
+  - failure
+  - failure.environment
+  - failure.input
+  - failure.resource
+
+  # Application-meaning roots. These are the labels a policy actually names ("presenters do not
+  # enqueue jobs") and the ones `tolerated:` grips, so a project must not need a plugin before it
+  # can write one. Rigor-owned and proposed to Steins, which holds ecosystem labels outside its
+  # builtin set and supplies them through a plugin manifest (ADR-103 WD16).
+  - telemetry
+  - email.send
+  - job.enqueue
+  - cache.read
+  - cache.write
+
+# Retired spellings: `old.label: [replacement, ...]`. Empty at vocabulary 1 — nothing has been
+# renamed or removed yet.
+retired: {}

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

@@ -165,6 +165,79 @@ 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).
 
+## Bounding what a method *does* — effect envelopes
+
+Every directive so far describes what a method returns. One
+describes what it *does*:
+
+```rbs
+class UserRepository
+  %a{rigor:v1:effect io.db}
+  def find: (Integer) -> User
+
+  %a{pure}
+  def slug: (String) -> String
+end
+```
+
+`%a{rigor:v1:effect io.db}` says "this method may touch the
+database, and nothing else the vocabulary names". `%a{pure}`
+says "nothing at all" — it is rbs' own purity annotation, the
+one Steep already reads, so Rigor honours the spelling that
+exists rather than inventing a synonym. Both tolerate mutating
+objects the method itself allocated and never let out, so a
+`%a{pure}` method may still build and fill a local array.
+
+The payload is a comma-separated list of bare labels
+(`%a{rigor:v1:effect io.db, nondet.time}`), from the vocabulary
+in
+[effect-labels.md](../type-specification/effect-labels.md).
+Write the annotation on a `class` or `module` declaration
+instead and it applies to every method of that class —
+reopenings and `attr_writer`-generated methods included, but
+never to subclasses. A method that carries its own envelope
+keeps it; nearest wins.
+
+The bound covers the method's whole *code*, including what it
+calls. A `find` declared `io.db` that reaches an HTTP request
+through a helper exceeds its envelope, and Rigor says so — on
+the Ruby `def`, naming the route it took:
+
+```text
+lib/user_repository.rb:12: warning: Method UserRepository#find
+performs io.net.http (Net::HTTP.get via PaymentGateway#charge),
+but is declared %a{rigor:v1:effect io.db} at sig/repo.rbs:3,
+so io.net.http exceeds the envelope.
+```
+
+Two things it will not do. It never reports an effect it only
+*suspects*: a call Rigor could not resolve makes the summary
+read "and possibly more", and possibly is not a finding. And
+none of this happens unless you asked for it — the check needs
+an `effects:` block in `.rigor.yml`, so an `%a{pure}` already
+sitting in your signatures for Steep's benefit stays inert
+until you opt in. Set `effects.check: false` to keep the
+`rigor effects` report and its snapshot while silencing the
+diagnostic. Inert is not the same as unmentioned: annotations
+with no `effects:` block earn one
+[`effect.annotations-unchecked`](../manual/04-diagnostics.md#rule-effect-annotations-unchecked)
+`:info` per run, so a bound nobody checks never goes unnoticed.
+
+Misspell a label and the annotation does not narrow to the part
+Rigor recognised — the **whole** tag reads as unbounded, so a
+typo can never turn into findings on correct code. That would
+be a silent loss of a contract you thought you had, so where
+the spelling is evidently meant to be a label Rigor says so:
+[`effect.unknown-label`](../manual/04-diagnostics.md#rule-effect-unknown-label),
+at the line you wrote it on, naming the nearest real label.
+A word that resembles nothing in the vocabulary stays silent —
+you may be opening a root of your own.
+
+The whole feature — the label vocabulary, the committed effect
+snapshot, and `rigor effects` itself — is
+[ADR-103](../adr/103-effect-labels.md); start with
+[`rigor effects`](../manual/02-cli-reference.md#rigor-effects).
+
 ## Worked example: an assertion gate
 
 ```rbs
@@ -299,11 +372,39 @@ class Slug
 end
 ```
 
-You **cannot** put these `%a{rigor:v1:…}` directives inside a
-`.rb` file. The directives only fire when read from RBS —
-that is a design choice (see
-ADR-5, the robustness principle: strict on returns, lenient
-on parameters).
+You can also write them **in a `.rb` file**, as rbs-inline
+`# @rbs %a{…}` comments:
+
+```rb
+# rbs_inline: enabled
+
+class Slug
+  # @rbs %a{rigor:v1:return: non-empty-string}
+  # @rbs id: String
+  # @rbs return: String
+  def normalise(id) = id.strip
+end
+```
+
+`%a{}` is *rbs-inline's own* grammar, not a Rigor dialect, and
+the annotation reaches Rigor through the ordinary path: the
+rbs-inline writer copies it verbatim onto the signature it
+generates, and that signature joins the same RBS environment
+your `sig/` tree lands in. So this is not a per-directive
+feature — every `RBS::Extended` directive is read from the same
+annotation object whichever buffer it arrived in — the effect
+envelopes above (`%a{pure}`, `%a{rigor:v1:effect …}`) included.
+Reading them requires the rbs-inline library, which Rigor
+ingests by default when it is installed
+([ADR-93](../adr/93-default-rbs-inline-ingestion.md)).
+
+What Rigor does **not** offer is a Rigor-only comment dialect —
+there is no `# rigor:effect` directive and no file pragma. The
+`# rigor:` comment family stays suppression-only (`disable`,
+`disable-file`). Application code never has to carry
+Rigor-specific syntax ([ADR-0](../adr/0-concept.md)); an
+upstream annotation form you may use if you want one is a
+different thing from a requirement.
 
 ## Inline RBS in Ruby source — the `rigor-rbs-inline` plugin
 

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

@@ -48,6 +48,7 @@ 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). |
+| `--no-tolerated-effects` | Check effect envelopes as if [`effects.tolerated:`](03-configuration.md) were empty — the audit switch for your discharge policy (ADR-103). Judgment only: the run, what it collects and its cache entry are identical either way, so this never costs a re-analysis. |
 | `--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
@@ -162,6 +163,247 @@ rigor type-scan PATH...
 unrecognized-node ratio exceeds `RATIO`, and `--format=text|json`
 selects the output format.
 
+## `rigor effects`
+
+Report what each method *does* — its effect labels — rather
+than what it returns, and manage the committed **effect
+snapshot** that gates drift. Opt-in and observational: nothing
+here emits a diagnostic or changes `rigor check`'s output, and
+only `rigor effects check` ever exits non-zero. The workflow
+around these verbs — the label vocabulary, how to read the
+report at scale, the review loop and the CI step — is
+[Effect labels](19-effect-labels.md).
+
+```sh
+rigor effects [PATH...]                       # the report
+rigor effects {update,check,diff,explain}     # the snapshot
+```
+
+With no paths the report analyses the configured `paths:`. It
+runs with effect collection enabled even when your `.rigor.yml`
+carries no `effects:` block, so you can try it before
+configuring anything; such an ad-hoc run shares no cache with
+`rigor check`, because a run served from that cache would have
+collected nothing.
+
+Passing paths narrows the **analysis**, not just the output.
+Labels are transitive over what was analysed, so a method whose
+callees were not analysed reports fewer labels and a wider
+"possibly more" than the same method in a whole-project run —
+honest, but not a cheaper way to get the whole-project answer.
+Filter the output when you want the real footprint.
+
+Each line is one method, sorted by key:
+
+```
+Tracer::Reporter#report: [io.output.stdout, nondet.time]
+Tracer::Gateway#fetch: [] …?
+    dynamic-receiver (external_gem_without_rbs)
+```
+
+The labels are the **transitive** footprint — the method's own
+plus every project method it reaches. A ` …?` suffix means the
+list is not exhaustive: some call could not be resolved, so the
+reading is "these effects, and possibly more". The indented
+lines say why. A taint is never a finding.
+
+A ` ≤ [...]` clause after the labels is the **declared** lane:
+what a source Rigor trusts but did not verify *claims* the
+method does. Two sources feed it — the plugins you activated,
+which on a framework application contribute most of it
+(`rails.session.write` and the rest of `rails.*` are Action
+Pack's rows, not yours), and the `effects.attribution:` table
+you wrote for gem methods nothing models. It is printed apart
+from the proven labels and never folded in among them, because
+the two answer different questions. It follows call edges exactly as
+the proven labels do, so a controller two hops above an
+attributed gem call carries the claim rather than only a
+"possibly more"; a declared label the proven list already
+covers is not printed twice.
+
+```
+Gateways::Client#fetch: [] ≤ [io.net.http] …?
+    plugin-attribution (Acme::Http.get)
+```
+
+Two kinds of method are omitted: one that proves nothing
+beyond `mutate.local` and claims nothing — mutation of objects
+its own frame allocated and never let out, which every effect
+envelope tolerates — and one with no label in either lane,
+which exists only to record that something below it was
+unresolved. `--full` lists both. `--pure` asks for the first
+group by name, which is the set worth annotating `%a{pure}`.
+
+`--label=LABEL` prints only the methods carrying `LABEL` or a
+label under it, in either lane. `--limit=N` caps the rows.
+`--why` expands each row's unresolved reasons and the plugin
+row behind each declared label, which are collapsed to a count
+by default. The report closes with a footer counting the two
+lanes apart, because they have different powers: a proven label
+can fail a build and a declared one cannot
+([ADR-103](../adr/103-effect-labels.md) § WD17).
+
+A `PATH` argument selects which methods are **printed**, never
+which are analysed: Rigor analyses your configured `paths:`
+either way, so a selected row carries exactly the labels the
+whole-project run gives it, and a note on stderr says how many
+of how many you are looking at. A path outside `paths:` is
+analysed as well as them, so pointing the command at a tree
+your configuration does not cover still works.
+
+`--format=text|json` selects the output format; the JSON
+payload additionally carries each method's *direct* summary
+broken down per origin. `--config=PATH` picks a config file.
+`--no-tolerated-effects` is accepted for symmetry with the
+subcommands and does nothing here: the report is an
+observation, and observations are undischarged.
+
+What is collected and how it propagates is
+[the effect-summaries internal spec](../internal-spec/effect-summaries.md).
+`--list-labels` prints the vocabulary this project can name —
+every shipped label with its root's meaning, plus whatever your
+plugins and your `effects.labels:` opened — and exits without
+analysing anything. The same table is in
+[Effect labels § The label vocabulary](19-effect-labels.md), and
+the grammar is specified normatively in the effect-labels
+specification, which the gem does not ship:
+<https://rigor.typedduck.fail/type-specification/effect-labels/>.
+
+### The effect snapshot
+
+Four subcommands manage a committed record of the effects
+Rigor observed — `.rigor-effects.yml`, the effect equivalent
+of `db/schema.rb`:
+
+```sh
+rigor effects update    # write the snapshot; commit it
+rigor effects check     # 0 fresh, 1 drift — the CI gate
+rigor effects diff      # the same comparison, never gating
+rigor effects explain   # why an entry point reaches a label
+```
+
+Unlike the report, the subcommands take no paths: a snapshot
+records the whole project, and one written over a subset would
+read as a project where every other method vanished. They all
+accept `--config=PATH`, `--format=text|json` and `--full`;
+`check`, `diff` and `explain` additionally accept
+`--baseline=PATH` (compare against a file other than the
+configured one — `--baseline <(git show
+origin/main:.rigor-effects.yml)` in a bot),
+`--strict-tolerated` and `--no-tolerated-effects`.
+
+The file records two tables. `methods:` holds each method's
+**direct** summary — what its own body does, block literals
+and catalogued callees included, but not what the project
+methods it calls do. That is deliberate: an entry moves only
+when its own lines changed, so the diff stays attributable to
+the pull request that caused it. `reach:` holds the
+**transitive** footprint at the entry points
+`effects.snapshot.reach:` names, where a leaf change is
+supposed to fan out — the fan-out is the blast radius.
+
+```yaml
+# .rigor-effects.yml — generated by `rigor effects update`. Commit it; review its diff.
+schema: 1
+rigor: "0.3.3"
+vocabulary: 1
+config_digest: "9ec82bfc…"
+methods:
+  "PaymentGateway#charge":
+    effects: ["io.net.http", "telemetry"]
+  "Reports::Nightly#perform":
+    effects: ["io.db.read"]
+    exhaustive: false
+    unresolved: ["dynamic-send"]
+reach:
+  "OrdersController#create":
+    effects: ["io.db.read", "io.net.http", "job.enqueue"]
+```
+
+A method is left out when it is exhaustive and proves nothing
+beyond `mutate.local`, when its summary is a synthesised
+accessor's, and when it carries no label in either lane — a
+row that would say only "not exhaustive, and here is why" is
+something `rigor effects` and `rigor effects explain` answer
+better than a committed record. `--full` records everything.
+The header carries
+the Rigor and vocabulary versions and a digest of your
+`effects:` block, so an upgrade or a policy edit shows up as a
+*regeneration event* rather than as silent reinterpretation.
+
+Under `methods:` the declared lane is what that method's own
+body claims; under `reach:` it is the transitive claim, like
+the proven labels beside it.
+
+`check` prints one line per difference: `+ label` / `- label`
+for the proven lane, `≤+` / `≤-` for the declared one,
+`materialised` when a declared label became proven,
+`exhaustive → not` when someone introduced a call Rigor cannot
+follow, and `+symbol` / `-symbol` for methods that appeared or
+vanished (a rename is one of each, counted in the footer). A
+removal read off a summary that is no longer exhaustive is
+printed hedged — "possibly more" cannot prove an absence.
+
+`effects.snapshot.gate:` decides what fails. `symmetric` (the
+default) fails on any drift: a job that stopped enqueueing is
+news too. `additions` is the ratchet — only growth fails.
+`effects.tolerated:` is applied at judgment time, never while
+writing: a difference confined to tolerated labels is printed
+under a `tolerated:` heading and does not fail the gate unless
+you pass `--strict-tolerated`. `--no-tolerated-effects` judges
+as if the list were empty; on `update` it changes nothing,
+because the record itself is undischarged.
+
+Discharge works **per origin**, not per label. `Logger#info`
+carries `io` and `telemetry` together, so `tolerated:
+[telemetry]` frees the `io` that came with the logging — and
+leaves an `io.fs.read` from a `File.read` two lines down
+exactly where it was. An added label is discharged only when
+every origin that introduces it is discharged.
+
+### Reviewing effect drift
+
+Day one, run `rigor effects update` and commit the result. The
+diff you are committing is the team's first map: which
+controllers reach the network, which jobs write, which
+presenters query.
+
+Add `rigor effects check` to CI. From then on a pull request
+that changes what the code *does* fails it with the reason
+spelled out:
+
+```
+Effect drift against .rigor-effects.yml:
+
+methods:
+  PaymentGateway#charge  + io.net.http
+
+reach:
+  OrdersController#create  + io.net.http
+
+Run `rigor effects update` and commit the result if this change is intended.
+```
+
+The author runs `rigor effects explain` to see the route —
+
+```
+reach:
+  OrdersController#create → OrderService#place → PaymentGateway#charge → Net::HTTP.get [io.net.http]
+```
+
+— then runs `rigor effects update` and commits the regenerated
+file. **Intent is expressed by committing the regenerated
+snapshot**, not by annotating the code; the reviewer reads the
+two-line diff alongside the code change and either nods or
+pushes back. A bundle update that moves effects with no code
+diff of its own works the same way, and is exactly the case
+worth seeing.
+
+None of this is a diagnostic. `rigor check`'s output and exit
+code are identical whether or not you use the snapshot, and
+drift is never a finding: whether it *matters* is the
+reviewer's judgment, which is what makes it a review artefact.
+
 ## `rigor explain`
 
 Print the catalogue entry for a diagnostic rule, or list every
@@ -300,6 +542,112 @@ rigor triage --format json | jq '[.selectors[] | select(.receiver == "String")]'
 The same `receiver_type` / `method_name` fields ride on each
 diagnostic of `rigor check --format json`, for per-site (rather than
 aggregated) grouping.
+## `rigor unused`
+
+Report project constants that nothing reachable references — a
+starting point for dead-code removal.
+
+```sh
+rigor unused [paths] --entry-point='lib/cli.rb'
+```
+
+**Read the output as a review queue, not a defect list.** On a
+hand-adjudicated corpus target only **7% of the rows were genuinely
+unused**; the rest were reachable by means static analysis cannot
+see. That is why this is a separate command and never a `rigor check`
+diagnostic — see
+[ADR-102](https://github.com/rigortype/rigor/blob/master/docs/adr/102-unused-code-reachability-report.md).
+
+Reachability is computed from **roots**, not by counting references,
+so a cluster of classes that only reference each other is still
+reported. Roots are the declarations in files matching
+`--entry-point=GLOB` (repeatable), anything referenced at file level
+by non-test code, and anything the project's **plugins** contribute.
+
+Plugin-supplied roots are where framework knowledge enters. A Rails
+controller is reached by name at request time, so nothing in the
+project references it and a reference index cannot tell a live
+controller from a dead one. `rigor-rails-routes` closes that by
+reading `config/routes.rb` statically and naming every controller it
+dispatches to — no Rails boot, and a route written under a
+conditional (`get "/beta", to: "beta#index" if ENV["BETA"]`) is
+visible where a booted app's route table would not show it. On two
+Rails corpus targets this removed 56 % and 84 % of the candidate list.
+
+`rigor unused` loads the same `plugins:` your `rigor check` run uses,
+and prints how many roots came from them:
+
+```
+  roots:                    404 (288 from plugins, 0 matched no declaration)
+```
+
+`matched no declaration` is the number a plugin claimed that this
+project does not declare — normally framework classes such as
+`Rails::HealthController`. A number climbing away from zero means a
+root source has drifted out of step with the code, which matters
+because an over-claiming root source silently *hides* dead code. A
+framework Rigor has no plugin for supplies no roots, so its
+controllers still read as candidates.
+
+`rigor-pundit` supplies the second kind of root: a policy class is
+reached as `PostPolicy` from `authorize @post`, a name that appears
+nowhere in the source. It publishes the policies your authorization
+calls actually name — not every class under `app/policies`, because a
+file's location is not evidence that anything authorizes against it.
+
+`rigor-sidekiq` shows how narrow a root source has to be to be worth
+having. A worker named as `class: "NightlyReportWorker"` in a cron
+schedule is enqueued from YAML, so its name appears nowhere in the
+code and it reads as dead — that name becomes a root. The queue list
+in the same `sidekiq.yml` does not: a queue name is not a class name,
+and inflecting one into a worker name would root a class on a naming
+coincidence.
+
+A plugin can also contribute a **reference** rather than a root, and
+`rigor-factorybot` is why the distinction exists. `factory :user,
+class: "Admin::User"` names a class as a string the scan cannot see,
+so it is real evidence of use — but a factory lives in the test tree.
+Supplied as a reference carrying the `test` role, the class leaves
+the candidate list and appears under *Reachable only from test code*;
+supplied as a root it would have been promoted to
+production-reachable, and the more interesting finding would have
+disappeared.
+
+Most bundled plugins deliberately contribute nothing.
+`MyJob.perform_later`, `MyMailer.welcome`, `MyWorker.perform_async`
+and `RSpec.describe User` all write the class name as an ordinary
+constant, which the report already records — and for the spec case,
+records with the `test` role that makes the section above possible.
+Each plugin's page says which choice it made and why.
+
+Three things the report separates rather than merges:
+
+- **Reachable only from test code** gets its own section — a class
+  used solely by its own spec is dead production code with a live
+  test, which is a more actionable finding than either bucket alone.
+- **Constants something can name at runtime** are demoted to a
+  `cannot decide` section with the reason, never claimed as unused.
+  `"Foo".constantize` names `Foo` exactly, so it counts as an ordinary
+  reference; `"Foo::#{key}".constantize` instead marks everything
+  under `Foo` undecidable. A class name appearing as a string in a
+  `.yml`, `.json`, or template file demotes it the same way — that is
+  weaker evidence than a constant reference, so it is neither proof of
+  use nor grounds to call it dead.
+- **Namespace modules** wrapping live code are excluded and counted,
+  because nothing references an intermediate namespace by itself. A
+  namespace whose contents are *all* unreachable is still reported.
+
+Only class and module constants are reported at all; value constants
+are omitted because they do not resolve across files.
+
+References are harvested from a wider file set than the analysed
+paths — `.rake` tasks, `config/`, specs and the project's own `sig/`
+all count as references — because a constant used only from a Rake
+task is not dead.
+
+`--format json` emits the same data; `--limit=N` truncates the
+printed lists. `--incremental` is refused: reachability is only sound
+over a whole-project run.
 
 ## `rigor coverage`
 
@@ -654,6 +1002,7 @@ Queued today:
 | `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. |
+| `effects-on-by-default` | behaviour | A project whose `.rigor.yml` carries no [`effects:`](03-configuration.md#effect-labels) key at all is treated as if it had written `effects: {}` — [effect collection](03-configuration.md#effect-labels), the `rigor effects` verbs' cache sharing, and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` explicitly still opts out. **Scheduled to graduate at v0.4.0** ([ADR-103](../adr/103-effect-labels.md) § WD15) rather than at the next major — an owner ruling specific to this feature, ahead of the general v1.0.0 majors-only cadence below. |
 
 Once a feature **graduates** — it becomes the default at a major
 ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7)
@@ -758,8 +1107,16 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 | Code | Meaning |
 | --- | --- |
 | `0` | Success — no error-severity diagnostics. |
-| `1` | Diagnostics found, or a per-command failure (parse error, missing file, new diagnostics on `diff`). |
-| `64` | Usage error — unknown command, bad flag, malformed argument. |
+| `1` | Diagnostics found, or a per-command failure (parse error, missing file, new diagnostics on `diff`, effect drift on `effects check`). |
+| `64` | Usage error — unknown command, bad flag, malformed argument, or a value in `.rigor.yml` the loader cannot proceed on. |
 
 `rigor triage` is the exception: it is advisory and always
 exits `0`.
+
+A configuration mistake prints one `rigor:` line naming the key
+and nothing else — no backtrace, on every command:
+
+```
+$ rigor effects update
+rigor: effects.attribution key is not a method key (`Owner#method` / `Owner.method`): "Net::HTTP get"
+```