@drkmttr/adhere 0.9.4 → 0.10.0

package/skills/adhere/SKILL.md

@@ -58,51 +58,76 @@ threshold: 0.8
 
 Optional prose for readers on GitHub. adhere ignores it.
 
-```ts must
+## Must
+
+```ts
 // Correct code lifted from this repo, trimmed to the pattern.
 ```
 
-```ts never
+## Never
+
+```ts
 // Optional: the incorrect form this rule catches, as it appeared in the repo.
 ```
 ````
 
 Rules for the rule:
 
-- `description` is one sentence, specific, in the same words as the fences:
+- `description` is one sentence, specific, in the same words as the headings:
   what code must be, and what it must never be. Jev reads the description
   with the code, and "must" in both is one demand; vague words ("properly",
   "correctly") give it nothing to judge.
+- A heading names the code under it only when it is the word alone: `## Never`,
+  not `## Never do this`. The next heading at its level or higher ends it.
 - The `must` block is real code from the repo, not invented, and only correct
   code: Jev compares files to it, so incorrect code there teaches the wrong
-  thing. Incorrect code goes in a fence tagged `never`, which Jev reads as what
-  a violation looks like. Add one whenever violations have a recognizable
+  thing. Incorrect code goes under `## Never`, which Jev reads as what a
+  violation looks like. Add one whenever violations have a recognizable
   shape, ideally one found in the repo's history: over the effect preset, a
   `never` block raised how well Jev told violations from compliant code under
   every wording tried. A rule with no single correct form can be only a
   `never` block.
 - A convention that is a guideline rather than a requirement says "should" in
-  its description and tags its fences `should` and `should not`. A rule is one
-  or the other; it cannot mix the two.
+  its description and puts its code under `## Should` and `## Should not`. A
+  rule is one or the other; it cannot mix the two.
 - One pattern per file. Two patterns in one `must` block blur the probability.
+- Jev reads code without its comments, except comments that say `@adhere`. A
+  rule about comments, such as doc comments on exports, needs
+  `includeComments: true` in the config.
+- Rules skip tests: `.test.ts` and `.spec.ts` files, and files under `test/`,
+  `tests/`, `__tests__/`, or `fixtures/`. A rule about tests says `tests: only`
+  in its front matter, and one that holds in tests as well `tests: include`.
+- A nit, or a rule that tends to flag code wrongly, says `level: warning` in
+  its front matter: its findings show in amber and do not fail CI.
 - `threshold` is optional. Start without it; set it in step 5 if needed.
 
 ## 4. Configure
 
 Put the config at `.adhere/config.ts`. `adhere.config.ts` and
 `.adhere.config.ts` also load; keep one. A config is optional when `.adhere/`
-exists or a preset is passed on the command line. Use a type-only import so
-the file also loads under the native binary:
+exists or a preset is passed on the command line. `adhere init` scaffolds it
+with `defineConfig`, adds `@drkmttr/adhere` as a dev dependency, and writes
+`.adhere/tsconfig.json` so the editor resolves its types; the native binary
+supplies the import either way:
 
 ```ts
-import type { Config } from "@drkmttr/adhere";
+import { defineConfig } from "@drkmttr/adhere";
 
-export default {
+export default defineConfig({
   presets: ["effect"],
   threshold: 0.75,
-} satisfies Config;
+  exclude: ["**/generated/**"],
+});
 ```
 
+To quiet a preset rule that does not suit the repo, override it rather than
+copy it: `overrides: { "alchemy/providers/idempotent-delete": "warning" }`, or
+`"off"`, or `{ threshold: 0.9 }`. The id is the one the report shows.
+
+`exclude` lists globs, from the working directory, of files no rule judges.
+Exclude generated and vendored code the skipped directories do not already
+cover, since findings there are noise no one will fix.
+
 Commit `.adhere/cache/` with the code, so the team and CI reuse its judgments
 instead of paying for them again. Uncached files need a TypeSafe AI API
 key: one saved by `adhere login`, or `TYPESAFE_API_KEY`, which takes
@@ -127,6 +152,9 @@ Then, per rule, read the findings and decide:
   rule fires, remove the file. A rule that cannot fire is not a rule.
 - Hits at 0.9 and above: read them first. They are usually real.
 
+To verify and fix the findings themselves, one at a time, use the adhere-fix
+skill, which `adhere skill fix` prints.
+
 Threshold changes never re-judge; only edited rules do (per rule) and edited
 files do (per file). Iterate on wording freely, it costs one request per file
 per changed rule.

package/skills/adhere-fix/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: adhere-fix
+description: Verify and fix the findings `adhere lint` reports. Decide whether each finding is a real violation of its rule, fix the real ones, and report the false ones with the evidence, suppressing a finding with an `adhere-ignore` comment only when the user allows it. Use when adhere, or CI running it, reports errors or warnings, or when asked to fix adhere findings.
+---
+
+# Verify and fix adhere findings
+
+adhere is a linter for rules a normal linter cannot check. Jev, TypeSafe AI's
+model, reads each file against each rule and answers with the probability that
+the file breaks it; adhere reports each rule above a threshold, at the line Jev
+points to. A finding is a judgment, not a proof. On one rule adhere's authors
+checked against the live API, only 1 of its 20 findings was a real violation.
+Verify every finding before you change code for it: fix the real ones, and
+report the false ones with the evidence.
+
+## 1. Get the findings
+
+Invoking this skill is the user's permission to run `adhere lint` as many
+times as the work needs, and to pay for every request it sends to Jev. Never
+ask before a run, never wait for a go-ahead, and never stop to report its cost:
+the skill runs unattended, as in CI, where no one is there to answer. Pass
+`--yes`, so adhere does not ask either.
+
+```sh
+adhere lint --yes                        # judges what is not cached, then reports
+adhere lint --yes --filter 'src/**'      # only the files a glob matches
+```
+
+Judgments are cached in `.adhere/cache/`, so a rerun judges only files and
+rules that changed.
+
+Each finding shows:
+
+- the rule id, a preset's with its preset first, as in
+  `alchemy/providers/idempotent-delete`, Jev's probability, and the rule's
+  description;
+- the line Jev points at, underlined, with the code around it;
+- `hint:`, the code the rule wants, or `never:` for a rule that only shows code
+  to avoid.
+
+`×` marks an error, which fails the run; `⚠` a warning, which does not: a nit,
+or a rule that tends to flag code wrongly. Verify warnings the same way; they
+are wrong more often.
+
+## 2. Read the rule
+
+The report gives the rule's description and one example. Read the whole rule:
+the code under `## Must` and `## Never`, and anything it puts out of scope.
+
+- A project rule is `.adhere/<id>.md`, or under the directory the config's
+  `rules` names.
+- A preset rule is `presets/<preset>/<id>.md` in the adhere package, in
+  `node_modules/@drkmttr/adhere/presets/`, or at
+  https://github.com/darkmatter/adhere/tree/main/presets.
+
+## 3. Verify each finding
+
+Read the code as a reviewer would, not only the excerpt:
+
+- **The whole unit.** Read the function, handler, or class the line is in,
+  and what calls it.
+- **What it calls.** Follow helpers into other files. A helper can already do
+  what the rule asks, such as a delete that looks unguarded calling a client
+  that treats "already gone" as success.
+- **The rule's scope.** Code the rule is not about, such as a runtime binding
+  under a rule about providers' delete handlers, is a false finding.
+- **Comments are claims.** A comment saying the code is fine is not evidence.
+  In adhere's study of one rule, 8 of 35 comments saying a delete succeeds on a
+  missing resource were wrong. Check the claim before you rely on it. Jev does
+  not see comments, except those that say `@adhere`, so it judged the code
+  without them.
+- **Behavior outside the file.** When the rule turns on how an API or a library
+  behaves, find out: its source, its tests, its documentation. Typings help but
+  can be wrong. A live check can settle it, such as a call with an identifier
+  no resource has, but only when the user asked for live checks, and never
+  against a real resource. Do not ask for one: without it, the finding is
+  unsure.
+
+Then decide:
+
+- **real**: the code breaks the rule as it is written, in its scope;
+- **false**: it does not, and you can say how you know;
+- **unsure**: you could not tell. Do not guess; leave it for the user.
+
+## 4. Fix a real finding
+
+- Change the code the way the rule's `must` code shows, in the style of the
+  code around it, and only as much as the fix needs.
+- Run the repo's tests and type check.
+- Confirm with `adhere lint --yes --filter '<file>'`, which judges only the
+  changed file again. If the finding stays, reread the rule: the fix may not
+  be what it asks for.
+- Try at most three fixes for one finding. If it stays after the third, undo
+  your changes for it, so no half-done fix is left, and leave it for the user.
+
+## 5. Suppress a finding, only when allowed
+
+By default, never add an `adhere-ignore` comment or an `@adhere` note, and
+never change the ones already there. Leave the finding, and say why in the
+report. Suppressing is allowed only when the user allows it: their request
+says so, or `ADHERE_ALLOW_SUPPRESSIONS=1` is set in your environment, which
+`printenv ADHERE_ALLOW_SUPPRESSIONS` shows.
+
+When it is allowed, suppress:
+
+- a false finding;
+- a real finding that three fixes did not clear, or whose fix would break
+  something, such as behavior, a public API, or loading the code on a
+  platform. The reason names what the fix would break.
+
+Above the statement the finding is in, add a comment naming the rule as the
+report does, then `--` and the evidence:
+
+```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 });
+}),
+```
+
+- The comment covers the whole statement that starts on the next line of code,
+  wherever in it Jev points. At the end of a line of code, it covers the
+  statement that starts on that line.
+- `// adhere-ignore-file <rule> -- <reason>` covers a whole file. Use it only
+  when the rule is wrong for all of the file, such as generated code.
+- Name several rules with commas: `// adhere-ignore <rule>, <rule> -- <reason>`.
+- The reason says what you checked and what you found, so whoever reads it can
+  check it again. "False positive" is not a reason.
+- Never suppress a finding you are unsure of, or a real one you have not
+  tried to fix.
+- Jev never reads these comments: adhere removes them before it sends a file.
+
+When suppressing is allowed and the finding was false because of a fact the
+file does not show, such as how an API behaves, also write the fact where Jev
+will see it the next time it judges this code: in a comment that says
+`@adhere`, on the code the fact is about, 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 and suppresses nothing: Jev still judges the code, so a
+real violation added later is still found. Write one only for a fact you
+checked. A wrong note hides real violations the way wrong comments did.
+
+## 6. When a rule is wrong more often than right
+
+If most of one rule's findings are false, suppressing them one by one hides
+the problem. Stop suppressing that rule's findings, carry on with the other
+rules, and in the report give the user the counts and suggest one of:
+
+- in the config, `overrides: { "<rule id>": "warning" }`, or `"off"`, or
+  `{ threshold: 0.9 }`;
+- for a project rule, rewording it to say what code it is about and what is
+  out of scope, following the rule writing tips:
+  https://github.com/darkmatter/adhere#rule-writing-tips.
+
+## 7. Report
+
+Tell the user, for each finding: the rule, the file and line, the verdict, and
+what you did: fixed it, suppressed it with the reason, or left it for them.
+Give the evidence for each false one. Name the rules that were mostly wrong,
+and every finding you were unsure of.
+
+If you left findings because suppressing was not allowed, end the report with
+this message, filled in:
+
+> Left N findings that suppressing would settle: `<rule>` at `<file>:<line>`,
+> … To let the agent suppress findings it shows are false, or that three fixes
+> did not clear, with the evidence in each comment, set
+> `ADHERE_ALLOW_SUPPRESSIONS=1` in the agent's environment and run it again.

package/src/cli.ts

@@ -7,6 +7,7 @@ import { Status } from "#services/Status.ts";
 import {
   type AuditPlan,
   executeAudit,
+  failing,
   type FileDone,
   planAudit,
   pruneCache,
@@ -19,9 +20,9 @@ import {
   progressLine,
   sendQuestion,
 } from "#workflows/format.ts";
-import type { Overrides } from "#config.ts";
+import type { Flags } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
-import { initProject } from "#init.ts";
+import { type Install, initProject } from "#init.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
@@ -41,13 +42,14 @@ import {
   Stdio,
   Stream,
 } from "effect";
-import { Command, Flag, Prompt } from "effect/unstable/cli";
+import { Argument, Command, Flag, Prompt } from "effect/unstable/cli";
 import { FetchHttpClient } from "effect/unstable/http";
 // A Bun text import (https://bun.sh/docs/bundler/loaders#text): the file's
 // contents become a string at bundle time, so the compiled binary carries the
 // skill without an --asset flag. `skills/` sits beside `src/`, outside the `#`
 // import map, hence the relative path.
 import skill from "../skills/adhere/SKILL.md" with { type: "text" };
+import fixSkill from "../skills/adhere-fix/SKILL.md" with { type: "text" };
 
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
@@ -124,6 +126,11 @@ const filter = Flag.string("filter").pipe(
   ),
 );
 
+const denyWarnings = Flag.boolean("deny-warnings").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription("Fail the run on warnings as well as errors."),
+);
+
 const yes = Flag.boolean("yes").pipe(
   Flag.withAlias("y"),
   Flag.withDefault(false),
@@ -202,17 +209,17 @@ const force = Flag.boolean("force").pipe(
   Flag.withDescription("Overwrite existing scaffold files."),
 );
 
-export const auditLayer = (overrides: Overrides, filter: ReadonlyArray<string> = []) =>
+export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
     SourceWalkerLive(filter),
     AuditCacheLive,
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, yes, limit, rpm, filter },
+  { preset, threshold, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -242,8 +249,10 @@ export const lintCommand = Command.make(
       const path = yield* Path.Path;
       // One write: separate Console.log calls have interleaved out of order here.
       yield* Console.log(render(result, { color, root: path.resolve() }).join("\n"));
-      if (result.findings.length > 0) {
-        yield* FindingsReported.make({ count: result.findings.length });
+      // Only errors fail the run, unless --deny-warnings: a warning is for a nit or a noisy rule.
+      const failed = failing(result.findings, input.denyWarnings);
+      if (failed.length > 0) {
+        yield* FindingsReported.make({ count: failed.length });
       }
     }),
 ).pipe(
@@ -263,11 +272,11 @@ export const lintCommand = Command.make(
 );
 
 /** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
-export const validateLayer = (overrides: Overrides) =>
+export const validateLayer = (flags: Flags) =>
   Layer.merge(
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
     AuditCacheLive,
-  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)), Layer.provideMerge(statusLayer));
+  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
@@ -306,6 +315,17 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   Command.provide((input) => validateLayer({ presets: input.preset })),
 );
 
+const installLine = (install: Install): string => {
+  switch (install.status) {
+    case "installed":
+      return `installed: @drkmttr/adhere with ${install.packageManager}`;
+    case "listed":
+      return "installed: none, @drkmttr/adhere is already in package.json";
+    case "no-package-json":
+      return "installed: none, there is no package.json";
+  }
+};
+
 /** `adhere init`: the scaffold. */
 export const initCommand = Command.make("init", { force }, (input) =>
   Effect.gen(function* () {
@@ -314,10 +334,15 @@ export const initCommand = Command.make("init", { force }, (input) =>
     const lines = [
       result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
       result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
+      installLine(result.install),
     ];
     yield* Console.log(lines.join("\n"));
   }),
-).pipe(Command.withDescription("Scaffold .adhere/config.ts and example Markdown rules."));
+).pipe(
+  Command.withDescription(
+    "Scaffold .adhere/config.ts and example Markdown rules, and add @drkmttr/adhere to devDependencies with the project's package manager.",
+  ),
+);
 
 /**
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
@@ -376,10 +401,22 @@ export const logoutCommand = Command.make("logout", {}, () =>
   Command.provide(CredentialsLive),
 );
 
-/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
-export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
+/** The agent skills the binary carries, by the name `adhere skill` takes. */
+const skills = { rules: skill, fix: fixSkill } as const;
+
+const skillName = Argument.choice("skill", ["rules", "fix"] as const).pipe(
+  Argument.withDefault("rules" as const),
+  Argument.withDescription(
+    "rules, the default, to gather a repo's conventions into rules and configure adhere; fix, to verify and fix the findings lint reports.",
+  ),
+);
+
+/** `adhere skill [rules|fix]`: an agent skill, as shipped in the binary. */
+export const skillCommand = Command.make("skill", { name: skillName }, ({ name }) =>
+  Console.log(skills[name].trimEnd()),
+).pipe(
   Command.withDescription(
-    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
+    "Print an agent skill: by default the one that gathers a repo's conventions into rules and configures adhere, or with fix, the one that verifies and fixes lint's findings. Pipe it into .agents/skills/<name>/SKILL.md or hand it to an agent.",
   ),
 );
 

package/src/comments.ts

@@ -0,0 +1,36 @@
+import { scan } from "#highlight.ts";
+
+/** `@adhere` anywhere in a comment makes it a note for Jev. */
+const NOTE = /@adhere\b/;
+
+/**
+ * Whether a comment is a note for Jev: one that says `@adhere` anywhere in
+ * it, which stays when comments are taken out.
+ */
+export const isNote = (comment: string): boolean => NOTE.test(comment);
+
+/**
+ * A file's lines with its comments taken out, but for those `keep` keeps:
+ * each comment's text removed and its line breaks kept, so every line keeps
+ * its number, and a line with only the spaces before a comment left empty. A
+ * string, template literal, or regular expression that holds `//` or `/*`
+ * stays whole, as the highlighter reads it.
+ */
+export const withoutComments = (
+  lines: ReadonlyArray<string>,
+  keep: (comment: string) => boolean = () => false,
+): ReadonlyArray<string> => {
+  const code = lines.join("\n");
+  // No comment can start without one of these, so a file without them is sent as it is.
+  if (!code.includes("//") && !code.includes("/*")) return lines;
+  const tokens = scan(code);
+  // What the highlighter could not read, if anything, stays as it was.
+  const read = tokens.reduce((length, token) => length + token.text.length, 0);
+  const kept =
+    tokens
+      .map(({ text, kind }) =>
+        kind === "comment" && !keep(text) ? text.replace(/[^\n]/g, "") : text,
+      )
+      .join("") + code.slice(read);
+  return kept.split("\n").map((line, index) => (line === lines[index] ? line : line.trimEnd()));
+};

package/src/config.ts

@@ -17,6 +17,17 @@ const RuleFields = Schema.Struct({
   should: Schema.optionalKey(Schema.String),
   shouldNot: Schema.optionalKey(Schema.String),
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * Test files, which a rule skips by default: `only` for a rule about tests,
+   * which judges nothing else, and `include` for one that holds in tests too.
+   */
+  tests: Schema.optionalKey(Schema.Literals(["only", "include"])),
+  /**
+   * How a finding under the rule is reported: an `error`, the default, which
+   * fails the run, or a `warning`, for a nit or a rule that errs toward false
+   * findings, which does not.
+   */
+  level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
 });
 
 /** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
@@ -51,6 +62,9 @@ export const Rule = Schema.Struct({
   );
 export interface Rule extends Schema.Schema.Type<typeof Rule> {}
 
+/** How a finding is reported: an error fails the run, a warning does not. */
+export type Level = NonNullable<Rule["level"]>;
+
 /** One of a rule's examples, under the word it is written with. */
 export interface Example {
   readonly word: "must" | "never" | "should" | "should not";
@@ -79,9 +93,29 @@ export type Rules = Readonly<Record<RuleId, Rule>>;
 /** Rules inline, or a directory of Markdown rule files (see `markdown.ts`). */
 export type RuleSource = Rules | string | URL;
 
+/** A rule's setting in a config's `overrides`: `off`, a level, or a level and a threshold. */
+const Override = Schema.Union([
+  Schema.Literals(["off", "error", "warning"]),
+  Schema.Struct({
+    level: Schema.optionalKey(Schema.Literals(["off", "error", "warning"])),
+    threshold: Schema.optionalKey(Schema.Finite),
+  }),
+]);
+export type Override = typeof Override.Type;
+
 export const AdhereConfig = Schema.Struct({
+  /**
+   * The model id sent to typesafe. Defaults to "jev-latest"
+   */
   model: Schema.optionalKey(Schema.String),
+  /**
+   * The minimum confidence threshold for a positive match. Defaults to 0.8
+   */
   threshold: Schema.optionalKey(Schema.Finite),
+  /**
+   * The presets to use for rule matching. Defaults to an empty array. Current presets
+   * include "effect" and "alchemy". Subcategories can be expanded by appending `/<subcategory>`.
+   */
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
@@ -90,6 +124,24 @@ export const AdhereConfig = Schema.Struct({
    * Unset: `.adhere/` when that directory exists, otherwise no rules.
    */
   rules: Schema.optionalKey(Schema.Union([Schema.Record(Schema.String, Rule), Schema.String])),
+  /**
+   * Globs, relative to the working directory, of files no rule judges: what
+   * `--filter '!<glob>'` leaves out of one run, left out of every run.
+   */
+  exclude: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * Settings for rules by the id a report names them with, a preset's with
+   * its preset first, as in `alchemy/providers/idempotent-delete`: `off`, a
+   * level, or `{ level, threshold }`. A preset's rule changes without its text
+   * being copied into `rules`.
+   */
+  overrides: Schema.optionalKey(Schema.Record(Schema.String, Override)),
+  /**
+   * Whether Jev reads every comment, for rules about comments. By default
+   * comments are taken out, since a comment changes nothing a file does, but
+   * for the notes that say `@adhere`.
+   */
+  includeComments: Schema.optionalKey(Schema.Boolean),
 });
 
 /** Where a repo keeps its rule files by default. The cache lives under it. */
@@ -120,17 +172,36 @@ export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
   "vendor",
   "e2e",
 ]);
-export interface AdhereConfig extends Schema.Schema.Type<typeof AdhereConfig> {}
+/**
+ * Directories whose files are tests, matched as whole path segments below the
+ * working directory, as skipped directories are. Only a rule that says `tests`
+ * judges them, or a `.test.ts` or `.spec.ts` file anywhere.
+ */
+export const TEST_DIRECTORIES: ReadonlySet<string> = new Set([
+  "test",
+  "tests",
+  "__tests__",
+  "fixtures",
+]);
 
-/** The shape a config file default-exports. */
+/** The shape a config file default-exports: the schema's input, where `presets` is optional. */
 export type Config = typeof AdhereConfig.Encoded;
 
 export const defineConfig = (config: Config) => config;
 
 /** A built-in rule set. Same shape as a config, minus `presets`. */
 export interface Preset {
+  /**
+   * Override the model id used. Defaults to "jev-latest"
+   */
   readonly model?: string;
+  /**
+   * Override the threshold that determines a positive match. Defaults to 0.8
+   */
   readonly threshold?: number;
+  /**
+   * Per-rule overrides.
+   */
   readonly rules: RuleSource;
 }
 
@@ -150,15 +221,19 @@ export interface ResolvedConfig {
   readonly scopedRules?: RuleSet;
   /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
   readonly rpm?: number;
+  /** The config's globs of files no rule judges. */
+  readonly exclude?: ReadonlyArray<string>;
+  /** Whether Jev reads every comment; unset, only the `@adhere` notes. */
+  readonly includeComments?: boolean;
 }
 
 /** Command-line values that apply on top of the config file. */
-export interface Overrides {
+export interface Flags {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
-  readonly threshold?: number;
+  readonly threshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
-  readonly rpm?: number;
+  readonly rpm?: number | undefined;
 }
 
 /**
@@ -167,10 +242,10 @@ export interface Overrides {
  * the whole preset already holds its rules.
  */
 export const presetsOf = (
-  config: Pick<AdhereConfig, "presets">,
-  overrides: Overrides,
+  config: Pick<typeof AdhereConfig.Type, "presets">,
+  flags: Flags,
 ): ReadonlyArray<PresetName> => {
-  const named = [...new Set([...(overrides.presets ?? []), ...config.presets])];
+  const named = [...new Set([...(flags.presets ?? []), ...config.presets])];
   return named.filter((name) => {
     const [whole] = name.split("/");
     return whole === name || !named.some((other) => other === whole);
@@ -183,11 +258,11 @@ export const presetsOf = (
  * rule with the same id.
  */
 export const resolveConfig = (
-  config: Loaded<AdhereConfig>,
-  overrides: Overrides = {},
+  config: Loaded<typeof AdhereConfig.Type>,
+  flags: Flags = {},
   registry: Readonly<Partial<Record<PresetName, Loaded<Preset>>>> = {},
 ): ResolvedConfig => {
-  const applied = presetsOf(config, overrides).flatMap((name) => {
+  const applied = presetsOf(config, flags).flatMap((name) => {
     const preset = registry[name];
     return preset === undefined ? [] : [preset];
   });
@@ -195,9 +270,11 @@ export const resolveConfig = (
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
   return {
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
-    threshold: overrides.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
+    threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
-    ...(overrides.rpm === undefined ? {} : { rpm: overrides.rpm }),
+    ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
+    ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
+    ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
   };
 };
 
@@ -206,7 +283,14 @@ export class ConfigUnavailable extends Schema.TaggedError<ConfigUnavailable>()(
   { message: Schema.String },
 ) {}
 
-export const decodeConfig = (value: unknown): Effect.Effect<AdhereConfig, ConfigUnavailable> =>
+/**
+ * Decodes an in-memory value. @adhere The file-reading caller loadConfigFile
+ * in services/AdhereConfig.ts prefixes these errors with the config path;
+ * verified in its source and by CLI probes at all three config paths, 2026-09-26.
+ */
+export const decodeConfig = (
+  value: unknown,
+): Effect.Effect<typeof AdhereConfig.Type, ConfigUnavailable> =>
   Schema.decodeUnknownEffect(AdhereConfig)(value).pipe(
     Effect.mapError((problem) =>
       ConfigUnavailable.make({