@drkmttr/adhere 0.9.5 → 0.11.0

package/README.md

@@ -1,20 +1,33 @@
-# adhere
+<div align="center">
+<h1>adhere</h1>
+  <sup>A linter for non-deterministic rules. Powered by Typesafe</sup>
+</div>
 
-A linter for rules a normal linter cannot check. A rule is a one-sentence
-description in RFC 2119's words, like "business logic must live in services",
-with code that must be written that way, code that must never be, or both. For
-each source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
+A linter for rules a normal linter cannot check. Describe rules using RFC2119
+language, like "business logic MUST live in services", or "A 3rd-party API going down
+SHOULD NOT also take us down". A rule also includes a good example, a bad example, or 
+both (which is highly recommended according to [our studies](eval/studies/example-count.md).) 
+
+For each source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
 model) whether the file breaks each rule, gets a calibrated probability per
-rule, and reports the ones above a threshold with the line Jev points at. The
-report uses the same frame as `vp lint`.
+rule, and reports the ones above a threshold with the section of the file Jev
+points at. The report uses the same frame as `vp lint`.
+
+Here's a demo of what the output looks like:
+
+<a href="https://asciinema.org/a/1266511" target="_blank"><img width="400" src="https://asciinema.org/a/1266511.svg" /></a>
+
 
-Deterministic rules (substring matches, type checks) belong in a normal linter;
-`adhere validate` points out a rule that looks like one.
+Rules a normal linter can check exactly, such as a banned import or a type
+error, belong in that linter. While it lints, adhere asks Jev whether a normal
+linter could check each of your rules, and [`adhere validate`](#validate) lists
+rules that it thinks belong in a regular linter, and also detects any
+contradictions in your rules.
 
-A preset for effect is included which can be run without setup:
+Presets for TypeScript, React, security, Effect, and alchemy are included, and run without setup:
 
 ```sh
-TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset effect
+TYPESAFE_API_KEY=xxx npx @drkmttr/adhere lint --preset typescript
 ```
 
 ## Install
@@ -27,7 +40,7 @@ To pin the version in a repo, for CI or scripts, add it as a dev dependency
 and run `npx adhere`.
 
 `adhere` is a prebuilt executable for macOS and Linux on arm64 and x64 and for
-Windows on x64. .
+Windows on x64.
 
 adhere sends each file it judges to Jev at `api.typesafe.ai`, authenticated
 with a TypeSafe AI API key: the one `adhere login` saved, or
@@ -36,7 +49,7 @@ with a TypeSafe AI API key: the one `adhere login` saved, or
 ## Quick start
 
 ```sh
-adhere init                          # .adhere/config.ts and two example rules
+adhere init                          # .adhere/config.ts, two example rules, and the dependency
 adhere login                         # save your TypeSafe AI API key, once
 adhere validate                      # Checks your rules' wording, and contradictions using Jev
 adhere lint                          # audit the working directory
@@ -49,6 +62,9 @@ built-in Effect rules. A finding looks like this:
 ```text
   × data/brand-ports (0.93): A port must be a branded, range-checked integer, never a bare number.
    ╭─[src/server.ts:6:3]
+ 1 │ import { Effect } from "effect";
+ 2 │ import { listen } from "./listen.ts";
+ 3 │
  4 │ export const serve = Effect.gen(function* () {
  5 │   const host = process.env.HOST ?? "localhost";
  6 │   const port: number = Number(process.env.PORT ?? 3000);
@@ -68,17 +84,45 @@ Found 1 error.
 
 The header is the rule id, Jev's probability, and the rule's description. A
 preset's rule has the preset's name first, as in
-`effect/basics/external-calls-are-resilient`, so a report that mixes presets
+`effect/basics/gen-for-sequencing`, so a report that mixes presets
 with a repo's own rules says where each came from.
-Under it is the line Jev points at, underlined, with the code around it: the
-largest statement around the line that is 30 lines or fewer, usually the whole
-function, and up to 3 lines of whole statements on either side. The
-hint is the rule's code that must be written; a rule with only code that must
-never be written shows that code, labeled `never:`, instead. On a terminal, the report is in color and the code
-in it is highlighted. The exit code is 0 when nothing is reported and 1 when
-something is. It is also 1 when the run refuses, for example on an invalid
-config or rule file, a missing API key, or an unknown command or flag; a
-refusal prints its reason.
+Under it is the section of the file Jev points at, with the line it names
+underlined, or the lines, when it names several, marked with a bar beside the
+code. adhere splits each file into sections of whole statements, such as
+its imports, constants, and functions, packed in order into runs of at most 30
+lines; a class or function longer than that splits into its methods or the
+statements of its body. Jev reads the file as these sections and chooses one,
+and in the same request the line in it where the violation starts and the one
+where it ends: on the eval it judged as well that way, and the lines it named
+held a violation for 94% of real findings, most often as one line. When it
+names no lines, the section is shown alone, at its first line.
+
+Jev is also asked whether the file shows enough to decide the rule at all:
+whether it turns on something the file does not show, such as what another
+file, a library, or a service does. When Jev's probability that it does is
+below 0.6, the finding gets a warning under its code, with the probability
+that it does not, and help on adding what is missing:
+
+```text
+  warning: this file may not show enough to check this rule (Jev: 0.55 that it does not)
+     help: add what the code relies on outside this file as a note Jev reads:
+           // @adhere <the fact>, and how you know it
+```
+
+On the eval, most findings with this warning were false, where about one in
+five of all findings was: check what the code relies on outside the file
+before acting on it. What you find can go in an `@adhere` note, which Jev
+reads (see [Comments](#comments)). `sufficiencyThreshold` in the config, or `--sufficiency-threshold`, sets
+the cutoff. The warning changes neither the finding's level nor the exit code.
+
+The hint is the rule's code that must be written; a rule with only code that must
+never be written shows that code, labeled `never:`, instead. A rule whose
+level is `warning` reports its findings with `⚠` in place of `×`, in amber. On
+a terminal, the report is in color and the code in it is highlighted. The exit
+code is 1 when an error is reported, and 0 when nothing is, or only warnings;
+`--deny-warnings` fails the run on warnings too. It is also 1 when the run
+refuses, for example on an invalid config or rule file, a missing API key, or
+an unknown command or flag; a refusal prints its reason.
 
 ## Usage
 
@@ -86,10 +130,12 @@ refusal prints its reason.
 adhere lint                    # audit the working directory
 adhere lint --preset effect    # add a built-in rule set; the config becomes optional
 adhere lint --threshold 0.9    # replace the config's threshold; per-rule thresholds still apply
+adhere lint --sufficiency-threshold 0.5  # warn on fewer findings that may turn on other files
 adhere lint --yes              # send the requests without asking first
 adhere lint --limit 500        # judge at most 500 checks; the rest wait for the next run
 adhere lint --rpm 30           # send at most 30 requests a minute
 adhere lint --filter 'src/**'  # read only the files a glob matches
+adhere lint --deny-warnings    # fail on warnings as well as errors
 adhere lint --log-level debug  # log each request to Jev on stderr
 adhere validate                # check the rules' wording; ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
@@ -121,15 +167,10 @@ Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, a
 The cost is adhere's estimate of the input tokens times the model's price.
 Jev charges only for input tokens: $0.042 a million for `jev-latest`, per
 [TypeSafe AI's models page](https://docs.typesafe.ai/models) in September 2026.
-The estimate runs about a tenth high, and locating findings, which depends on
-what judging finds, comes on top. For a model adhere has no price for, the plan
-gives the tokens alone.
+For a model adhere has no price for, the plan gives the tokens alone.
 
 It asks only with a terminal on stdin and stdout, and never when the cache
-answers every check; `--yes` sends without asking. While it runs, a counter on
-stderr shows the files done, the requests sent, and the findings so far, and
-the report goes to stdout. A request Jev refuses stops the run with the file,
-the HTTP status, and Jev's reason. Files finished before it are cached, so
+answers every check; `--yes` sends without asking. Files finished before it are cached, so
 running again continues from there.
 
 The firewall in front of Jev's API can refuse a request whose code reads to
@@ -147,13 +188,61 @@ next run with the same limit picks up where this one stopped. `--limit 0` shows
 the plan and judges nothing. `--rpm <requests>` sends at most that many requests
 to Jev a minute, evenly spaced, retries included, and the plan says about how
 long they take. `--filter <glob>` reads only the files whose path from the
-working directory matches, such as `src/**` or `**/*.service.ts`; repeat it for
-more, and start a pattern with `!` to leave out what it matches. Together:
+working directory matches, such as `src/**` or `**/*.service.ts` (if using globs,
+wrap with single quotes to avoid expansion); repeat it for more, and start a
+pattern with `!` to leave out what it matches. Together:
 
 ```sh
 adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 200 --rpm 30
 ```
 
+### Comments
+
+Jev reads a file's code, not its comments. A comment changes nothing the code
+does, so it should not change the report, yet Jev takes what comments claim at
+their word: in a study of one alchemy rule, comments saying a delete succeeds
+on a missing resource hid 8 of its 9 real violations, and taking comments out
+found all nine. adhere takes every comment out before it hashes or sends a
+file, blanking it so every line keeps its number; the report's excerpts still
+show them.
+
+A comment that says `@adhere` anywhere in it is a note for Jev, and stays.
+Write one for a fact the code relies on that the file cannot show, once you
+have checked it, with how you know:
+
+```ts
+/**
+ * Deletes the activity. @adhere DeleteActivity succeeds on a missing
+ * activity, so no not-found error needs catching; probed 2026-09-25.
+ */
+```
+
+A note informs Jev; it suppresses nothing, and Jev still judges the code
+around it. `includeComments: true` in the config sends every comment, for a
+project whose rules are about comments, such as doc comments on exports.
+
+### Suppressing a finding
+
+A finding Jev got wrong is suppressed in the code, with a comment saying why:
+
+```ts
+// adhere-ignore alchemy/providers/idempotent-delete -- DeleteActivity succeeds on a missing activity; probed 2026-09-25
+delete: Effect.fn(function* ({ output }) {
+  yield* sfn.deleteActivity({ activityArn: output.activityArn });
+}),
+```
+
+On a line of its own, `adhere-ignore` covers the statement that starts on the
+next line of code: here the whole handler, wherever in it Jev points, since the
+lines it points at can move between runs. A finding without lines is covered
+when its section overlaps the statement. At the end of a line of code, it
+covers the statement that starts on that line. `adhere-ignore-file`, anywhere
+in a file, covers the whole file, and the rules it names are not judged there
+at all. A comment names rules as a report does, a preset's with its preset
+first, separated by commas; what follows `--` is the reason, for whoever
+reads the code next. Jev never reads these comments, even with
+`includeComments: true`, and the summary counts the findings they suppress.
+
 ### Logging a run
 
 `--log-level debug` logs a run's work on stderr: the config it loaded, how many
@@ -172,21 +261,52 @@ adhere lint --log-level debug 2> adhere.log
 
 ### What gets read
 
-`adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
-`.test.ts`, and config files. When the working directory contains `agents/`,
-`apps/`, or `packages/`, only those trees are read. Below the working
-directory, anything under `node_modules/`, `dist/`, `coverage/`, `vendor/`,
-`e2e/`, `references/`, `.adhere/`, `.agents/`, `.claude/`, `.direnv/`,
-`.alchemy/`, or `.vite/` is skipped; the directories above it do not count.
-`.tsx` files are not read, and `.gitignore` is not consulted.
+`adhere lint` reads the TypeScript files under the working directory, `.ts`,
+`.tsx`, `.mts`, and `.cts`, except declaration files such as `.d.ts` and
+config files. When the working directory contains `agents/`, `apps/`, or
+`packages/`, only those trees are read. Below the working directory, anything
+under `node_modules/`, `dist/`, `coverage/`, `vendor/`, `e2e/`, `references/`,
+`.adhere/`, `.agents/`, `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` is
+skipped; the directories above it do not count. JavaScript files are not read,
+and `.gitignore` is not consulted.
+
+Tests are judged only by rules about tests. A test is a `.test` or `.spec`
+file, such as `a.test.ts` or `Button.spec.tsx`; a fixture or test helper named
+as one, such as `fixtures.ts`, `GitHubHttpFixtures.ts`,
+`ledger-copy.fixture.ts`, `linear-test-helpers.ts`, or `test-utils.ts`; or any
+file under a `test/`, `tests/`, `__tests__/`,
+`testing/`, `fixtures/`, `fixture/`, `__fixtures__/`, or `__mocks__/`
+directory, and only a rule whose front matter says `tests` judges
+one (see [Rules as Markdown files](#rules-as-markdown-files)). On alchemy, 38%
+of the findings from rules not about tests were in test helpers and fixtures.
+
+A config's `exclude` lists globs, relative to the working directory, of files
+no rule judges, such as generated code. It leaves them out of every run, as
+`--filter '!<glob>'` leaves them out of one:
+
+```ts
+export default defineConfig({ exclude: ["**/generated/**"] });
+```
 
 ### Init
 
-`adhere init` writes `.adhere/config.ts` and two example rules. It is safe to
-rerun: by default it reports existing files as skipped and does not clobber
+`adhere init` writes `.adhere/config.ts`, the `.adhere/tsconfig.json` that gives
+the editor its types (see [Config](#config)), and two example rules. It is safe
+to rerun: by default it reports existing files as skipped and does not clobber
 them. `--force` overwrites them. A config already at another accepted path is
 kept, and no second one is added, even with `--force`.
 
+When there is a `package.json`, init also adds `@drkmttr/adhere` to its
+`devDependencies`, so the config's `defineConfig` has its types in the editor. It runs
+`<manager> add -D @drkmttr/adhere` with the package manager whose lockfile
+(`bun.lock`, `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`)
+sits beside the `package.json`, or npm when there is none. With pnpm it adds
+`--ignore-workspace-root-check`, so the install also works at a workspace root,
+and `--config.strict-dep-builds=false`, so pnpm 11 skips the build script of
+msgpackr-extract, an optional native add-on that comes with `effect` and that
+adhere never uses, with a warning instead of failing.
+It skips the install when `package.json` already lists adhere.
+
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
@@ -252,12 +372,15 @@ repo being audited, at one of these paths (keep one):
 - `.adhere.config.ts`
 
 ```ts
-import type { Config } from "@drkmttr/adhere";
+import { defineConfig } from "@drkmttr/adhere";
 
-export default {
+export default defineConfig({
   model: "jev-latest", // optional, default "jev-latest"
   threshold: 0.8, // optional, default 0.8
+  sufficiencyThreshold: 0.6, // optional, default 0.6: below it, a finding warns to check outside the file
   presets: ["effect"], // optional, built-in rule sets
+  exclude: ["**/generated/**"], // optional, files no rule judges
+  overrides: { "effect/basics/instrument-with-pipe": "off" }, // optional, see Presets
   rules: {
     "data/brand-meaningful-primitives": {
       description:
@@ -270,16 +393,24 @@ type UserId = typeof UserId.Type
       threshold: 0.8, // optional per-rule override
     },
   },
-} satisfies Config;
+});
 ```
 
 The default export is decoded with Effect `Schema`. An invalid shape refuses
-the run. The `import type` is erased at runtime. `defineConfig({...})` from
-`@drkmttr/adhere` does the same thing as `satisfies Config`, and the executable
-supplies it whether or not the repo has the package installed; the editor's
-types come from the package as a dev dependency. A config can import other
-files by relative path, but no packages besides `@drkmttr/adhere`: the
-executable does not resolve `node_modules`.
+the run. `defineConfig` types the config for the editor and returns it as it
+is; `satisfies Config`, with `import type { Config }`, does the same. The
+executable supplies `@drkmttr/adhere` to the config whether or not the repo has
+the package installed, and the editor's types come from the package, which
+`adhere init` adds as a dev dependency. A config can import other files by
+relative path, but no packages besides `@drkmttr/adhere`: the executable does
+not resolve `node_modules`.
+
+A tsconfig's globs skip dot directories, so the editor opens
+`.adhere/config.ts` outside any project, where it cannot resolve the package's
+types: they are reached only by `bundler`, `node16`, or `nodenext` resolution.
+`adhere init` writes `.adhere/tsconfig.json`, a project for the config alone
+with `bundler` resolution. For a config written by hand, add that file, or
+include `.adhere/config.ts` in a tsconfig that resolves the same way.
 
 `rules` in the config, inline as above or as a directory (below), replaces the
 `.adhere/` rule files: none of them, root or nested, is read then.
@@ -291,12 +422,19 @@ config and the cache (neither is read as a rule). The path without `.md` is the
 rule id, so `.adhere/data/brand-ports.md` is `data/brand-ports`. When that
 directory exists, it is read without any config.
 
-A file is front matter, then a body. The body's code goes in fences tagged,
-after the language, with RFC 2119's words: `must` for code that must be
-written, and `never` for code that must never be, which is what a violation
-looks like. Prose around them renders on GitHub and is ignored. An untagged
-fence is code that must be written, and without a fence the whole body is.
-`avoid`, the tag before 0.7, reads as `never`.
+A file is front matter, then a body. The body's code goes in fences under
+headings of RFC 2119's words: `## Must` for code that must be written, and
+`## Never` for code that must never be, which is what a violation looks like.
+A heading names the code in its section, which runs to the next heading at its
+level or higher, so a deeper heading such as `### A bare number` stays inside
+it. Only a heading that is the word alone names code, in any case and with or
+without a colon: `## Never:` does, `## Never do this` does not. Prose around
+the code renders on GitHub and is ignored.
+
+A fence can instead name its code after its language, as in `ts never`, which
+GitHub does not show; a fence's own word wins over its heading's. An untagged
+fence outside those sections is code that must be written, and without a fence
+the whole body is. `avoid`, the tag before 0.7, reads as `never`.
 
 ````md
 ---
@@ -306,22 +444,31 @@ threshold: 0.8
 
 Why: a bare `number` accepts 70000 and -1.
 
-```ts must
+## Must
+
+```ts
 const Port = Schema.Int.pipe(
   Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
   Schema.brand("Port"),
 );
 ```
 
-```ts never
+## Never
+
+```ts
 const port: number = Number(process.env.PORT);
 ```
 ````
 
 `description` is required, with code under `must`, `never`, or both.
-`threshold` is optional. A file that fails validation refuses the run with its
-path in the message. `loadRules(directory)` from the package root does the same
-load for your own tooling.
+`threshold` is optional, and so is `tests`, for a rule that judges tests, which
+rules otherwise skip: `tests: only` for a rule about tests, which judges
+nothing else, and `tests: include` for one that holds in tests as well. So is
+`level`: `level: warning` for a nit, or for a rule that tends to flag code
+wrongly, reports its findings as warnings, which do not fail the run. A rule
+inline in a config takes the same `tests` and `level`. A file that fails validation refuses
+the run with its path in the message. `loadRules(directory)` from the package
+root does the same load for your own tooling.
 
 Jev reads the code under the same words, and is asked whether the file
 diverges from the pattern `must` shows, with `never` as an example of
@@ -334,7 +481,7 @@ dropped. Neither goes in the other's place: code that must never be written,
 under `must`, reads to Jev as the pattern to follow.
 
 A rule that is a guideline rather than a requirement says "should" instead:
-in its description, and in fences tagged `should` and `should not` (`should`
+in its description, and in `## Should` and `## Should not` headings (`should`
 and `shouldNot` inline in a config). Jev then reads the code under `should`
 and `should_not`. A rule is one or the other, so it cannot mix `must` or
 `never` with `should` or `should not`. In a config, `reference` and `avoid`,
@@ -360,18 +507,45 @@ cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
 documentation can point `rules` at `docs/adhere/`:
 
 ```ts
-export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
+export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });
 ```
 
 Rules read through `rules` apply project-wide.
 
+### Scoping a rule
+
+A rule can say where it applies, apart from what it asks for, with
+`appliesTo` and `excludeIf`: each a list of descriptions of code, written in
+front matter as a JSON array on one line, or as an array inline in a config.
+
+```md
+---
+description: Structured variants must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field.
+appliesTo: ["a declared union type or schema"]
+excludeIf: ["a type that mirrors a third-party format whose tag key that format fixes, such as a Slack Block Kit block"]
+---
+```
+
+Each goes to Jev as a question of its own, in the same request as the rule,
+about the code that breaks the rule rather than the whole file: for
+`appliesTo`, whether any of that code is as described, and for `excludeIf`,
+whether all of it is. A finding stands only when Jev says yes, above 0.5, to
+every `appliesTo` and to no `excludeIf`, so a file with a real violation
+beside code an `excludeIf` describes keeps its finding. The scores are cached
+with the rule's judgment, and editing a matcher judges the rule again, as
+editing its description does. At `--log-level debug`, lint logs each finding
+its matchers dropped, with their scores.
+
+Keeping the scope out of the description keeps the description to what the
+rule asks for, which the report shows, and gives each part a score of its own.
+
 ### Rule writing tips
 
 We've evaluated different ways of giving Jev a rule, to catch the most
 violations with the fewest false positives. In general:
 
 - Say "must" for what code must do and "never" for what it must not, in the
-  description and as the fence tags.
+  description and in the headings over the code.
 - Give one example of each: one `must` block and one `never` block. Three of
   each did no better, and several of one kind alone did worse.
 - For a guideline rather than a requirement, say "should" and "should not"
@@ -389,13 +563,30 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 command line with `--preset`, repeated or separated by commas, as in
 `--preset effect,alchemy`, in which case the config file is optional. Presets
 named in both places apply together. Reports name a preset's rule with the
-preset first, as in `alchemy/secrets/…`. There are two:
-
+preset first, as in `alchemy/secrets/…`. There are five:
+
+- `typescript`: 11 rules in [`presets/typescript/`](./presets/typescript/) for
+  any TypeScript project, drawn from the TypeScript Handbook and the Google
+  TypeScript Style Guide: data from outside checked at runtime, invalid states
+  unrepresentable, errors never swallowed, resources released on every path,
+  arguments not mutated, and tests that assert outcomes and stand alone.
+- `react`: 10 rules in [`presets/react/`](./presets/react/) for components
+  and hooks, lifted from react.dev, mostly
+  [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
+  and [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure):
+  logic for an event in its handler rather than an effect, effects that clean
+  up and ignore stale fetches, `useSyncExternalStore` for outside stores, state
+  that neither copies props nor contradicts itself, and Server Functions and
+  Server Components that guard what crosses to the client.
+- `security`: 4 rules in [`presets/security/`](./presets/security/), drawn
+  from OWASP's cheat sheets: secrets kept out of logs, error messages, and
+  responses; parameterized SQL; no untrusted input in shell commands, `eval`,
+  or file paths; and secrets compared in constant time. It has no topics.
 - `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
   from the [effect-solutions](https://github.com/kitlangton/effect-solutions)
   docs and the
   [effect/platform](https://effect.website/docs/platform/introduction/) docs.
-- `alchemy`: 43 rules in [`presets/alchemy/`](./presets/alchemy/) for code that
+- `alchemy`: 41 rules in [`presets/alchemy/`](./presets/alchemy/) for code that
   deploys with [alchemy](https://alchemy.run), lifted from its docs and blog:
   where Config and bindings are read, which resources keep their data, how
   secrets stay out of bundles and logs, authorization on public URLs,
@@ -407,11 +598,36 @@ of its own: `--preset effect/basics` applies only the rules under
 A topic's rules keep the ids they have in the whole preset, so a topic and its
 preset share cached judgments, and naming both applies each rule once.
 
+A config's `overrides` changes a rule by the id a report names it with, a
+preset's with the preset first, without copying its text into `rules`: `off`
+drops it, `warning` or `error` sets its level, and `{ level, threshold }` sets
+either. An id that no preset or project rule has refuses the run, so a typo
+does not go unnoticed; a rule of a preset the run does not name is accepted.
+
+```ts
+export default defineConfig({
+  presets: ["effect", "alchemy"],
+  overrides: {
+    "alchemy/providers/idempotent-delete": { level: "warning", threshold: 0.9 },
+    "effect/basics/instrument-with-pipe": "off",
+  },
+});
+```
+
+`effect`'s four rules about tests, `testing/test-clock-for-time`,
+`services/fresh-layer-per-test`, `services/test-layers-are-in-memory`, and
+`config/tests-provide-values-directly`, say `tests: only`: they judge tests and
+nothing else, and every other preset rule skips tests.
+
+`alchemy`'s `providers/idempotent-delete` reports warnings. Whether a delete
+fails on a resource that is already gone is a fact about the API, which the
+file does not show, so the rule also flags deletes of APIs that succeed
+anyway; see [the study](eval/studies/idempotent-delete.md).
+
 A preset rule says "must" only where its source makes a requirement, and
-"should" where the source gives advice. In `effect`, three rules are
-guidelines: network calls carry a timeout and a retry schedule, unless their
-client already applies both; test layers are in memory, outside integration
-tests; and tests provide config through a layer. Config validation accepts
+"should" where the source gives advice. In `effect`, two rules are
+guidelines: test layers are in memory, outside integration tests, and tests
+provide config through a layer. Config validation accepts
 `Config.mapOrFail` as well as `Config.schema`, and the variants rule does not
 rule out a `switch`. The rule that a command handler only parses input is
 gone: the docs show that pattern but do not ask for it.
@@ -450,17 +666,56 @@ whose types have no requirements to find. The preset's
 `services/dependencies-through-layers` asks for that, and
 `services/operations-have-no-requirements` for the style it goes with.
 
+`typescript` leaves out what typescript-eslint and ESLint check exactly:
+unhandled promises (`no-floating-promises`), throwing non-errors
+(`only-throw-error`), `any` (`no-explicit-any`), exhaustive switches
+(`switch-exhaustiveness-check`), a lost `cause` (`preserve-caught-error`), and
+empty catch blocks (`no-empty`). Four of its rules report warnings. Three are
+advice that code often has reason to set aside: assertions that claim only
+what the code established, types derived rather than restated, and
+independent awaits run concurrently. The fourth, that HTTP requests carry a
+timeout, was right on fewer than half its findings above 0.8 on the eval:
+many of the rest were calls through a client with a default timeout that the
+file does not show.
+Two rules the eval found mostly wrong are gone: that tests use fake time
+rather than real waits, and that importing a module does no work.
+
+Where effect or alchemy had a rule that `typescript` or `security` has, that
+one is kept and the other is gone: typescript's
+`async/network-calls-have-timeouts` replaced effect's
+`basics/external-calls-are-resilient`, and `security/parameterized-queries`
+and `security/no-secrets-in-output` replaced alchemy's
+`data/parameterized-sql` and `secrets/never-logged-returned-or-output`. A
+project on Effect or alchemy names those presets too, for those rules.
+
+`react` leaves out what the React Compiler's lint rules check, in
+[eslint-plugin-react-hooks](https://react.dev/reference/eslint-plugin-react-hooks)'s
+recommended set and in Oxlint: pure render (`purity`), props and state never
+mutated (`immutability`), refs not read during render (`refs`), no `setState`
+in render or synchronously in an effect (`set-state-in-render`,
+`set-state-in-effect`), which covers state derived in an effect, and no
+component defined inside another (`static-components`). Its rules judge `.ts`
+files as well as `.tsx`, and apply only to components, hooks, effects, and
+Server Functions, so other files cost their checks and find nothing.
+`server/no-private-data-to-client` reports warnings: a file does not show
+whether the component it passes a record to is a Client Component. So does
+`state/store-ids-not-copies`, which also flags state that copies a string or
+an option from a fixed list, where a copy cannot go stale.
+
 ### Precedence
 
 Highest first: `--threshold` on the command line, the config file, presets in
 order (a later preset wins), then the defaults `jev-latest` and `0.8`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
-beats all of the above for that rule.
+beats all of the above for that rule, and an entry in `overrides` beats the
+rule's own `threshold` and `level`. `--sufficiency-threshold` beats the
+config's `sufficiencyThreshold`, which beats the default, `0.6`.
 
 ## How a file is judged
 
-1. One Jev request per file. The state is the file's numbered lines and
-   nothing else. Each rule is one `noul` (yes/no probability) question that
+1. One Jev request per file. The state is the file's sections (see the
+   report, above) under their numbers from 1, as `{ "1": "…", "2": "…" }`,
+   without their comments (see [Comments](#comments)), and nothing else. Each rule is one `noul` (yes/no probability) question that
    carries the rule's description and its code under its words, `must` and
    `never` (or a guideline's `should` and `should_not`): whether the file
    diverges from the pattern `must` shows, with `never` as an example of
@@ -473,14 +728,22 @@ beats all of the above for that rule.
    project rule, the rule's question has a second one beside it, the linter
    check (see [Validate](#validate)), with the same fields.
 2. A second request only when at least one rule's probability is above its
-   threshold: one `choice` question per flagged rule over the file's non-blank
-   lines, which yields the line to report. A file with more than 255 non-blank
-   lines is located in two steps (a block of 20 lines, then a line inside it).
+   threshold. Per flagged rule, when the file has more than one section, one
+   `choice` question among the sections' numbers, which yields the section to
+   report. The options carry no text of their own, since each is a key of the
+   state: describing each section by its first line, or by what it declares,
+   located no better on the eval. For each section, two `choice` questions
+   among its lines, each option the line's text, of the line the violation
+   starts on and the one it ends on; the chosen section's are underlined.
+   Beside them, one `noul` carrying the rule:
+   whether you can tell if `code` breaks it from `code` alone, without knowing
+   what other files, libraries, services, or configuration do. It yields the
+   warning (see the report, above).
 3. Jev reads at most 32k tokens of state and one question together, and 64k
    tokens in a request. adhere estimates tokens from the JSON it sends, at
    about three bytes a token. When a file's questions would not fit in one
    request, they are split across several. A file whose code and longest
-   question would not fit together, or that has more than 5100 lines, is
+   question would not fit together, or that has more than 255 sections, is
    skipped and counted in the summary, and the rest of the run goes on. So is
    a file Jev itself counts as over its context, which text denser than the
    estimate, such as CJK, can cause.
@@ -493,8 +756,9 @@ gives everyone and CI the same findings without paying for them again, and a
 pull request changes the judgments of only the files it changes.
 
 `files/` holds Jev's answers by the content they are about: each cache file is
-named for the hash of a source file's content, so a moved or copied file keeps
-its judgments, and identical files share them. Each answer sits under a
+named for the hash of a source file's content as Jev reads it, without its
+comments, so a moved or copied file keeps its judgments, identical files share
+them, and a change to comments alone re-judges nothing. Each answer sits under a
 fingerprint of the model and the question asked for the rule, which carries
 the rule's text. A changed file re-judges every rule for that file. An edited
 rule re-judges only that rule, and an adhere that asks its questions
@@ -510,9 +774,12 @@ every file, adhere prunes the cache: it deletes answers about content no file
 has, and folds what is left into one file per content. Answers to rules the
 run left out stay, so a run with other presets or rules, or with one topic,
 loses nothing another run still asks; answers to a rule's old texts stay too,
-until the content they are about is gone. A run narrowed by `--filter` does not
-prune. To keep the
-cache out of diffs, mark it as generated in `.gitattributes`:
+until the content they are about is gone. Answers about a file the run read
+but judged against no rule, such as a test when no rule judges tests, stay as
+well, while a file the config excludes is not read, so answers about it go. A
+run narrowed by `--filter` does not prune.
+
+To keep the cache out of diffs, mark it as generated in `.gitattributes`:
 
 ```text
 .adhere/cache/** linguist-generated -diff
@@ -532,12 +799,55 @@ every file is cached needs no key and no network.
 
 ## Agent skill
 
-[`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) teaches an agent to
-gather a repo's conventions into rule files, configure adhere, and calibrate
-thresholds. Install it with the [skills](https://github.com/vercel-labs/skills)
-CLI: `skills add darkmatter/adhere`. The binary carries the same file:
-`adhere skill` prints it, so `adhere skill > .agents/skills/adhere/SKILL.md`
-works without a checkout.
+Two skills teach an agent to work with adhere:
+
+- [`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) gathers a repo's
+  conventions into rule files, configures adhere, and calibrates thresholds.
+- [`skills/adhere-fix/SKILL.md`](./skills/adhere-fix/SKILL.md) verifies and
+  fixes the findings `lint` reports: it checks each against its rule and the
+  code, fixes the real ones, reports the false ones with the evidence, and says
+  when a rule is wrong more often than right.
+
+Install them with the [skills](https://github.com/vercel-labs/skills) CLI:
+`skills add darkmatter/adhere`. The binary carries both: `adhere skill` prints
+the first and `adhere skill fix` the second, so
+`adhere skill fix > .agents/skills/adhere-fix/SKILL.md` works without a
+checkout.
+
+### In CI
+
+Pipe the fix skill into an agent that runs without asking. The skill tells it
+that invoking the skill permits every `adhere lint` run and its cost, and
+`adhere skill fix` prints the skill of the adhere that runs, so its flags
+match:
+
+```sh
+adhere skill fix | codex exec --yolo
+adhere skill fix | claude -p --dangerously-skip-permissions
+```
+
+Both turn off the agent's own permission checks, which suits a runner thrown
+away after the job. To keep Codex in its sandbox, let the sandbox reach
+`api.typesafe.ai`:
+
+```sh
+adhere skill fix | codex exec --sandbox workspace-write \
+  -c sandbox_workspace_write.network_access=true -c approval_policy=never
+```
+
+- Set `TYPESAFE_API_KEY` from a secret.
+- The agent adds no `adhere-ignore` comments or `@adhere` notes unless
+  `ADHERE_ALLOW_SUPPRESSIONS=1` is set in its environment, as in
+  `adhere skill fix | ADHERE_ALLOW_SUPPRESSIONS=1 codex exec --yolo`. It then
+  suppresses a finding it shows is false, or that three fixes did not clear,
+  with the evidence in the comment. Without it, the agent leaves those
+  findings, and its report ends by naming them and the variable.
+- End the job with `adhere lint --yes`. The agent exits 0 whatever it left,
+  so this step passes or fails the job; it judges only the files the agent
+  changed, and reads the rest from the cache.
+- Do not run it on pull requests from forks. The agent reads their code with
+  your secrets in reach and the network open, so code written to steer it can
+  send them out.
 
 ## Development
 
@@ -556,7 +866,7 @@ and `bun run test` runs the tests.
 ### Native executable
 
 `bun run build` compiles `dist/adhere`, a single binary with Bun and the
-`effect` preset inside it, through Bun's
+presets inside it, through Bun's
 [`--compile`](https://bun.sh/docs/bundler/executables) with
 `--asset ./presets`. It runs without Bun or `node_modules` on the target
 machine and still loads the repo's `config.ts` and Markdown rules from disk.
@@ -564,6 +874,12 @@ machine and still loads the repo's `config.ts` and Markdown rules from disk.
 into its package under `dist/npm/`
 ([`scripts/npm-packages.ts`](./scripts/npm-packages.ts)).
 
+`adhere --version` tells the builds apart. A release prints its version, as
+`adhere v0.10.0`. `bun run build` prints `git describe --tags --dirty` where
+it was built, as `adhere v0.10.0-16-g9a41328`: 16 commits after v0.10.0, at
+`9a41328`, ending in `-dirty` when the tree had changes. Run from source, it
+prints the checkout's version marked `(source)`.
+
 Each platform's executable is its own npm package,
 `@drkmttr/adhere-<platform>-<arch>`, limited by `os` and `cpu`, and an
 optional dependency of `@drkmttr/adhere`, so an install fetches only its own