@drkmttr/adhere 0.11.0 → 0.13.0

package/README.md

@@ -60,7 +60,8 @@ Without a config or rules, `adhere lint --preset effect` audits against the
 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.
+  × data/brand-ports: A port must be a branded, range-checked integer, never a bare number.
+    confidence 0.93 · context 0.88
    ╭─[src/server.ts:6:3]
  1 │ import { Effect } from "effect";
  2 │ import { listen } from "./listen.ts";
@@ -78,12 +79,28 @@ built-in Effect rules. A finding looks like this:
           Schema.brand("Port"),
         );
 
+  confidence  0–0.74 < 0.8 < 0.85–1  Jev's probability that the file breaks the rule
+  context     0–0.49 < 0.6 < 0.70–1  its probability that the file shows enough to decide
+
 Found 1 error.
 42 files, 3 judged, 39 cached.
 ```
 
-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
+The header is the rule id and the rule's description, and two scores have
+the next line. `confidence` is Jev's probability that the file breaks the
+rule. `context` is its probability that the file shows enough to decide that
+(see below). On a terminal a confidence is amber near its rule's threshold,
+and green above that. Near is within a quarter of the room above the
+threshold, on either side: 0.05 at a threshold of 0.80, so 0.75 to 0.84. A
+rule whose findings are mostly amber turns on where its threshold sits, which
+may be too low. Below the amber a score is red: lint reports no finding with
+a confidence there. A context is colored the same way around the sufficiency
+threshold, so at 0.60 it is amber from 0.50 to 0.69 and red below 0.50, the
+finding to doubt first. A legend under the last finding gives each score's
+threshold between the range in red and the range in green. The threshold and
+each `<` are amber, for the scores between them. Confidence's threshold there is the run's;
+a rule with a threshold of its own has its ranges around that.
+A preset's rule has the preset's name first, as in
 `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 section of the file Jev points at, with the line it names
@@ -99,12 +116,12 @@ 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:
+file, a library, or a service does. Its probability that the file does show
+enough is the finding's `context`. When that is below 0.6, the finding gets a
+warning under its code, 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)
+  warning: this file may not show enough to check this rule
      help: add what the code relies on outside this file as a note Jev reads:
            // @adhere <the fact>, and how you know it
 ```
@@ -139,9 +156,12 @@ 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
+adhere init --shared org/repo  # scaffold a repo of rules other repos install
+adhere list org/repo           # list the rules in another repo's .adhere/rules/
+adhere install org/repo        # copy them into this repo's .adhere/rules/org/repo/
 adhere login                   # save a TypeSafe AI API key for later runs
 adhere logout                  # delete the saved key
-adhere skill                   # print the agent skill (below)
+adhere skill [setup|fix]       # print an agent skill (below)
 ```
 
 Bare `adhere` prints the help, which lists the commands, and
@@ -301,12 +321,63 @@ When there is a `package.json`, init also adds `@drkmttr/adhere` to its
 `<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.
+`--ignore-workspace-root-check`, so the install also works at a workspace root.
 It skips the install when `package.json` already lists adhere.
 
+`adhere init --shared org/repo` scaffolds a repo whose rules other repos copy
+in with `adhere install` (see [Sharing rules](#sharing-rules)) instead of one
+that lints itself. It writes the two example rules and no config, since
+install copies only rule files, and with them:
+
+- `README.md`, which says what the repo is for, how to install its rules, and
+  how to add one.
+- `.github/workflows/adhere.yaml`, which runs `adhere validate` on every push
+  to main and every pull request, with the `TYPESAFE_API_KEY` secret. A pull
+  request from a fork gets no secrets, so validate refuses there.
+- `alchemy.run.ts`, an [alchemy](https://alchemy.run) stack that creates the
+  GitHub repo, or adopts it, and sets that secret from `TYPESAFE_API_KEY`
+  when deployed with `npx alchemy deploy`. The repo is public unless you
+  answer yes when init asks, at a terminal, whether to make it private. Other
+  repos then need git's credentials for it to list and install its rules.
+  Without a terminal it is public; change `visibility` in the stack to make it
+  private.
+- `package.json`, with alchemy and effect pinned to versions that work
+  together, which init installs, and a `.gitignore` for them and alchemy's
+  state.
+
+### Sharing rules
+
+An organization's rules can live in one repo's `.adhere/rules/`, and other
+repos copy them in. `adhere list org/repo` prints each rule there with its
+description. `adhere install org/repo` copies every rule's directory into this
+repo's `.adhere/rules/org/repo/`, so `data/brand-ports` from
+darkmatter/standards is `.adhere/rules/darkmatter/standards/data/brand-ports/`,
+the rule `darkmatter/standards/data/brand-ports`, and two repos' rules never
+collide.
+A topic or a rule after the repo copies only that part, and `#` picks a branch
+or tag:
+
+```sh
+adhere install darkmatter/standards/data                # the data topic
+adhere install darkmatter/standards/data/brand-ports    # one rule
+adhere install darkmatter/standards#v3                  # every rule, as tagged v3
+```
+
+The copies are the repo's own rules from then on: commit them, edit them, or
+start new rules from them. Nothing tracks where they came from, so a later
+install skips a rule already there, as init does, and `--force` replaces its
+directory, edits and all. A rule's whole directory is copied, so a `RULE.ts`
+comes with the helpers beside it, and runs whenever lint does, in CI too: read
+what you install. `adhere list` names a `RULE.ts` without its description,
+since reading it would run it. The source's config, its inline rules, and its
+cache are not copied. A config with inline `rules` replaces `.adhere/rules/`,
+so it replaces copied rules too.
+
+The source is cloned with `git` from `https://github.com/org/repo.git`, so a
+private repo needs git's credentials for GitHub, as `gh auth setup-git` sets
+up. To clone over SSH instead, let git rewrite the URL:
+`git config --global url.git@github.com:.insteadOf https://github.com/`.
+
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
@@ -362,8 +433,8 @@ login. `adhere logout` deletes the saved key.
 
 ## Config
 
-A config file is optional. Without one, adhere reads the rule files in
-`.adhere/` and any `--preset`. A config names presets, sets the model and
+A config file is optional. Without one, adhere reads the rules in
+`.adhere/rules/` and any `--preset`. A config names presets, sets the model and
 thresholds, or gives rules inline. It sits in the working directory of the
 repo being audited, at one of these paths (keep one):
 
@@ -408,21 +479,35 @@ 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.
+`adhere init` writes `.adhere/tsconfig.json`, a project for the config and any
+[rules written in TypeScript](#rules-as-typescript-files), 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. One written
+before rules could be TypeScript includes only `config.ts`; make its `include`
+`["**/*.ts"]` to give rule files their types.
 
-`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.
+`rules` in the config, inline as above or as a directory (below), replaces
+`.adhere/rules/`: none of its rules, root or nested, is read then.
 
 ### Rules as Markdown files
 
-A repo's own rules live in `.adhere/`, one `*.md` file per rule, next to the
-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 under
+A repo's own rules live in `.adhere/rules/`, a directory per rule, which holds
+the rule as a `RULE.md`, or as a `RULE.ts` (see
+[Rules as TypeScript files](#rules-as-typescript-files)). The directory's path
+is the rule id, so `.adhere/rules/data/brand-ports/RULE.md` is
+`data/brand-ports`, and a directory that holds no rule, such as `data/`, is a
+topic. Nothing else in a rule's directory, such as notes or a helper its
+`RULE.ts` imports, is read as a rule, and a directory with both a `RULE.md` and
+a `RULE.ts` refuses the run. When `.adhere/rules/` exists, it is read without
+any config.
+
+Rules used to be any `*.md` file in `.adhere/`, as
+`.adhere/data/brand-ports.md`. A `*.md` file outside every rule's directory,
+but a `README.md`, now refuses the run, and the refusal says where each such
+file goes to keep its id, so `adhere-ignore` comments and `overrides` still
+name it.
+
+A `RULE.md` 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
@@ -489,7 +574,7 @@ the names before 0.7, read as `must` and `never`.
 
 Nested `.adhere/` directories are also discovered, except under
 `node_modules/`, `dist/`, and the other skipped directories (above). A rule in
-`packages/api/.adhere/data/brand-ports.md` has the same id,
+`packages/api/.adhere/rules/data/brand-ports/RULE.md` has the same id,
 `data/brand-ports`, but applies only to files under `packages/api/`. Root
 `.adhere/` rules apply project-wide. If a nested rule has the same id as a root
 rule, the nearest containing `.adhere/` shadows the less-specific rule for that
@@ -498,8 +583,8 @@ priority system: presets are global, project rules override preset rules with
 the same id, and nested project rules override less-specific project rules with
 the same id for files in their subtree.
 
-`.adhere/` is the default rather than `docs/adhere/` because it keeps
-everything adhere owns in one directory: the config and the cache are tool
+`.adhere/rules/` is the default rather than `docs/adhere/` because it keeps
+everything adhere owns in `.adhere/`: the config and the cache are tool
 state, not documentation, and would stay in `.adhere/` anyway. A nested
 `.adhere/` also scopes its rules to the directory that contains it (above). The
 cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
@@ -510,7 +595,59 @@ documentation can point `rules` at `docs/adhere/`:
 export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });
 ```
 
-Rules read through `rules` apply project-wide.
+That directory holds its rules as `.adhere/rules/` does, a directory per rule,
+and they apply project-wide.
+
+### Rules as TypeScript files
+
+A rule's directory can hold it as a `RULE.ts` instead, which default-exports
+`defineRule({...})`, taking the fields a config's inline rule does. What
+TypeScript adds is `appendState`, a hook on what Jev reads for the rule:
+
+```ts
+// .adhere/rules/data/columns/RULE.ts
+import { defineRule } from "@drkmttr/adhere";
+
+export default defineRule({
+  description:
+    "A query must name only columns its table has in `schema`, and never a column it lacks.",
+  must: 'db.select("id", "email").from("users")',
+  never: 'db.select("mail").from("users")',
+  appendState: async (state, file, Bun) => ({
+    schema: await Bun.file("db/schema.sql").text(),
+  }),
+});
+```
+
+Right before each request about the rule goes out, `appendState` gets the
+request's state, the file it is about, and Bun's API, and what it returns is
+spread over the state. The state is what Jev reads beside each question:
+`code`, the file's sections as Jev reads them, under their numbers from 1, as
+in `{ code: { "1": "import …", "2": "export const …" } }`. `file` is the file's
+absolute `path`, and its `contents` as written, comments and all. The
+description can name a key the hook adds, in backticks, as the questions name
+`code`. Nothing the hook returns is checked, so it can change `code` too, or
+replace it: a hook can break its own rule's answers, and adhere does not stop
+it. It can be async, and one that throws refuses the run, naming the rule.
+
+A rule with a hook goes to Jev in requests of its own, to judge a file and to
+locate a finding, so only that rule reads what its hook adds, and no other
+rule's answer depends on it. Each of those requests sends the file again. The
+plan counts them, but not the tokens a hook adds, which are not known until it
+runs; a request over Jev's context skips the file, as a file too long does.
+
+The cache keys a judgment by the file's content and the rule, and the hook is
+part of the rule by its source: editing the hook judges the rule again. What
+the hook reads outside the file is not, so when `db/schema.sql` changes, a file
+already judged is not judged again until it or the rule changes.
+
+A `RULE.ts` is imported, as a config is, so its code runs on every lint, and
+one that default-exports no rule refuses the run. It can import other files by
+relative path, such as a helper beside it in its directory, but the executable
+resolves no packages besides `@drkmttr/adhere`. `Bun` is typed when
+`@types/bun` is installed and `.adhere/tsconfig.json` lists it, as
+`"types": ["bun"]`, and is `unknown` otherwise. A config's inline rules can
+have `appendState` too.
 
 ### Scoping a rule
 
@@ -628,7 +765,7 @@ A preset rule says "must" only where its source makes a requirement, and
 "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
+`Config.mapEffect` 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.
 
@@ -726,7 +863,10 @@ config's `sufficiencyThreshold`, which beats the default, `0.6`.
    file and that rule, not on which other rules share the request. Every
    question shares the state cost of the request. On up to 10 files per
    project rule, the rule's question has a second one beside it, the linter
-   check (see [Validate](#validate)), with the same fields.
+   check (see [Validate](#validate)), with the same fields. A rule with
+   `appendState` has requests of its own, here and below, whose state is what
+   its hook makes of this one (see
+   [Rules as TypeScript files](#rules-as-typescript-files)).
 2. A second request only when at least one rule's probability is above its
    threshold. Per flagged rule, when the file has more than one section, one
    `choice` question among the sections' numbers, which yields the section to
@@ -760,7 +900,7 @@ 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
+the rule's text, and of the source of the rule's `appendState`, if it has one. 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
 differently re-judges every rule once. A lowered threshold locates cached
 judgments that are newly above it without judging again. `tallies/` keeps the
@@ -799,18 +939,25 @@ every file is cached needs no key and no network.
 
 ## Agent skill
 
-Two skills teach an agent to work with adhere:
+Three 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/SKILL.md`](./skills/adhere/SKILL.md) is the reference: the
+  commands, how to write and word a rule, the config, presets, shared rules,
+  comments and suppressions, the cache, reading a report, and tuning a rule.
+- [`skills/adhere-setup/SKILL.md`](./skills/adhere-setup/SKILL.md) sets adhere
+  up in a repo with the user. It drafts rules from the repo's conventions,
+  offers fitting presets and a shared org repo's rules, shows them all in one
+  list to choose from, imports and validates the chosen ones, walks through
+  the first lint, and adds a CI workflow.
 - [`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
+`skills add darkmatter/adhere`. The binary carries all three: `adhere skill`
+prints the reference, `adhere skill setup` the setup skill, and
+`adhere skill fix` the fix skill, so
 `adhere skill fix > .agents/skills/adhere-fix/SKILL.md` works without a
 checkout.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -37,10 +37,10 @@
     "release": "release-it"
   },
   "dependencies": {
-    "effect": "4.0.0-rc.112"
+    "effect": "4.0.0-rc.118"
   },
   "devDependencies": {
-    "@effect/platform-bun": "4.0.0-rc.112",
+    "@effect/platform-bun": "4.0.0-rc.118",
     "@types/bun": "^1.4.2",
     "@types/node": "^24.13.6",
     "release-it": "^21.1.0",
@@ -49,7 +49,7 @@
     "vitest": "4.1.11"
   },
   "overrides": {
-    "@effect/platform-node-shared": "4.0.0-rc.112"
+    "@effect/platform-node-shared": "4.0.0-rc.118"
   },
   "release-it": {
     "$schema": "https://unpkg.com/release-it@21.1.0/schema/release-it.json",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.11.0",
-    "@drkmttr/adhere-darwin-x64": "0.11.0",
-    "@drkmttr/adhere-linux-arm64": "0.11.0",
-    "@drkmttr/adhere-linux-x64": "0.11.0",
-    "@drkmttr/adhere-win32-x64": "0.11.0"
+    "@drkmttr/adhere-darwin-arm64": "0.13.0",
+    "@drkmttr/adhere-darwin-x64": "0.13.0",
+    "@drkmttr/adhere-linux-arm64": "0.13.0",
+    "@drkmttr/adhere-linux-x64": "0.13.0",
+    "@drkmttr/adhere-win32-x64": "0.13.0"
   }
 }

package/presets/effect/basics/{instrument-with-pipe.md → instrument-with-pipe/RULE.md}

@@ -7,7 +7,7 @@ description: Timeouts, retries, logging, and spans must be attached with .pipe,
 ```ts
 const program = fetchData.pipe(
   Effect.timeout("5 seconds"),
-  Effect.retry(Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)))),
+  Effect.retry(Schedule.max([Schedule.exponential("100 millis"), Schedule.recurs(3)])),
   Effect.tap((data) => Effect.logInfo(`Fetched: ${data}`)),
   Effect.withSpan("fetchData"),
 );

package/presets/effect/config/{business-logic-depends-on-config-service.md → business-logic-depends-on-config-service/RULE.md}

@@ -15,8 +15,8 @@ class ApiConfig extends Context.Service<
   static readonly layer = Layer.effect(
     ApiConfig,
     Effect.gen(function* () {
-      const apiKey = yield* Config.redacted("API_KEY");
-      const baseUrl = yield* Config.string("API_BASE_URL");
+      const apiKey = yield* Config.Redacted("API_KEY");
+      const baseUrl = yield* Config.String("API_BASE_URL");
       return { apiKey, baseUrl };
     }),
   );
@@ -27,7 +27,7 @@ class ApiConfig extends Context.Service<
 
 ```ts
 const sendInvoice = Effect.fn("sendInvoice")(function* (invoice: Invoice) {
-  const apiUrl = yield* Config.string("BILLING_API_URL");
+  const apiUrl = yield* Config.String("BILLING_API_URL");
   return yield* post(apiUrl, invoice);
 });
 ```

package/presets/effect/config/{secrets-are-redacted.md → secrets-are-redacted/RULE.md}

@@ -1,12 +1,12 @@
 ---
-description: A token, password, or key must be read with Config.redacted, never with Config.string.
+description: A token, password, or key must be read with Config.Redacted, never with Config.String.
 ---
 
 ## Must
 
 ```ts
 const program = Effect.gen(function* () {
-  const apiKey = yield* Config.redacted("API_KEY");
+  const apiKey = yield* Config.Redacted("API_KEY");
 
   const headers = {
     Authorization: `Bearer ${Redacted.value(apiKey)}`,
@@ -19,5 +19,5 @@ const program = Effect.gen(function* () {
 ## Never
 
 ```ts
-const token = yield* Config.string("GITHUB_TOKEN");
+const token = yield* Config.String("GITHUB_TOKEN");
 ```

package/presets/effect/config/{validate-with-schema.md → validate-with-schema/RULE.md}

@@ -1,5 +1,5 @@
 ---
-description: A config value with constraints must be validated as it is read, with Config.schema or Config.mapOrFail, never checked by hand after reading.
+description: A config value with constraints must be validated as it is read, with Config.schema or Config.mapEffect, never checked by hand after reading.
 ---
 
 ## Must
@@ -14,8 +14,8 @@ const Environment = Schema.Literals(["development", "staging", "production"]);
 const program = Effect.gen(function* () {
   const port = yield* Config.schema(Port, "PORT");
   const env = yield* Config.schema(Environment, "ENV");
-  const timeoutMs = yield* Config.int("TIMEOUT_MS").pipe(
-    Config.mapOrFail((ms) =>
+  const timeoutMs = yield* Config.Int("TIMEOUT_MS").pipe(
+    Config.mapEffect((ms) =>
       ms > 0 && ms <= 60_000
         ? Effect.succeed(ms)
         : Effect.fail(
@@ -33,7 +33,7 @@ const program = Effect.gen(function* () {
 ## Never
 
 ```ts
-const timeoutMs = yield* Config.number("TIMEOUT_MS");
+const timeoutMs = yield* Config.Number("TIMEOUT_MS");
 if (timeoutMs <= 0 || timeoutMs > 60_000) {
   return yield* Effect.die("TIMEOUT_MS out of range");
 }