@drkmttr/adhere 0.18.0 → 0.18.1

package/README.md

@@ -97,6 +97,7 @@ your rules.
 - [Reading the report](#reading-the-report)
 - [Rule format](#rule-format)
 - [Config](#config)
+- [Other Providers](#providers)
 - [Running lint](#running-lint)
 - [Comments and suppressions](#comments-and-suppressions)
 - [Cache](#cache)
@@ -123,12 +124,14 @@ curl -fsSL --create-dirs -o ~/.local/bin/adhere \
 chmod +x ~/.local/bin/adhere
 ```
 
-- The npm package brings its own TypeScript compiler, for the
-  [`symbols` and `references`](#what-jev-reads) Jev reads by default. No other
-  setup is needed.
-- The standalone executable has no compiler, so it lints only with `reads: []`
-  or `reads: ["workspacePackages"]` in the [config](#config). It suits a global
-  install that your agent config can always call.
+- The npm package brings its own TypeScript compiler. Opt in with
+  `--type-aware` or `typeAware: true` to add both
+  [`symbols` and `references`](#what-jev-reads); type awareness is off by default.
+  No other compiler setup is needed.
+- The standalone executable has no compiler. It runs the default, compiler-free
+  audit with workspace context, or code alone with `reads: []`. Type-aware audits
+  require the npm package or a checkout with its development dependencies.
+  It suits a global install that your agent config can always call.
 - It is built for macOS and Linux, on arm64 and x64, and for Windows x64:
   download `adhere-Windows-x86_64.exe` from the
   [latest release](https://github.com/darkmatter/adhere/releases/latest).
@@ -354,13 +357,13 @@ writing a rule.
 
 ### What else the studies found
 
-| Lesson                                                 | What the study found                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "Should" is for people, not a weaker check.            | Rules written with "should" and with "must" scored nearly the same ([study](eval/studies/rule-vocabulary.md)).                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| A wrong finding is usually the rule's fault.           | Above 0.8, 31 of 35 wrong findings repeated within a rule: a scope its words reach past, or the same misreading again. Fixing the wording fixes them together. Below 0.8, one-off misreads grow, to about one finding in six at 0.6 to 0.7 ([study](eval/studies/presets.md)).                                                                                                                                                                                                                                                                                        |
-| Narrow a rule in its description.                      | Jev scores an `excludeIf` near 0.5 for real and false findings alike, so it thins a rule's findings about as much as a higher threshold ([study](eval/studies/presets.md)). Narrowing the description moves the judgment itself: scoping alchemy's idempotent-delete rule to providers' delete handlers dropped its findings elsewhere from 0.67–0.88 to 0.08–0.21, with nothing real lost ([study](eval/studies/idempotent-delete.md)).                                                                                                                              |
-| Beware rules that turn on what the file does not show. | The weakest preset rules hinged on facts outside the file: whether a client has a default timeout, whether a script is an entry point, whether a key is public ([study](eval/studies/presets.md)). Warning below a context of 0.7 marked one finding in five, and those were real about half the time, where the rest were real three times in four ([study](eval/studies/sufficiency.md)). Make such a rule a warning, or give Jev the fact with config-level [`reads`](#what-jev-reads), an [`appendState`](#rules-as-typescript-files) hook, or an `@adhere` note. |
-| Jev believes comments.                                 | Eight of nine real violations of the idempotent-delete rule carried a comment wrongly saying they were fine, and scored 0.31 to 0.62; without comments, all nine scored 0.81 or more ([study](eval/studies/idempotent-delete.md)). That is why adhere takes comments out. A fact Jev needs, such as an exemption, goes in an `@adhere` note, which stays ([study](eval/studies/comments.md)).                                                                                                                                                                         |
+| Lesson                                                 | What the study found                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Should" is for people, not a weaker check.            | Rules written with "should" and with "must" scored nearly the same ([study](eval/studies/rule-vocabulary.md)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| A wrong finding is usually the rule's fault.           | Above 0.8, 31 of 35 wrong findings repeated within a rule: a scope its words reach past, or the same misreading again. Fixing the wording fixes them together. Below 0.8, one-off misreads grow, to about one finding in six at 0.6 to 0.7 ([study](eval/studies/presets.md)).                                                                                                                                                                                                                                                                                                    |
+| Narrow a rule in its description.                      | Jev scores an `excludeIf` near 0.5 for real and false findings alike, so it thins a rule's findings about as much as a higher threshold ([study](eval/studies/presets.md)). Narrowing the description moves the judgment itself: scoping alchemy's idempotent-delete rule to providers' delete handlers dropped its findings elsewhere from 0.67–0.88 to 0.08–0.21, with nothing real lost ([study](eval/studies/idempotent-delete.md)).                                                                                                                                          |
+| Beware rules that turn on what the file does not show. | The weakest preset rules hinged on facts outside the file: whether a client has a default timeout, whether a script is an entry point, whether a key is public ([study](eval/studies/presets.md)). Warning below a context of 0.7 marked one finding in five, and those were real about half the time, where the rest were real three times in four ([study](eval/studies/sufficiency.md)). Make such a rule a warning, or give Jev the fact with [`typeAware` or workspace `reads`](#what-jev-reads), an [`appendState`](#rules-as-typescript-files) hook, or an `@adhere` note. |
+| Jev believes comments.                                 | Eight of nine real violations of the idempotent-delete rule carried a comment wrongly saying they were fine, and scored 0.31 to 0.62; without comments, all nine scored 0.81 or more ([study](eval/studies/idempotent-delete.md)). That is why adhere takes comments out. A fact Jev needs, such as an exemption, goes in an `@adhere` note, which stays ([study](eval/studies/comments.md)).                                                                                                                                                                                     |
 
 ## Commands
 
@@ -570,7 +573,9 @@ finding its matchers dropped, with their scores.
 
 ### What Jev reads
 
-Beside the file's code, Jev reads three kinds of context, for every rule:
+By default, Jev reads the file's code and its imported workspace packages, with
+no native compiler startup. Opt in with `typeAware: true` in the config or
+`adhere lint --type-aware` to add both compiler context maps for every rule:
 
 | Name                | What Jev reads                                                                                                                                                                              |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -597,7 +602,7 @@ with `…` between them. For example, code importing `twice as scale` can receiv
 }
 ```
 
-When sent to Jev, each selected `references`, `symbols`, and `workspacePackages`
+When sent to Jev, each enabled `references`, `symbols`, and `workspacePackages`
 map includes a reserved `__comment` explaining its contents. These comments are
 included before `appendState` hooks and restored after hooks. Top-level guidance
 also tells Jev that these maps are context only: judge the target `code`, not the
@@ -609,18 +614,25 @@ and JSDoc tags are first capped separately by `maxSymbolDocumentationLength`, al
 256 by default; `0` omits documentation and tags. Smaller limits reduce request
 size but can cut off type signatures, overloads, useful details, or examples.
 
-To read fewer, list the ones you want in the config's `reads`:
+`typeAware` defaults to `false`. When enabled, it adds **both** `symbols` and
+`references`, regardless of `reads`. The `reads` setting now chooses workspace
+context only: its default is `["workspacePackages"]`; `[]` omits that map.
+Legacy `"symbols"` or `"references"` entries in `reads` alone do not enable native
+context, and leaving them out does not disable it when `typeAware` is true.
 
 ```ts
 // .adhere/config.ts
 import { defineConfig } from "@drkmttr/adhere";
 
 export default defineConfig({
-  reads: ["workspacePackages"], // no symbols or references
+  typeAware: true, // opt in to both symbols and references
+  reads: [], // omit workspacePackages, not compiler context
 });
 ```
 
-`reads: []` sends the code alone.
+For code alone, use `reads: []` with type awareness off; do not pass
+`--type-aware`. To retain workspace context without a compiler, leave the
+settings at their defaults.
 
 Each name is the key Jev reads it under, so a rule's description can name it in
 backticks, as the questions name `code`:
@@ -657,10 +669,12 @@ import { parse } from "orders-core";
 - What adhere has no name for, such as a file of the repository's, a rule in
   TypeScript adds with [`appendState`](#rules-as-typescript-files).
 
-**Cost and privacy.** `symbols` and `references` send Jev more than the file it
+**Cost and privacy.** Opting into type awareness sends Jev more than the file it
 judges: whole declarations from other files, plus compiler-provided documentation
-and JSDoc tags in `symbols`, even with `includeComments` off. The plan's estimate leaves their tokens out. Leave them
-out of `reads` to send less.
+and JSDoc tags in `symbols`, even with `includeComments` off. It also starts the
+native compiler during execution. The plan's estimate leaves those tokens out.
+Keep `typeAware` off to avoid that extra context and compiler work; changing
+`reads` only changes workspace context.
 
 <details>
 <summary>Where the packages come from</summary>
@@ -720,7 +734,7 @@ export default defineRule({
 - 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 …" } }`, beside what the
-  config [`reads`](#what-jev-reads).
+  config's [`reads` and `typeAware`](#what-jev-reads) enable.
 - `file` is the file's absolute `path`, and its `contents` as written, comments
   and all.
 - Nothing the hook returns is checked, so it can change `code` too, or replace
@@ -779,7 +793,8 @@ export default defineConfig({
   model: "jev-latest",
   threshold: 0.8,
   sufficiencyThreshold: 0.6,
-  reads: ["workspacePackages", "symbols", "references"],
+  reads: ["workspacePackages"],
+  typeAware: true, // optional; false by default
   presets: ["effect"],
   maxSymbolDocumentationLength: 256,
   maxSymbolLength: 256,
@@ -800,20 +815,21 @@ type UserId = typeof UserId.Type
 });
 ```
 
-| Key                            | Default                                          | Meaning                                                                                                                                                                |
-| ------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model`                        | `"jev-latest"`                                   | The model id sent to TypeSafe.                                                                                                                                         |
-| `threshold`                    | `0.8`                                            | Report a rule when Jev's probability is above this.                                                                                                                    |
-| `sufficiencyThreshold`         | `0.6`                                            | Below it, a finding warns that Jev may not see enough to decide.                                                                                                       |
-| `presets`                      | none                                             | Built-in rule sets, or their topics. See [Presets](#presets).                                                                                                          |
-| `rules`                        | `.adhere/rules/`                                 | Rules inline, as above, or a directory (see [Where rules live](#where-rules-live)). Either replaces `.adhere/rules/`: none of its rules, root or nested, is read then. |
-| `exclude`                      | none                                             | Globs, relative to the working directory, of files no rule judges.                                                                                                     |
-| `overrides`                    | none                                             | Settings for a rule by its id. See [Overrides](#overrides).                                                                                                            |
-| `includeComments`              | `false`                                          | Send every comment to Jev. See [Comments](#comments).                                                                                                                  |
-| `reads`                        | `["workspacePackages", "symbols", "references"]` | What Jev reads beside each file's code, for every rule. `[]` is the code alone. See [What Jev reads](#what-jev-reads).                                                 |
-| `maxSymbolDocumentationLength` | `256`                                            | Maximum characters of each symbol's combined documentation and JSDoc tags, before `maxSymbolLength` applies. A non-negative integer; `0` omits them.                   |
-| `maxSymbolLength`              | `256`                                            | Maximum characters of each complete `symbols[name]` string, including type signatures and documentation. A non-negative integer; `0` leaves names with empty content.  |
-| `provider`                     | TypeSafe's Jev                                   | Where the questions go instead, with its own model. See [Providers](#providers).                                                                                       |
+| Key                            | Default                 | Meaning                                                                                                                                                                |
+| ------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`                        | `"jev-latest"`          | The model id sent to TypeSafe.                                                                                                                                         |
+| `threshold`                    | `0.8`                   | Report a rule when Jev's probability is above this.                                                                                                                    |
+| `sufficiencyThreshold`         | `0.6`                   | Below it, a finding warns that Jev may not see enough to decide.                                                                                                       |
+| `presets`                      | none                    | Built-in rule sets, or their topics. See [Presets](#presets).                                                                                                          |
+| `rules`                        | `.adhere/rules/`        | Rules inline, as above, or a directory (see [Where rules live](#where-rules-live)). Either replaces `.adhere/rules/`: none of its rules, root or nested, is read then. |
+| `exclude`                      | none                    | Globs, relative to the working directory, of files no rule judges.                                                                                                     |
+| `overrides`                    | none                    | Settings for a rule by its id. See [Overrides](#overrides).                                                                                                            |
+| `includeComments`              | `false`                 | Send every comment to Jev. See [Comments](#comments).                                                                                                                  |
+| `reads`                        | `["workspacePackages"]` | Chooses workspace context only. `[]` omits it; native read entries do not enable type awareness. See [What Jev reads](#what-jev-reads).                                |
+| `typeAware`                    | `false`                 | Opt in to both compiler `symbols` and declaration `references`, regardless of `reads`. Also enabled by `--type-aware`.                                                 |
+| `maxSymbolDocumentationLength` | `256`                   | Maximum characters of each symbol's combined documentation and JSDoc tags, before `maxSymbolLength` applies. A non-negative integer; `0` omits them.                   |
+| `maxSymbolLength`              | `256`                   | Maximum characters of each complete `symbols[name]` string, including type signatures and documentation. A non-negative integer; `0` leaves names with empty content.  |
+| `provider`                     | TypeSafe's Jev          | Where the questions go instead, with its own model. See [Providers](#providers).                                                                                       |
 
 - An invalid shape refuses the run.
 - A config can import other files by relative path, but no packages besides
@@ -1122,6 +1138,7 @@ the default, `0.6`.
 | `--preset <names>`                 | Add built-in rule sets, or their topics. The config becomes optional. See [Presets](#presets). |
 | `--threshold <0 to 1>`             | Replace the config's threshold. Per-rule thresholds still apply.                               |
 | `--sufficiency-threshold <0 to 1>` | Replace the config's `sufficiencyThreshold`: a finding warns when its `context` is below it.   |
+| `--type-aware`                     | Enable both compiler `symbols` and declaration `references`; off by default.                   |
 | `--yes`, `-y`                      | Send the requests without asking first.                                                        |
 | `--limit <files>`                  | Send requests for at most that many files. See [Limiting a run](#limiting-a-run).              |
 | `--rpm <requests>`                 | Send at most that many requests a minute.                                                      |
@@ -1177,8 +1194,9 @@ Estimates cover only code and workspace-package context; symbol/reference input,
 - 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 leaves out `symbols` and `references`, which
-  adhere reads as it sends each file, so a run can cost more than it says.
+  September 2026. When type awareness is enabled, the estimate leaves out
+  `symbols` and `references`, which adhere reads as it sends each file, so a run
+  can cost more than it says.
 - A run that stops loses nothing: files finished before it stopped are cached,
   so running again continues from there.
 
@@ -1242,7 +1260,7 @@ it hashes or sends a file, or a declaration from
 [`references`](#what-jev-reads), blanking it so every line keeps its number.
 The report's excerpts still show them. Compiler-provided documentation and
 JSDoc tags still reach Jev in the type/docs strings [`symbols`](#what-jev-reads)
-sends; these are not editor hovers.
+sends when type awareness is enabled; these are not editor hovers.
 
 Jev takes what comments claim at their word, which hid real violations in the
 studies: see [Writing good rules](#writing-good-rules).
@@ -1474,17 +1492,21 @@ about three bytes a token, and leaves 1k of room for what Jev wraps around it.
 
 Names and layouts from older versions:
 
-| Version           | What it had                                                                                                  | What happens now                                                                                                                                                                                        |
-| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| before 0.7        | A rule's examples were `reference` and `avoid` in a config, and a fence could be tagged `avoid`.             | They still read as `must` and `never`.                                                                                                                                                                  |
-| through 0.7       | The `effect` preset checked seven conventions a linter checks exactly.                                       | They are left to `@effect/tsgo`. The notes on `effect` under [Presets](#presets) say how to turn them on.                                                                                               |
-| before 0.13       | A rule was any `*.md` file in `.adhere/`, as `.adhere/data/brand-ports.md`.                                  | A `*.md` file outside every rule's directory, but a `README.md`, refuses the run. The refusal says where each such file goes to keep its id, so `adhere-ignore` comments and `overrides` still name it. |
-| before 0.13       | `.adhere/tsconfig.json` included only `config.ts`.                                                           | Make its `include` `["**/*.ts"]` to give rules written in TypeScript their types.                                                                                                                       |
-| 0.13.1            | The workspace's packages had a key of their own, `includeWorkspacePackages: true`.                           | adhere no longer reads it. Jev reads the workspace's packages by default.                                                                                                                               |
-| 0.13.1 and before | Prose around a `RULE.md`'s code was ignored.                                                                 | Jev reads it after the description, as the rule's details, so a rule with prose is judged again once. Keep prose about the rule: why it holds, or where it does not apply.                              |
-| 0.15.0 and before | A rule named what Jev reads beside its code, in `reads`.                                                     | `reads` is the config's, for every rule, and a rule that has it refuses the run: delete it. Jev reads all three by default. See [What Jev reads](#what-jev-reads).                                      |
-| 0.15.0 and before | `--limit` counted rule checks.                                                                               | It counts files.                                                                                                                                                                                        |
-| 0.14.0 and before | The `effect` preset had `services/test-layers-are-in-memory` and `services/operations-have-no-requirements`. | They are gone, and an `overrides` entry naming either refuses the run: remove it. `@effect/tsgo`'s `leakingRequirements` checks the second. `adhere-ignore` comments naming them suppress nothing.      |
+| Version           | What it had                                                                                                  | What happens now                                                                                                                                                                                                    |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| before 0.7        | A rule's examples were `reference` and `avoid` in a config, and a fence could be tagged `avoid`.             | They still read as `must` and `never`.                                                                                                                                                                              |
+| through 0.7       | The `effect` preset checked seven conventions a linter checks exactly.                                       | They are left to `@effect/tsgo`. The notes on `effect` under [Presets](#presets) say how to turn them on.                                                                                                           |
+| before 0.13       | A rule was any `*.md` file in `.adhere/`, as `.adhere/data/brand-ports.md`.                                  | A `*.md` file outside every rule's directory, but a `README.md`, refuses the run. The refusal says where each such file goes to keep its id, so `adhere-ignore` comments and `overrides` still name it.             |
+| before 0.13       | `.adhere/tsconfig.json` included only `config.ts`.                                                           | Make its `include` `["**/*.ts"]` to give rules written in TypeScript their types.                                                                                                                                   |
+| 0.13.1            | The workspace's packages had a key of their own, `includeWorkspacePackages: true`.                           | adhere no longer reads it. Jev reads the workspace's packages by default.                                                                                                                                           |
+| 0.13.1 and before | Prose around a `RULE.md`'s code was ignored.                                                                 | Jev reads it after the description, as the rule's details, so a rule with prose is judged again once. Keep prose about the rule: why it holds, or where it does not apply.                                          |
+| 0.15.0 and before | A rule named what Jev reads beside its code, in `reads`.                                                     | `reads` is the config's, for every rule, and a rule that has it refuses the run: delete it. Workspace context is on by default; compiler context requires `typeAware: true`. See [What Jev reads](#what-jev-reads). |
+| 0.15.0 and before | `--limit` counted rule checks.                                                                               | It counts files.                                                                                                                                                                                                    |
+| 0.14.0 and before | The `effect` preset had `services/test-layers-are-in-memory` and `services/operations-have-no-requirements`. | They are gone, and an `overrides` entry naming either refuses the run: remove it. `@effect/tsgo`'s `leakingRequirements` checks the second. `adhere-ignore` comments naming them suppress nothing.                  |
+
+Configs that previously enabled compiler context with `reads: ["symbols", "references"]`
+must now opt in with `typeAware: true`, or use `adhere lint --type-aware`.
+That switch enables both maps; `reads` only controls workspace context.
 
 ## Development
 
@@ -1497,13 +1519,13 @@ adhere lint --preset effect
 ```
 
 - In a checkout no platform package is installed, so `bin/adhere.js` runs
-  `src/main.ts` with Bun instead, and `symbols` and `references` use the
-  checkout's own TypeScript.
+  `src/main.ts` with Bun instead. Type-aware audits use the checkout's own
+  TypeScript; the default audit does not start it.
 - `bun run typecheck` runs `tsc` and the linter.
 - `bun run test` runs the tests.
 - `bun scripts/verify-npm.ts`, after `bun run build:npm`, installs the built
-  packages in a scratch project and checks that they read `symbols` and
-  `references`. It needs Node 24 or later, and sends Jev nothing.
+  packages in a scratch project and explicitly enables `typeAware: true` to
+  check `symbols` and `references`. It needs Node 24 or later, and sends Jev nothing.
 
 ### Native executable
 

package/package.json

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

package/skills/adhere/SKILL.md

@@ -27,6 +27,7 @@ adhere lint                      # judge the working directory; exit 1 on an err
 adhere lint --limit 0            # compiler-free counts/cache plan; no budgeting
 adhere lint --limit 100          # first 100 files needing requests; all pending rules per file
 adhere lint --yes                # send without asking, as in CI
+adhere lint --type-aware         # opt in to both compiler symbols and declaration references
 adhere lint --preset effect      # add a built-in rule set; the config becomes optional
 adhere lint --filter 'src/**'    # read only matching files; repeat, and ! to leave out
 adhere lint --threshold 0.9      # report at another threshold from the cache; judges nothing again
@@ -38,8 +39,9 @@ adhere skill [docs|setup|fix]    # print a skill
 
 `adhere <command> --help` lists every flag. Version, help, skills, `validate`,
 and planning with `--limit 0` do not start the native compiler. Default `lint`
-starts it only during execution, after confirmation, for pending judgments or
-cached findings still needing location.
+is compiler-free. With `typeAware: true` or `--type-aware`, it starts the compiler
+only during execution, after confirmation, for pending judgments or cached
+findings still needing location.
 
 `--limit` now counts files, not rule checks; use the same flag without an extra
 unit selector. Each request-bearing file consumes one slot for all its pending
@@ -127,7 +129,7 @@ rule takes:
 `description`, `must`, `never`, and the rest. Its `appendState(state, file, Bun)`
 runs right before each request for the rule, and what it returns is spread
 over the request's state: `code`, the file's sections as Jev reads them,
-plus the shared context selected by the config's `reads`. Use it to give Jev what the file cannot show, such
+plus the shared context enabled by the config's `reads` and `typeAware`. Use it to give Jev what the file cannot show, such
 as a schema another file holds, and name the key it adds in the description.
 Nothing it returns is checked, so it can break its own rule. The rule gets
 requests of its own, repeating the shared context. Hook-owned external data
@@ -153,7 +155,8 @@ export default defineConfig({
   presets: ["typescript", "security"], // built-in rule sets, or topics such as "effect/basics"
   threshold: 0.8, // default 0.8
   sufficiencyThreshold: 0.6, // below it, a finding warns the file and shared context may not show enough
-  reads: ["workspacePackages", "symbols", "references"], // default; omitting this field keeps all three
+  reads: ["workspacePackages"], // default; [] omits workspace context
+  typeAware: false, // default; true or --type-aware enables both symbols and references
   exclude: ["**/generated/**"], // files no rule judges
   includeComments: false, // true only for rules about comments
   overrides: {
@@ -163,14 +166,16 @@ export default defineConfig({
 });
 ```
 
-Top-level `reads` selects shared context for every audited file and all its
-rules, including presets. `resolveConfig` defaults to
-`["workspacePackages", "symbols", "references"]` when the field is omitted,
-even without a config file. An explicit array replaces the default: `reads: []`
-is the code-only opt-out, and a subset limits context to those readers. Presets
-do not own or override this selection. Rule-level `reads`, in Markdown front
-matter, `defineRule`, or inline rules, is rejected with guidance to move it to
-the config. The available names are:
+Top-level `reads` chooses workspace context for every audited file and all its
+rules, including presets. It defaults to `["workspacePackages"]`, even without
+a config file; `reads: []` omits that map. `typeAware` defaults to `false`.
+Opting in with `typeAware: true` or `--type-aware` enables both `symbols` and
+`references`, regardless of `reads`. Legacy native-reader entries in `reads`
+alone do not enable the compiler; leaving them out does not disable it when
+type awareness is on. Code alone requires `reads: []` and type awareness off.
+Presets do not own or override this selection. Rule-level `reads`, in Markdown
+front matter, `defineRule`, or inline rules, is rejected with guidance to move
+it to the config. The context maps are:
 
 - `workspacePackages`: only packages matched by this file's literal imports,
   as `{ canonicalPackageName: directory }`. Subpaths match the owning package;
@@ -184,10 +189,14 @@ the config. The available names are:
   and narrowing types stay distinct; docs/tags appear once per canonical symbol
   per file. This is not literal IDE hover text: there are no IDE labels or
   selected-call overload presentation. Unused local declarations may have type
-  blocks too. Library types/docs can appear even when their source is excluded
-  from snippets.
-- `references`: `{ Name: { pathname: declarationSnippet } }` for used symbols'
-  canonical outgoing alias-target declarations. Each snippet is the smallest
+  blocks too. Standard-library and Node/Bun built-ins and their methods are
+  omitted; project and third-party symbols remain, including built-in-name
+  shadows. Built-in type names can still appear inside meaningful signatures.
+- `references`: a flat `Record<string, string>`, as
+  `{ "Name:path/to/file.ts": "declarationSnippet" }`, for declarations of symbols
+  used by the target code, not incoming call sites. Keys retain names as used,
+  including import aliases, and repository-relative pathname casing; alias targets
+  are resolved canonically. Each snippet is the smallest
   complete AST declaration scope, with no extra surrounding lines: full function
   bodies; whole arrow/object initializer variable statements, including
   `export const` and semicolons; whole methods/getters/setters, not their classes;
@@ -201,8 +210,10 @@ the config. The available names are:
   exclusions remain. There are no counts, incoming callers, structured locations,
   unresolved lists, full-file collection, or completeness metadata.
 
-Default npm-installed lint uses `symbols` and `references` with adhere's pinned
-native TypeScript compiler through the npm/Bun launcher. No root `tsconfig.json`
+When type awareness is enabled, npm-installed lint uses both `symbols` and
+`references` with adhere's pinned native TypeScript compiler through the npm/Bun
+launcher. Enabled context maps include a self-describing `__comment` in Jev's
+state; top-level guidance identifies only `code` as the audit target. No root `tsconfig.json`
 or root file-list membership is required. During execution, native TypeScript
 opens files with pending judgments or cached findings needing location and
 discovers each file's configured project, including package
@@ -243,27 +254,32 @@ program graphs can still consume substantial time/memory. Bounding active
 documents/snapshots does not make total memory or model payload size constant,
 and oversized contexts are still possible. Context is queried just
 before judge/locate and reused locally. Planning never calls `SourceReads`.
-Source checkouts use their development compiler dependency. Raw GitHub
-binaries still have no compiler resources: their lint requires explicit config
-`reads: []` or `reads: ["workspacePackages"]` for execution; use the package
-launcher for the full default. Plan-only `--limit 0` needs no compiler or API key.
+Type-aware source checkouts use their development compiler dependency. Raw
+GitHub binaries have no compiler resources, but run the default compiler-free
+audit with workspace context without special configuration. Use `reads: []`
+for code alone, with type awareness off; use the package launcher or a checkout
+for type-aware execution. Plan-only `--limit 0` needs no compiler or API key.
 
 Rules without `appendState` share requests and pay for shared input context
 once per request, not once per rule. Context repeats on request splitting,
 locating findings, and hook requests. Compiler documentation and complete declaration
-scopes add default token/privacy cost, including source from files not judged.
+scopes add token/privacy cost only when type awareness is enabled, including
+source from files not judged.
 Complete scopes may contain substantially more source/tokens than fixed-line
 excerpts; function bodies are not peeked or capped to seven lines.
 Compiler-provided docs and JSDoc tags can remain present with ordinary comments
-stripped. Omit `symbols` to disable type/docs context, `references` to disable
-snippets, or use `reads: []` for code-only built-in context.
+stripped. Keep `typeAware` off to omit both native maps; `reads` controls only
+workspace context. Use `reads: []` with type awareness off for code alone.
 Plan token/cost estimates include code and cheap workspace metadata only, not
 native context or hook-added data. Actual cost and request splits may therefore
 be higher. Shared state plus any one question must fit 32k tokens, and state
 plus all questions in a request must fit 64k, with 1k reserved for overhead.
-Execution splits question batches, checks full budgets before HTTP, and skips
-oversized files instead of silently truncating type/docs strings or complete scopes. Only
-`appendState` forces a private rule request group.
+Execution splits question batches and checks full budgets before HTTP. On
+context overflow, it retries once without `references` when that map is present,
+keeping target code and `symbols` intact; a further overflow skips the file.
+Complete declaration scopes are not shortened to fit. Symbol strings have
+configurable `maxSymbolLength` and `maxSymbolDocumentationLength` limits, both
+256 by default. Only `appendState` forces a private rule request group.
 
 `overrides` changes any rule by the id the report shows, a preset's with the
 preset first, without copying it; an id no rule has refuses the run. `rules`
@@ -330,8 +346,8 @@ re-judges that rule; a threshold change re-judges nothing.
 
 Dependencies, related source, reader selection, shared read-context contents,
 and hook-owned external data are deliberately not fingerprinted. If `A.ts` imports
-`B.ts`, changing `B.ts` does not invalidate `A.ts`. Changing config `reads` does
-not refresh its cached answers either. This keeps planning cheap but accepts
+`B.ts`, changing `B.ts` does not invalidate `A.ts`. Changing config `reads` or
+`typeAware` does not refresh its cached answers either. This keeps planning cheap but accepts
 stale dependency/context judgments.
 
 `planAudit` reads/counts/hashes code, checks the cache, and makes code plus cheap
@@ -344,8 +360,8 @@ budgeting, native reads, and HTTP execution.
 Source reload/hash work is bounded to 8 files; plans retain compact metadata and
 estimates, not all file contents. Only sampled-linter files need a planning
 reread. After confirmation, execution reloads request-bearing files and cached
-finding excerpts, preparing full native context only for pending or
-cached-unlocated files just before judge/locate. Every reload validates normalized
+finding excerpts, preparing native context only when type awareness is enabled,
+for pending or cached-unlocated files just before judge/locate. Every reload validates normalized
 code and ignore directives against the active plan; changes refuse with rerun
 guidance, without adding persistent-cache keys. A fully cached and located run
 starts no compiler and needs no API key or Jev requests.
@@ -390,7 +406,8 @@ the file breaks the rule. On a terminal it is amber near its rule's
 threshold, within a quarter of the room above it (0.80 to 0.84 at a threshold
 of 0.80), and green above that: a rule whose findings are mostly amber turns
 on where its threshold sits. `context` is its probability that the file and
-shared context show enough to decide; all three readers are included by default.
+shared context show enough to decide. Default context is `workspacePackages`;
+`symbols` and `references` require `typeAware: true` or `--type-aware`.
 It is colored the same way around the sufficiency threshold, 0.6
 by default: amber from 0.50 to 0.69, red below. Below 0.6 the finding also
 carries `warning: this file may not show enough to check this rule`. It turns

package/skills/adhere-setup/SKILL.md

@@ -37,23 +37,30 @@ wherever this skill says `adhere`, run it the manager's way, as in
 
 With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
 
-Default lint enables `workspacePackages`, `symbols`, and `references`, and
-starts native TypeScript only during execution, after confirmation, when
-pending judgments or cached findings needing location require context. It discovers each
-file's configured project, including package projects under solution roots,
-and falls back to inferred context for unconfigured or excluded files. No root
-`tsconfig.json` or literal root file-list membership is required; do not block
-setup on either. `.adhere/tsconfig.json` only types the config and rules.
-Planning, `--limit 0`, version, help, skills, and validate do not start the
-compiler.
+Default lint reads code and `workspacePackages` without starting a compiler.
+`typeAware` defaults to `false`; `typeAware: true` or `--type-aware` opts into
+both `symbols` and `references`, regardless of `reads`. `reads` now controls
+workspace context only, defaulting to `["workspacePackages"]`; legacy native
+reader entries alone do not opt in. Code alone uses `reads: []` with type
+awareness off. Explain the extra context/cost and **Ask** before opting in.
+
+With type awareness enabled, native TypeScript starts only during execution,
+after confirmation, when pending judgments or cached findings needing location
+require context. It discovers each file's configured project, including package
+projects under solution roots, and falls back to inferred context for
+unconfigured or excluded files. No root `tsconfig.json` or literal root file-list
+membership is required; do not block setup on either. `.adhere/tsconfig.json`
+only types the config and rules. Planning, `--limit 0`, version, help, skills,
+and validate do not start the compiler.
 
 In a repo without a `package.json`, inspect any `adhere` on PATH with
 `adhere --version`, then **Ask** whether to use the npm/Bun package launcher
-for the full default or a raw executable with deliberately reduced context.
-The raw release (`adhere-Windows-x86_64.exe` on Windows) needs no Node or
-package manager, but its lint requires explicit config `reads: []` or
-`reads: ["workspacePackages"]`. Do not silently disable readers to make it
-work. Only fetch it after the user chooses that alternative:
+or a raw executable for the same default compiler-free audit. The raw release
+(`adhere-Windows-x86_64.exe` on Windows) needs no Node or package manager and
+runs with workspace context without special configuration. It cannot run a
+type-aware audit: use the package launcher or a checkout if the user opts in.
+Do not silently turn off an explicitly chosen `typeAware` setting. Only fetch
+the raw release after the user chooses that alternative:
 
 ```sh
 curl -fsSL --create-dirs -o ~/.local/bin/adhere \
@@ -139,10 +146,11 @@ the wording of any. Revise drafts the user wants changed and show them again.
 - Copy each chosen draft to `.adhere/rules/<topic>/<slug>/RULE.md`.
 - Add chosen presets, or topics, to `presets` in `.adhere/config.ts`. Presets
   use the audit-wide readers; they do not own or override `reads`.
-- Leave `reads` omitted for the full default. Do not add `reads: []` to the
-  normal setup recommendation or as a workaround for missing compiler
-  resources. Only set an explicit replacement array if the user chooses to
-  disable or limit readers.
+- Leave `reads` omitted for default workspace context and `typeAware` off
+  unless the user explicitly chooses type-aware execution. `reads: []` omits
+  workspace context, not native maps. Only replace `reads` if the user chooses
+  to limit workspace context. If requested type awareness lacks compiler resources,
+  use the package launcher or a checkout; do not silently turn it off.
 - Install chosen shared rules: `adhere install org/repo/<id>` for each, or
   `adhere install org/repo` for all of them. They land in `.adhere/rules/org/repo/`.
 - Add `exclude` globs for generated or vendored code the default skips miss.
@@ -177,19 +185,21 @@ cost, and request splits may be higher. Source reload/hash work is bounded to
 for execution; if normalized code or ignore
 directives changed since planning, rerun rather than using the old plan.
 
-Tell the user that compiler type/docs strings and outgoing declaration snippets add
-source/documentation sharing and token cost by default, including complete
-scopes from files outside the audit filter. Whole declaration bodies can use more
-tokens than fixed-line excerpts; budget overflow skips the file instead of
-capping bodies to seven lines or silently truncating them. Compiler-provided
-documentation and JSDoc tags can remain even when ordinary code comments are
-stripped; omitting `symbols` disables type/docs context and omitting
-`references` disables snippets. The global workspace catalog is not sent: only
-this file's matched literal imports appear under canonical package keys.
-Offer an explicit reader subset or code-only opt-out if they want less context;
-never apply one silently. Neither reader selection nor dependency/shared-context
-changes invalidate cached judgments. If they want fresh answers under changed
-context, **Ask** before clearing `.adhere/cache/`; do not clear it automatically.
+If the user opts into type awareness, explain that both compiler type/docs
+strings and outgoing declaration snippets add source/documentation sharing and
+token cost, including complete scopes from files outside the audit filter.
+Whole declaration bodies can use more tokens than fixed-line excerpts. Context
+overflow gets one retry without `references`, keeping target code and `symbols`
+intact; it can still overflow and skip the file. Declaration bodies are not
+shortened to fit. Compiler documentation and JSDoc tags can remain even when
+ordinary code comments are stripped, subject to the configured symbol limits.
+The global workspace catalog is not sent: only this file's matched literal
+imports appear under canonical package keys.
+Offer type awareness only as an explicit opt-in, or `reads: []` with type
+awareness off for code alone; never apply either silently. Neither `reads`,
+`typeAware`, nor dependency/shared-context changes invalidate cached judgments.
+If they want fresh answers under changed context, **Ask** before clearing
+`.adhere/cache/`; do not clear it automatically.
 
 On a large repo, offer a subtree such as `--filter 'src/**'`, or a file cap
 such as `--limit 100`: the first 100 files needing requests in path order, with
@@ -201,7 +211,9 @@ or HTTP-size skips after selection consume a slot without runtime refill.
 
 Explain that a file cap is not an HTTP-request or token/cost cap: each file can
 produce judge, locate, split-batch, and private hook requests. **Ask** before
-sending, then run the command below with only the user's chosen filter/file cap:
+sending, then run the command below with only the user's chosen filter/file cap
+and `--type-aware` if they explicitly opted in, or retain `typeAware: true` in
+their config:
 
 ```sh
 adhere lint --yes
@@ -209,11 +221,14 @@ adhere lint --yes
 
 `SourceReads.prepare(paths)` registers eligible-path metadata only, with no
 file I/O, compiler/SDK import, spawn, snapshot, or semantic query, even for a large list.
-Only after confirmation do pending judgments or cached findings still needing
-location trigger actual per-file native reads just before judge/locate. Native
+Only with type awareness enabled, and after confirmation, do pending judgments
+or cached findings still needing location trigger actual per-file native reads
+just before judge/locate. Native
 transactions are serial through one permit; HTTP execution remains concurrent
 at 8. Returned context is reused locally and full budgets are enforced before
-HTTP, with oversized files skipped and no silent truncation. Shared state plus
+HTTP. Oversized context gets one retry without references when present, then
+skips the file if it still does not fit; code and declaration bodies are not
+shortened to fit. Shared state plus
 one question must fit 32k tokens and state plus all questions must fit 64k per
 request, with 1k reserved for overhead. The SDK may still parse a full selected
 project, and additional monorepo programs may increase startup time and memory.
@@ -223,9 +238,13 @@ blocks for same-name binding/narrowing contexts, with compiler documentation
 and JSDoc tags once per canonical symbol per file. It does not promise literal
 IDE labels or selected-call overload presentation. Symbol/type queries are
 batched, and independent SDK requests are chunked to at most 8 within the single
-active native document/snapshot; HTTP work remains concurrent at 8. `references` maps used names to canonical outgoing declarations
-by pathname, selecting the smallest complete AST scope without extra surrounding
-lines. Functions include full bodies; arrow/object initializer variables include
+active native document/snapshot; HTTP work remains concurrent at 8. Standard-library
+and Node/Bun built-ins are omitted, but project and third-party names remain.
+`references` is a flat `Record<string, string>` keyed by
+`symbol:repository-relative pathname`, retaining import alias names and original
+pathname casing. Values are declarations of symbols used by the target code,
+not incoming call sites, selecting the smallest complete AST scope without extra
+surrounding lines. Functions include full bodies; arrow/object initializer variables include
 whole variable statements with `export const` and semicolons. Methods, getters,
 and setters include their whole member, not the entire class; classes,
 interfaces, and type aliases include the whole declaration. Repeated/overlapping
@@ -235,7 +254,10 @@ not automatically expanded. Scopes preserve indentation and the comment/directiv
 policy, including associated JSDoc when `includeComments` is true; compiler
 docs/tags in `symbols` remain available regardless. Current-file, declaration-file, `node_modules`, and
 outside-root exclusions are unchanged. There are no incoming callers, counts, structured locations,
-unresolved lists, full-file collection, or completeness markers.
+unresolved lists, full-file collection, or completeness markers. Enabled context
+maps include a self-describing `__comment`; top-level guidance identifies only
+`code` as the audit target. Both native maps require the same type-awareness
+opt-in; `reads` cannot select or disable them individually.
 
 The first actual read lazily starts one native TypeScript LSP process with its
 public SDK API pipe; both are pinned to exactly `7.1.0-dev.20261009.1` and must
@@ -332,15 +354,16 @@ jobs:
 Pin the versions the repo already uses: bun's `bun-version`, Node's
 `node-version` from `.nvmrc` or `engines`, and pnpm's from `packageManager`,
 which `pnpm/action-setup` reads. Keep optional dependencies enabled so adhere's
-platform package and its compiler dependency are installed. Existing project
-configs and dependencies supply configured context when available; files with
-no configured project or excluded from one use inferred context. Do not require
-or generate a root `tsconfig.json` merely to make default lint run. In a repo
-without a `package.json`, use the package launcher for the full default.
-Only skip setup/install and fetch the raw executable if the user explicitly
-chose and committed `reads: []` or `reads: ["workspacePackages"]` locally.
-That is a reduced-context alternative, not an equivalent default installation.
-Fetch the executable at the version the user ran:
+platform package and its compiler dependency are installed. For type-aware audits,
+existing project configs and dependencies supply configured context when available;
+files with no configured project or excluded from one use inferred context. Do not
+require or generate a root `tsconfig.json` merely to make default lint run. Both
+package launchers and raw executables support the default compiler-free audit,
+including in repos without a `package.json`; no `reads` override is required.
+If the user explicitly chose type-aware execution, use the package launcher or a
+checkout; do not silently turn it off. For the default compiler-free audit, you can
+instead skip runtime setup/install and fetch the raw executable at the version
+the user ran:
 
 ```yaml
 - run: |

package/src/cli.ts

@@ -59,6 +59,10 @@ import skill from "../skills/adhere/SKILL.md" with { type: "text" };
 import fixSkill from "../skills/adhere-fix/SKILL.md" with { type: "text" };
 import setupSkill from "../skills/adhere-setup/SKILL.md" with { type: "text" };
 
+// @adhere This file owns CLI flags, progress output, and command wiring. Audit execution,
+// scaffolding, rule installation, credential storage, and rule checks are implemented in
+// their own modules imported above; the commands here connect them to the CLI.
+
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
 }) {
@@ -114,6 +118,13 @@ const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
   ),
 );
 
+const typeAware = Flag.Boolean("type-aware").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Include compiler-resolved symbols and declaration excerpts. Off by default.",
+  ),
+);
+
 const limit = Flag.Int("limit").pipe(
   Flag.filter(
     (files) => files >= 0,
@@ -235,7 +246,7 @@ export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
+  { preset, threshold, sufficiencyThreshold, typeAware, yes, limit, rpm, filter, denyWarnings },
   (input) =>
     Effect.gen(function* () {
       const stdio = yield* Stdio.Stdio;
@@ -298,6 +309,7 @@ export const lintCommand = Command.make(
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
         sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
+        typeAware: Option.getOrUndefined(input.typeAware),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,

package/src/config.ts

@@ -220,8 +220,10 @@ export const AdhereConfig = Schema.Struct({
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
-  /** Shared context for every audited file and all its rules. Unset: all built-in reads; []: code only. */
+  /** Workspace context shared by every rule. Defaults to workspacePackages; [] disables it. Native read names do not enable type awareness. */
   reads: Schema.optionalKey(Reads),
+  /** Include both compiler-resolved symbols and declaration excerpts. Defaults to false. */
+  typeAware: Schema.optionalKey(Schema.Boolean),
   /** Maximum characters of each symbol's complete resolved content. Defaults to 256. */
   maxSymbolLength: Schema.optionalKey(Schema.Natural),
   /** Maximum characters of documentation and JSDoc tags per symbol. Defaults to 256; 0 omits them. */
@@ -333,7 +335,7 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
 export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
-export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages", "symbols", "references"];
+export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages"];
 export const DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH = 256;
 export const DEFAULT_MAX_SYMBOL_LENGTH = 256;
 
@@ -355,6 +357,8 @@ export interface ResolvedConfig {
   readonly includeComments?: boolean;
   /** Built-in context shared by every rule, with the default applied. */
   readonly reads: typeof Reads.Type;
+  /** Whether both native symbol and declaration context are enabled. */
+  readonly typeAware: boolean;
   /** Maximum characters of each symbol's complete resolved content. */
   readonly maxSymbolLength: number;
   /** Maximum characters of documentation and JSDoc tags before the complete symbol limit applies. */
@@ -376,6 +380,8 @@ export interface Flags {
   readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
   readonly rpm?: number | undefined;
+  /** Replaces the config's native-context opt-in. */
+  readonly typeAware?: boolean | undefined;
 }
 
 /**
@@ -410,6 +416,7 @@ export const resolveConfig = (
   });
   const last = <K extends "model" | "threshold">(key: K) =>
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
+  const typeAware = flags.typeAware ?? config.typeAware ?? false;
   return {
     model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
     ...(config.provider === undefined ? {} : { provider: config.provider }),
@@ -420,7 +427,11 @@ export const resolveConfig = (
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
     ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
-    reads: config.reads ?? DEFAULT_READS,
+    typeAware,
+    reads: [
+      ...(config.reads ?? DEFAULT_READS).filter((read) => read === "workspacePackages"),
+      ...(typeAware ? (["symbols", "references"] as const) : []),
+    ],
     maxSymbolLength: config.maxSymbolLength ?? DEFAULT_MAX_SYMBOL_LENGTH,
     maxSymbolDocumentationLength:
       config.maxSymbolDocumentationLength ?? DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,

package/src/init.ts

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { CONFIG_FILES } from "#config.ts";
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 
 export interface InitResult {
   readonly created: ReadonlyArray<string>;
@@ -305,6 +305,13 @@ const writeScaffoldFile = (root: string, path: string, contents: string, options
 
 const PACKAGE = "@drkmttr/adhere";
 
+const PackageManifest = Schema.fromJsonString(
+  Schema.Struct({
+    dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+    devDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  }),
+);
+
 type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
 
 /** The first lockfile at the root names the package manager; npm when there is none. */
@@ -342,9 +349,21 @@ const addFlags: Record<PackageManager, ReadonlyArray<string>> = {
 const installPackages = (root: string, shared: boolean) =>
   Effect.tryPromise({
     try: async (): Promise<Install> => {
-      const manifest = await readFile(join(root, "package.json"), "utf8").catch(() => undefined);
+      const manifest = await readFile(join(root, "package.json"), "utf8").catch(
+        (cause: unknown) => {
+          if (
+            typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT"
+          ) {
+            return undefined;
+          }
+          throw cause;
+        },
+      );
       if (manifest === undefined) return { status: "no-package-json" };
-      const { dependencies, devDependencies } = JSON.parse(manifest);
+      const { dependencies, devDependencies } = Schema.decodeUnknownSync(PackageManifest)(manifest);
       if (
         !shared &&
         (dependencies?.[PACKAGE] !== undefined || devDependencies?.[PACKAGE] !== undefined)

package/src/install.ts

@@ -37,30 +37,35 @@ const failed = (what: string) => (cause: unknown) =>
 const cloned = (source: Source) =>
   Effect.acquireRelease(
     Effect.tryPromise({
-      try: async () => {
-        const directory = await mkdtemp(join(tmpdir(), "adhere-install-"));
-        const branch = source.ref === undefined ? [] : ["--branch", source.ref];
-        const url = `https://github.com/${source.repo}.git`;
-        await new Promise<void>((resolve, reject) => {
-          let stderr = "";
-          spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
-            stdio: ["inherit", "ignore", "pipe"],
-          })
-            .on("error", reject)
-            .on("exit", (code) =>
-              code === 0
-                ? resolve()
-                : reject(new Error(stderr.trim() || `git exited with ${code}`)),
-            )
-            .stderr?.on("data", (chunk) => {
-              stderr += chunk;
-            });
-        });
-        return directory;
-      },
-      catch: failed(`Could not clone ${source.repo}`),
+      try: () => mkdtemp(join(tmpdir(), "adhere-install-")),
+      catch: failed(`Could not create a temporary directory for ${source.repo}`),
     }),
     (directory) => Effect.promise(() => rm(directory, { recursive: true, force: true })),
+  ).pipe(
+    Effect.tap((directory) =>
+      Effect.tryPromise({
+        try: async () => {
+          const branch = source.ref === undefined ? [] : ["--branch", source.ref];
+          const url = `https://github.com/${source.repo}.git`;
+          await new Promise<void>((resolve, reject) => {
+            let stderr = "";
+            spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
+              stdio: ["inherit", "ignore", "pipe"],
+            })
+              .on("error", reject)
+              .on("exit", (code) =>
+                code === 0
+                  ? resolve()
+                  : reject(new Error(stderr.trim() || `git exited with ${code}`)),
+              )
+              .stderr?.on("data", (chunk) => {
+                stderr += chunk;
+              });
+          });
+        },
+        catch: failed(`Could not clone ${source.repo}`),
+      }),
+    ),
   );
 
 /**
@@ -103,7 +108,8 @@ export const listRules = (source: Source) =>
       const rules = yield* rulesIn(source, yield* cloned(source));
       return yield* Effect.forEach(rules, ({ id, name, directory }) =>
         Effect.gen(function* () {
-          if (name === "RULE.ts") return { id, description: "(TypeScript, which list does not run)" };
+          if (name === "RULE.ts")
+            return { id, description: "(TypeScript, which list does not run)" };
           const text = yield* Effect.tryPromise({
             try: () => readFile(join(directory, name), "utf8"),
             catch: failed(`Could not read ${id}`),

package/src/services/Jev.reads.test.ts

@@ -76,6 +76,7 @@ const recordedJev = (
     Layer.provide([
       Layer.succeed(FetchHttpClient.Fetch, fetch),
       Layer.succeed(AdhereConfig, {
+        typeAware: false,
         model: "jev-latest",
         threshold: 0.8,
         sufficiencyThreshold: 0.6,
@@ -493,9 +494,10 @@ describe("prepared shared Jev reads", () => {
     expect(readState.code).toEqual({});
   });
 
-  it("does not prepare context in HTTP even with resolved default reads and omitted or partial shared state", async () => {
+  it("uses only caller-prepared context in HTTP with workspace-only defaults", async () => {
     const config = resolveConfig({ presets: [], rules: { plain } });
-    expect(config.reads).toEqual(["workspacePackages", "symbols", "references"]);
+    expect(config.reads).toEqual(["workspacePackages"]);
+    expect(config.typeAware).toBe(false);
     const { sent, layer } = recordedJev({ unused: "packages/unused" }, config.reads);
     await Effect.runPromise(
       Effect.gen(function* () {

package/src/services/Jev.ts

@@ -141,7 +141,7 @@ export const tokensOf = (value: unknown): number => Math.ceil(bytesOf(value) / 3
 
 const READ_COMMENTS: Readonly<Record<string, string>> = {
   symbols:
-    "Compiler-inferred types, documentation, and JSDoc for symbols in `code`; keys are symbol names.",
+    "Compiler-rendered types and documentation for symbols used in `code`; keys are symbol names. A declared type, assertion, or type predicate is only a compile-time claim, not proof of runtime validation. When `references` show an implementation, inspect its actual checks. A predicate that returns true, tests only truthiness, or checks only whether a value is an object does not validate the fields it claims.",
   references:
     "Declarations of symbols used in `code`. Each key is `symbol:pathname`: the symbol name as used in `code` followed by its repository-relative declaration path. Each value is a complete declaration excerpt.",
   workspacePackages:

package/src/workflows/audit.ts

@@ -387,8 +387,8 @@ export const planAudit = (
       ? (config.workspacePackages ?? {})
       : undefined;
     const nativeReads: SourceReadRequest = {
-      symbols: config.reads.includes("symbols"),
-      references: config.reads.includes("references"),
+      symbols: config.typeAware,
+      references: config.typeAware,
       includeComments: config.includeComments === true,
       maxSymbolLength: config.maxSymbolLength,
       maxSymbolDocumentationLength: config.maxSymbolDocumentationLength,