# Rules

Every rule states a factual, whole-program claim ("no UI code matches this
state"), scoped to the code that was scanned. Evidence is `path:line:` plus a
bounded source excerpt with string literals elided. Precision below is
**factual** precision: how often the claim holds, not how often it is worth
acting on. A rule that cannot be validated is demoted or removed.

## Evidence per rule

Measured on the dogfood apps (nuwayze, dex, word_alive, tick).

| Rule | Evidence |
| --- | --- |
| `emitted-not-rendered` | 79/79 claims factual on nuwayze main (adjudicator with passing controls). One finding per unobserved union and per unobserved marker class. Drops to info when the UI reads the union's payload through base-class fields. |
| `rendered-not-emitted` | Fixture contract; suppressed with a reason when the owner emits through helper methods. Worded as "probably unreachable": only the scanned code is known. |
| `loading-not-reset` | Fixture contract; the dogfood apps guard correctly. |
| `loading-flag-not-reset` | 7/7 on dex, hand-adjudicated. |
| `event-without-handler` | Fixture contract; 168 dispatch sites on nuwayze all map to a handler. Follows the event hierarchy (`on<Base>` covers subtypes) and blocs sharing an event type. |
| `dead-handler` | 77/77 on nuwayze (adjudicator). The message names the directories scanned; events built only in tests are not features. |
| `riverpod-async-gap` | 10 hand-adjudicated findings (word_alive, tick). Recognises `.when`, `AsyncError`/`AsyncLoading` patterns and values stored in locals. `bool` providers are downgraded to info. |
| `notifier-never-notifies` | Fixture contract only; no real-code true positives yet. Limited to observable fields; lifecycle hooks excluded. |
| `notifier-inert-consumer` | Fixture contract only. |
| `provider-read-in-build` | 1 finding from 447 `context.read` calls on nuwayze. Reads inside closures are excluded by design. |
| `notifier-field-unread` | 3 on nuwayze; medium confidence, since a name match elsewhere can mask an unread member. |
| `provider-created-in-build` | Info, once per build method: the claim is factual, but impact depends on how often the widget rebuilds. |

## A factual finding is not always a bug

`emitted-not-rendered` at high confidence can be deliberate: dormant scaffolding
or a retired feature. Those findings are one decision per union, and the
remediation asks to check the repo's docs and action contracts before deleting
anything.

## How precision is measured

`tool/adjudicate.py <repo>` re-derives the two highest-volume claims
(`emitted-not-rendered`, `dead-handler`) with its own regex evidence, and prints
controls first: it must find evidence for every variant pipe calls rendered and
every event pipe calls dispatched. Controls are three-way (found /
unattributable / missing), and only *missing* fails. A corpus with no control
material reports **NO SIGNAL** and undefined precision. The script exits
non-zero whenever it cannot certify.

Limits: it is only partly independent (the list of variants, events and owners
to check comes from pipe's `state` output), it judges the factual claim only,
not severity, and it needs a clean working tree.

## Recall

1. **Rule contracts.** `test/rule_contract_test.dart` requires each rule to fire
   on a positive control and stay silent on an adjacent negative control. A rule
   without both fails the build.
2. **Labelled real bugs.** `pipe recall` evaluates `recall/manifest.json`. An
   `open` case must be found; a `fixed` case must stay quiet, and reappearing is
   a **REGRESSION**. Repos missing from the machine are *skipped*, never passed.
   Results reflect each repo's working tree.

The labelled set is small: it bounds the risk of false negatives, it does not
prove their absence.

## provider and ChangeNotifier

Modelled: every provider-package declaration type (`Provider`,
`ChangeNotifierProvider`, `ListenableProvider`, `ValueListenableProvider`,
`FutureProvider`, `StreamProvider`, `StateProvider`, `ProxyProvider` and
variants, `.value`), and `Consumer`, `Selector`, `ListenableBuilder` and
`AnimatedBuilder` as consumers. Declarations are told apart from Riverpod by
`create:`/`update:`/`value:` arguments, not by import, so an unrelated class
named `Provider` taking `create:` would be miscounted.

Not modelled: `ProxyProvider` `update` functions returning unchanged values, and
rebuild frequency.

## Other limits

Not modelled: `bloc_concurrency` transformers, freezed unions whose generated
file is absent, and `ref.read` call sites.

pipe deliberately does not reimplement per-file checks the ecosystem already
does well: `unawaited_futures`, `use_build_context_synchronously`,
`cancel_subscriptions`, `close_sinks`, `bloc_lint`, or declaration-level dead
code (`undead`, `dallow`).