@drkmttr/adhere 0.9.4 → 0.10.0

package/README.md

@@ -1,4 +1,6 @@
-# adhere
+<div align="center">
+<h1>adhere</h1>
+</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",
@@ -8,8 +10,11 @@ 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`.
 
-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:
 
@@ -27,7 +32,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 +41,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
@@ -66,16 +71,21 @@ Found 1 error.
 42 files, 3 judged, 39 cached.
 ```
 
-The header is the rule id, Jev's probability, and the rule's description.
+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
+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.
+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
 
@@ -87,6 +97,7 @@ 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
@@ -99,6 +110,10 @@ Bare `adhere` prints the help, which lists the commands, and
 `adhere <command> --help` lists a command's flags. `adhere --completions <shell>`
 prints a completion script.
 
+### Demo
+
+<a href="https://asciinema.org/a/1266511" target="_blank"><img width="400" src="https://asciinema.org/a/1266511.svg" /></a>
+
 ### Before and during a run
 
 Until it knows what judging takes, a status line on stderr says what `lint` is
@@ -111,14 +126,17 @@ what judging takes:
 ```text
 200 files and 14 rules: 2800 checks, 1400 cached.
 Judging the other 1400 takes 200 requests to Jev, plus 1 or more for each file with a finding.
-? Send 200 requests to Jev? › (Y/n)
+Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, and more for locating findings.
+? Send 200 requests to Jev, about $0.08? › (Y/n)
 ```
 
+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.
+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
@@ -136,13 +154,60 @@ 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
+line it points at can move between runs. 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
@@ -161,21 +226,47 @@ 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 `.ts` files under the working directory, except `.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. `.tsx` files are not read, and
+`.gitignore` is not consulted.
+
+Tests are judged only by rules about tests. A test is a `.test.ts` or
+`.spec.ts` file, or any file under a `test/`, `tests/`, `__tests__/`, or
+`fixtures/` 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`
@@ -241,12 +332,14 @@ 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
   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:
@@ -259,16 +352,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.
@@ -280,12 +381,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
 ---
@@ -295,22 +403,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
@@ -323,7 +440,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`,
@@ -349,7 +466,7 @@ 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.
@@ -360,7 +477,7 @@ 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"
@@ -377,7 +494,8 @@ A preset has the shape of a config without `presets`: `rules`, and optionally
 `model` and `threshold`. Name presets in the config's `presets`, or on the
 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. There are two:
+named in both places apply together. Reports name a preset's rule with the
+preset first, as in `alchemy/secrets/…`. There are two:
 
 - `effect`: Markdown rules in [`presets/effect/`](./presets/effect/), lifted
   from the [effect-solutions](https://github.com/kitlangton/effect-solutions)
@@ -395,6 +513,32 @@ 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
@@ -443,12 +587,13 @@ whose types have no requirements to find. The preset's
 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`.
 
 ## 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 numbered lines, 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
@@ -481,8 +626,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
@@ -498,9 +644,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
@@ -520,12 +669,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.9.4",
-    "@drkmttr/adhere-darwin-x64": "0.9.4",
-    "@drkmttr/adhere-linux-arm64": "0.9.4",
-    "@drkmttr/adhere-linux-x64": "0.9.4",
-    "@drkmttr/adhere-win32-x64": "0.9.4"
+    "@drkmttr/adhere-darwin-arm64": "0.10.0",
+    "@drkmttr/adhere-darwin-x64": "0.10.0",
+    "@drkmttr/adhere-linux-arm64": "0.10.0",
+    "@drkmttr/adhere-linux-x64": "0.10.0",
+    "@drkmttr/adhere-win32-x64": "0.10.0"
   }
 }

package/presets/alchemy/apis/match-remote-errors-by-tag.md

@@ -2,13 +2,17 @@
 description: Errors that crossed RPC or a workflow replay must be matched by their tag and data fields, never with instanceof, prototype methods, or object identity, which do not survive serialization, and RPC arguments must be serializable values, never functions or class instances.
 ---
 
-```ts must
+## Must
+
+```ts
 const value = yield* stub.get(key).pipe(
   Effect.catchTag("KeyMissing", (error) => Effect.succeed(`missing: ${error.key}`)),
 );
 ```
 
-```ts never
+## Never
+
+```ts
 const value = yield* stub.get(key).pipe(
   Effect.catchAll((error) => (error instanceof KeyMissing ? Effect.succeed("missing") : Effect.fail(error))),
 );

package/presets/alchemy/apis/schemas-at-trust-boundaries.md

@@ -2,14 +2,18 @@
 description: Input from outside the stack, such as browsers, partners, or public URLs, should be validated with a schema through Effect RPC or HttpApi, while calls between the stack's own runtimes should use schemaless RPC through bindings, and unvalidated payloads should not cross a trust boundary.
 ---
 
-```ts should
+## Should
+
+```ts
 const Tasks = HttpApiGroup.make("tasks").add(
   HttpApiEndpoint.post("create", "/tasks", { payload: Schema.Struct({ title: Schema.String }) }),
 );
 const greeter = yield* Cloudflare.Workers.bindWorker(Greeter); // internal call
 ```
 
-```ts should not
+## Should not
+
+```ts
 fetch: Effect.gen(function* () {
   const request = yield* HttpServerRequest.HttpServerRequest;
   const body = (yield* request.json) as { title: string; ownerId: string }; // public URL, no validation

package/presets/alchemy/data/commit-migrations-then-deploy.md

@@ -2,12 +2,16 @@
 description: Migrations must be generated and reviewed ahead of time, committed with the schema, and applied from the committed files; a deploy, deploy hook, or Action must never generate migration SQL, and schema changes must never run from an HTTP route.
 ---
 
-```ts must
+## Must
+
+```ts
 // package.json: "db:generate": "drizzle-kit generate" (run locally, then commit ./drizzle)
 const db = yield* Cloudflare.D1.Database("AppDb", { migrations: "./drizzle" });
 ```
 
-```ts never
+## Never
+
+```ts
 // package.json: "deploy": "drizzle-kit generate && alchemy deploy"
 fetch: Effect.gen(function* () {
   if (url.pathname === "/setup") yield* sql`CREATE TABLE users (id text primary key)`;

package/presets/alchemy/data/hyperdrive-direct-origin.md

@@ -2,13 +2,17 @@
 description: A Hyperdrive connection's origin should be the database's direct endpoint, and clients that connect without Hyperdrive should use the provider's pooled endpoint; Hyperdrive should not point at a provider pooler, which stacks two poolers.
 ---
 
-```ts should
+## Should
+
+```ts
 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", {
   origin: branch.origin,
   dev: branch.pooledOrigin,
 });
 ```
 
-```ts should not
+## Should not
+
+```ts
 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("AppHyperdrive", { origin: role.pooledOrigin });
 ```

package/presets/alchemy/data/migrations-use-direct-url.md

@@ -2,10 +2,14 @@
 description: A migration runner must connect with the database's direct URL, never Hyperdrive's runtime connection string or an Accelerate or pooled URL.
 ---
 
-```ts must
+## Must
+
+```ts
 export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.DIRECT_DATABASE_URL! } });
 ```
 
-```ts never
+## Never
+
+```ts
 export default defineConfig({ dialect: "postgresql", dbCredentials: { url: process.env.ACCELERATE_URL! } });
 ```