@drkmttr/adhere 0.18.0 → 0.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.18.0",
+  "version": "0.21.2",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -38,32 +38,32 @@
     "prepare": "vp config"
   },
   "dependencies": {
-    "effect": "4.0.0-rc.118"
+    "effect": "4.0.3"
   },
   "devDependencies": {
-    "@effect/platform-bun": "4.0.0-rc.118",
+    "@effect/platform-bun": "4.0.3",
     "@types/bun": "^1.4.2",
-    "@types/node": "^24.13.6",
+    "@types/node": "^26.0.0",
     "release-it": "^21.1.0",
-    "typescript": "7.1.0-dev.20261009.1",
+    "typescript": "7.1.0-dev.20261012.1",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
     "vite-plus": "1.1.0",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "overrides": {
-    "@effect/platform-node-shared": "4.0.0-rc.118",
+    "@effect/platform-node-shared": "4.0.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vitest": "5.0.3"
+    "vitest": "5.0.5"
   },
   "devEngines": {
     "packageManager": {
       "name": "bun",
-      "version": "1.4.2",
+      "version": "1.4.3",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.21.0",
+      "version": "26.11.1",
       "onFail": "download"
     }
   },
@@ -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.21.2",
+    "@drkmttr/adhere-darwin-x64": "0.21.2",
+    "@drkmttr/adhere-linux-arm64": "0.21.2",
+    "@drkmttr/adhere-linux-x64": "0.21.2",
+    "@drkmttr/adhere-win32-x64": "0.21.2"
   }
 }

package/presets/README.md

@@ -0,0 +1,132 @@
+# Presets
+
+Every rule in adhere's built-in presets is listed below, with a one-line
+summary. Each id links to the full rule, and is the id that reports,
+`overrides`, and `adhere-ignore` comments use. [Presets](../README.md#presets)
+says how to name a preset or one of its topics.
+
+## typescript
+
+- **Source.** The TypeScript Handbook and the Google TypeScript Style Guide.
+- **Checked by a linter instead.** The preset has no rules for these, since
+  typescript-eslint and ESLint check them exactly: unhandled promises
+  (`no-floating-promises`), throwing non-errors (`only-throw-error`), `any`
+  (`no-explicit-any`), exhaustive switches (`switch-exhaustiveness-check`), a
+  lost `cause` (`preserve-caught-error`), and empty catch blocks (`no-empty`).
+
+- [`typescript/async/concurrent-independent-work`](./typescript/async/concurrent-independent-work/RULE.md): Independent awaited calls run concurrently, not one after another.
+- [`typescript/async/network-calls-have-timeouts`](./typescript/async/network-calls-have-timeouts/RULE.md): HTTP requests carry a timeout or an abort signal.
+- [`typescript/design/no-argument-mutation`](./typescript/design/no-argument-mutation/RULE.md): Functions return changed copies instead of mutating arguments.
+- [`typescript/errors/no-swallowed-errors`](./typescript/errors/no-swallowed-errors/RULE.md): Caught errors are handled, rethrown, or returned as failures.
+- [`typescript/errors/release-on-every-path`](./typescript/errors/release-on-every-path/RULE.md): Acquired resources are released on every path, including errors.
+- [`typescript/testing/assert-outcomes`](./typescript/testing/assert-outcomes/RULE.md): Tests assert results and effects, not only that code ran.
+- [`typescript/testing/independent-tests`](./typescript/testing/independent-tests/RULE.md): Each test sets up its own state and relies on no other test.
+- [`typescript/types/assertions-only-when-proven`](./typescript/types/assertions-only-when-proven/RULE.md): Type assertions claim only what surrounding code has proven.
+- [`typescript/types/derive-dont-restate`](./typescript/types/derive-dont-restate/RULE.md): Types are derived from their source instead of restated by hand.
+- [`typescript/types/unrepresentable-invalid-states`](./typescript/types/unrepresentable-invalid-states/RULE.md): Types make invalid field combinations unrepresentable.
+- [`typescript/types/validate-external-data`](./typescript/types/validate-external-data/RULE.md): Data from outside is checked at runtime before use.
+
+## react
+
+- **Source.** react.dev, mostly
+  [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
+  and
+  [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure).
+- **Checked by a linter instead.** The preset has no rules for these, since
+  the React Compiler's lint rules check them, in
+  [eslint-plugin-react-hooks](https://react.dev/reference/eslint-plugin-react-hooks)'s
+  recommended set and in Oxlint: pure render (`purity`), props and state
+  never mutated (`immutability`), refs not read during render (`refs`), no
+  `setState` in render or synchronously in an effect (`set-state-in-render`,
+  `set-state-in-effect`), which covers state derived in an effect, and no
+  component defined inside another (`static-components`).
+
+- [`react/effects/clean-up-what-they-start`](./react/effects/clean-up-what-they-start/RULE.md): Effects return cleanup that undoes what they started.
+- [`react/effects/event-logic-in-handlers`](./react/effects/event-logic-in-handlers/RULE.md): Code responding to a user action runs in its event handler.
+- [`react/effects/external-stores-use-sync-external-store`](./react/effects/external-stores-use-sync-external-store/RULE.md): External stores are read with `useSyncExternalStore`.
+- [`react/effects/fetches-ignore-stale-responses`](./react/effects/fetches-ignore-stale-responses/RULE.md): Effects that fetch ignore or abort stale responses.
+- [`react/effects/notify-parents-in-handlers`](./react/effects/notify-parents-in-handlers/RULE.md): Parents are notified in the handler that makes the change.
+- [`react/server/no-private-data-to-client`](./react/server/no-private-data-to-client/RULE.md): Client Components receive only the fields they show.
+- [`react/server/server-functions-authorize-and-validate`](./react/server/server-functions-authorize-and-validate/RULE.md): Server Functions authorize callers and validate arguments.
+- [`react/state/no-contradictory-state`](./react/state/no-contradictory-state/RULE.md): One status value replaces booleans that can contradict.
+- [`react/state/no-props-copied-into-state`](./react/state/no-props-copied-into-state/RULE.md): Props are read during render, not copied into state.
+- [`react/state/store-ids-not-copies`](./react/state/store-ids-not-copies/RULE.md): State holds a selected item's id, not a copy of the item.
+
+## security
+
+- **Source.** OWASP's cheat sheets.
+
+- [`security/constant-time-secret-compare`](./security/constant-time-secret-compare/RULE.md): Received secrets are compared in constant time.
+- [`security/no-secrets-in-output`](./security/no-secrets-in-output/RULE.md): Secrets stay out of logs, errors, and HTTP responses.
+- [`security/no-untrusted-input-in-commands-or-paths`](./security/no-untrusted-input-in-commands-or-paths/RULE.md): Untrusted input stays out of command strings and unchecked paths.
+- [`security/parameterized-queries`](./security/parameterized-queries/RULE.md): SQL values from outside are passed as bound parameters.
+
+## effect
+
+- **Source.** The
+  [effect-solutions](https://github.com/kitlangton/effect-solutions) docs and
+  the [effect/platform](https://effect.website/docs/platform/introduction/)
+  docs.
+
+- [`effect/basics/gen-for-sequencing`](./effect/basics/gen-for-sequencing/RULE.md): Sequential effectful steps use `Effect.gen` and `yield*`.
+- [`effect/basics/instrument-with-pipe`](./effect/basics/instrument-with-pipe/RULE.md): Timeouts, retries, logging, and spans attach with `.pipe`.
+- [`effect/config/business-logic-depends-on-config-service`](./effect/config/business-logic-depends-on-config-service/RULE.md): Business logic depends on a config service, not Config reads.
+- [`effect/config/secrets-are-redacted`](./effect/config/secrets-are-redacted/RULE.md): Tokens, passwords, and keys are read with `Config.Redacted`.
+- [`effect/config/tests-provide-values-directly`](./effect/config/tests-provide-values-directly/RULE.md): Tests supply config with `Layer.succeed` on the config service.
+- [`effect/config/validate-with-schema`](./effect/config/validate-with-schema/RULE.md): Constrained config values are validated as they are read.
+- [`effect/data/brand-meaningful-primitives`](./effect/data/brand-meaningful-primitives/RULE.md): Meaningful primitives in domain types are branded schemas.
+- [`effect/data/variants-are-tagged-unions`](./effect/data/variants-are-tagged-unions/RULE.md): Domain variants are tagged schemas in a union.
+- [`effect/errors/catch-defects-at-boundaries-only`](./effect/errors/catch-defects-at-boundaries-only/RULE.md): Defects are caught only at system boundaries.
+- [`effect/errors/defects-for-bugs`](./effect/errors/defects-for-bugs/RULE.md): Bugs and invariant violations are defects, not typed errors.
+- [`effect/errors/wrap-external-errors`](./effect/errors/wrap-external-errors/RULE.md): External errors are wrapped in tagged errors.
+- [`effect/services/dependencies-through-layers`](./effect/services/dependencies-through-layers/RULE.md): Service dependencies are yielded inside the service's Layer.
+- [`effect/services/fresh-layer-per-test`](./effect/services/fresh-layer-per-test/RULE.md): Each `it.effect` test provides its own layer.
+- [`effect/services/memoize-parameterized-layers`](./effect/services/memoize-parameterized-layers/RULE.md): Parameterized layers are built once and stored in a constant.
+- [`effect/services/no-mutable-state`](./effect/services/no-mutable-state/RULE.md): Service interfaces expose only readonly members.
+- [`effect/testing/test-clock-for-time`](./effect/testing/test-clock-for-time/RULE.md): Tests that depend on time use `TestClock`.
+
+## alchemy
+
+- **Source.** alchemy's docs and blog.
+
+- [`alchemy/apis/match-remote-errors-by-tag`](./alchemy/apis/match-remote-errors-by-tag/RULE.md): Remote errors are matched by tag and data, not `instanceof`.
+- [`alchemy/apis/schemas-at-trust-boundaries`](./alchemy/apis/schemas-at-trust-boundaries/RULE.md): Outside input is schema-validated at trust boundaries.
+- [`alchemy/data/commit-migrations-then-deploy`](./alchemy/data/commit-migrations-then-deploy/RULE.md): Migrations are committed ahead of time and applied as committed.
+- [`alchemy/data/hyperdrive-direct-origin`](./alchemy/data/hyperdrive-direct-origin/RULE.md): Hyperdrive points at the database's direct endpoint.
+- [`alchemy/data/migrations-use-direct-url`](./alchemy/data/migrations-use-direct-url/RULE.md): Migration runners connect with the database's direct URL.
+- [`alchemy/data/never-disable-tls-verification`](./alchemy/data/never-disable-tls-verification/RULE.md): Database connections verify the server's TLS certificate.
+- [`alchemy/data/private-endpoint-at-runtime`](./alchemy/data/private-endpoint-at-runtime/RULE.md): Service code reaches its database through the private binding.
+- [`alchemy/data/single-migration-owner`](./alchemy/data/single-migration-owner/RULE.md): Each database has exactly one migration owner.
+- [`alchemy/durable/idempotent-event-handlers`](./alchemy/durable/idempotent-event-handlers/RULE.md): Handlers for at-least-once events are idempotent.
+- [`alchemy/durable/io-inside-steps`](./alchemy/durable/io-inside-steps/RULE.md): Workflow I/O runs inside steps; replayed code stays deterministic.
+- [`alchemy/durable/no-self-triggering-bucket-writes`](./alchemy/durable/no-self-triggering-bucket-writes/RULE.md): Bucket handlers filter out events from their own writes.
+- [`alchemy/durable/stable-step-names`](./alchemy/durable/stable-step-names/RULE.md): Workflow step names stay stable across replays.
+- [`alchemy/durable/webhook-state-is-truth`](./alchemy/durable/webhook-state-is-truth/RULE.md): Paid access depends on webhook-recorded state, not success URLs.
+- [`alchemy/providers/diff-guards-unresolved-props`](./alchemy/providers/diff-guards-unresolved-props/RULE.md): Provider diffs guard unresolved props with `isResolved`.
+- [`alchemy/providers/idempotent-delete`](./alchemy/providers/idempotent-delete/RULE.md): Provider delete treats an already-gone resource as success.
+- [`alchemy/providers/lazy-layer-construction`](./alchemy/providers/lazy-layer-construction/RULE.md): Provider layers defer credentials and connections until use.
+- [`alchemy/providers/reconcile-from-observed-state`](./alchemy/providers/reconcile-from-observed-state/RULE.md): Provider reconcile converges from the resource's live state.
+- [`alchemy/resources/anchor-paths-with-import-meta`](./alchemy/resources/anchor-paths-with-import-meta/RULE.md): Path props of resources declared outside the run directory use `import.meta`.
+- [`alchemy/resources/idempotent-actions-and-seeds`](./alchemy/resources/idempotent-actions-and-seeds/RULE.md): Actions and seed files are safe to run again.
+- [`alchemy/resources/previews-reference-shared-resources`](./alchemy/resources/previews-reference-shared-resources/RULE.md): Preview stages reference shared resources and add cheap pieces.
+- [`alchemy/resources/protect-irreplaceable-data`](./alchemy/resources/protect-irreplaceable-data/RULE.md): Buckets and databases with irreplaceable data are retained.
+- [`alchemy/resources/remote-state-for-ci`](./alchemy/resources/remote-state-for-ci/RULE.md): CI and multi-machine stacks use a shared state store.
+- [`alchemy/resources/stable-logical-ids`](./alchemy/resources/stable-logical-ids/RULE.md): Resource logical ids stay the same across deploys.
+- [`alchemy/resources/stage-unique-physical-names`](./alchemy/resources/stage-unique-physical-names/RULE.md): Global physical names are derived per stage.
+- [`alchemy/runtime/bind-tag-not-implementation`](./alchemy/runtime/bind-tag-not-implementation/RULE.md): Other runtimes bind the Tag; only the Stack provides the Layer.
+- [`alchemy/runtime/deterministic-config-defaults`](./alchemy/runtime/deterministic-config-defaults/RULE.md): Config defaults and fallbacks are deterministic.
+- [`alchemy/runtime/disposables-in-request-scope`](./alchemy/runtime/disposables-in-request-scope/RULE.md): Disposables are acquired inside handlers, within request scope.
+- [`alchemy/runtime/lambda-no-post-response-work`](./alchemy/runtime/lambda-no-post-response-work/RULE.md): Lambda handlers write durable work before responding.
+- [`alchemy/runtime/no-per-request-work-at-construction`](./alchemy/runtime/no-per-request-work-at-construction/RULE.md): Construction builds resources and handlers, not per-request work.
+- [`alchemy/runtime/resolve-config-and-bindings-at-construction`](./alchemy/runtime/resolve-config-and-bindings-at-construction/RULE.md): Config and bindings are resolved at construction, not in handlers.
+- [`alchemy/secrets/let-alchemy-mint-infra-secrets`](./alchemy/secrets/let-alchemy-mint-infra-secrets/RULE.md): Infrastructure tokens are minted once by alchemy, not hardcoded.
+- [`alchemy/secrets/none-in-browser-env`](./alchemy/secrets/none-in-browser-env/RULE.md): Browser-inlined env values hold only public configuration.
+- [`alchemy/secrets/redacted-until-use`](./alchemy/secrets/redacted-until-use/RULE.md): Secrets stay `Redacted` until the call that needs the raw string.
+- [`alchemy/secrets/unwrap-before-compare-or-send`](./alchemy/secrets/unwrap-before-compare-or-send/RULE.md): `Redacted` values are unwrapped before compare, send, or serialize.
+- [`alchemy/security/authorize-public-endpoints`](./alchemy/security/authorize-public-endpoints/RULE.md): Public handlers authenticate and authorize every caller.
+- [`alchemy/security/github-secret-not-variable`](./alchemy/security/github-secret-not-variable/RULE.md): Sensitive CI values use `GitHub.Secret`, not `GitHub.Variable`.
+- [`alchemy/security/identity-from-verified-session`](./alchemy/security/identity-from-verified-session/RULE.md): The acting user comes from the verified session or token.
+- [`alchemy/security/keep-auth-protections-on`](./alchemy/security/keep-auth-protections-on/RULE.md): Auth checks and protections stay enabled.
+- [`alchemy/security/least-privilege-bindings`](./alchemy/security/least-privilege-bindings/RULE.md): Runtimes bind the narrowest capability their calls need.
+- [`alchemy/security/least-privilege-ci-credentials`](./alchemy/security/least-privilege-ci-credentials/RULE.md): CI credentials are scoped to what the stack deploys.
+- [`alchemy/security/lookup-failure-is-not-anonymous`](./alchemy/security/lookup-failure-is-not-anonymous/RULE.md): A failed session lookup is an error, not an anonymous user.

package/skills/adhere/SKILL.md

@@ -23,10 +23,12 @@ adhere init [--force]            # .adhere/config.ts, two example rules, and the
 adhere init --shared org/repo    # a repo of rules other repos install, with CI and an alchemy stack
 adhere login                     # save a TypeSafe AI API key; TYPESAFE_API_KEY takes precedence
 adhere validate                  # rule wording, rules a linter could check, contradictions
+adhere rules create [idea]       # wizard: claude, codex, or omp drafts a RULE.md or RULE.ts from excerpts you judge; org rules pushed for a PR
 adhere lint                      # judge the working directory; exit 1 on an error finding
 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 +40,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 +130,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 +156,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 +167,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. A rule-level `reads`, in
+Markdown front matter, `defineRule`, or an inline rule, has no effect. The
+context maps are:
 
 - `workspacePackages`: only packages matched by this file's literal imports,
   as `{ canonicalPackageName: directory }`. Subpaths match the owning package;
@@ -184,10 +190,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 +211,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 +255,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 +347,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 +361,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 +407,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

@@ -25,10 +25,10 @@ the `packageManager` field in `package.json` names it; with neither, **Ask**.
 
 | Manager | Add adhere                       | Run adhere         |
 | ------- | -------------------------------- | ------------------ |
-| bun     | `bun add -D @drkmttr/adhere`     | `bunx adhere`      |
+| bun     | `bun add -D @drkmttr/adhere`     | `bun run adhere`   |
 | pnpm    | `pnpm add -D @drkmttr/adhere`    | `pnpm exec adhere` |
 | yarn    | `yarn add -D @drkmttr/adhere`    | `yarn adhere`      |
-| npm     | `npm install -D @drkmttr/adhere` | `npx adhere`       |
+| npm     | `npm install -D @drkmttr/adhere` | `npm exec adhere`  |
 
 In a repo with a `package.json`, add adhere as a dev dependency with its
 manager, so the repo pins the version the team and CI run. From then on,
@@ -37,30 +37,38 @@ 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
+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. On macOS and Linux:
 
 ```sh
-curl -fsSL --create-dirs -o ~/.local/bin/adhere \
-  https://github.com/darkmatter/adhere/releases/latest/download/adhere-$(uname -s)-$(uname -m)
-chmod +x ~/.local/bin/adhere
+curl -fsSL https://github.com/darkmatter/adhere/raw/main/scripts/install.sh | sh
 ```
 
+On Windows, download `adhere-Windows-x86_64.exe` from
+https://github.com/darkmatter/adhere/releases/latest.
+
 Validate and lint's paid requests need a TypeSafe AI API key: `TYPESAFE_API_KEY`,
 or one saved by `adhere login`, which the user runs; never ask for the key in
 chat or print it. Compiler-free planning with `--limit 0` needs no key.
@@ -139,10 +147,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 +186,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 +212,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 +222,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 +239,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 +255,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 +355,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: |