@drkmttr/adhere 0.15.0 → 0.18.0

package/bin/adhere.js

@@ -2,7 +2,10 @@
 /**
  * `adhere` on PATH. Runs the executable compiled for this machine, which the
  * install fetched as the optional dependency `@drkmttr/adhere-<platform>-<arch>`
- * (see scripts/npm-packages.ts). A checkout has none installed, so there it
+ * (see scripts/npm-packages.ts). For semantic reads, passes the native TypeScript
+ * compiler package resolved from that executable's dependencies to the bundled
+ * SDK. A missing compiler does not block plain commands; the reads adapter
+ * validates it when needed. A checkout has no executable installed, so there it
  * runs src/main.ts with Bun instead.
  */
 import { spawnSync } from "node:child_process";
@@ -24,8 +27,20 @@ const resolveExecutable = () => {
   }
 };
 
-const run = (command, commandArgs) => {
-  const result = spawnSync(command, commandArgs, { stdio: "inherit" });
+const resolveCompilerPackage = (prebuilt) => {
+  try {
+    return createRequire(prebuilt).resolve(`@typescript/typescript-${platform}/package.json`);
+  } catch {
+    return undefined;
+  }
+};
+
+const run = (command, commandArgs, compilerPackage) => {
+  const env = { ...process.env };
+  // This private handoff must not let an inherited value redirect the compiler.
+  delete env.ADHERE_TYPESCRIPT_PACKAGE;
+  if (compilerPackage) env.ADHERE_TYPESCRIPT_PACKAGE = compilerPackage;
+  const result = spawnSync(command, commandArgs, { stdio: "inherit", env });
   if (result.error) throw result.error;
   if (result.signal) {
     // A killed process says nothing itself, so say what killed it.
@@ -39,7 +54,7 @@ const run = (command, commandArgs) => {
 };
 
 const prebuilt = resolveExecutable();
-if (prebuilt) run(prebuilt, args);
+if (prebuilt) run(prebuilt, args, resolveCompilerPackage(prebuilt));
 else if (existsSync(new URL("../.git", import.meta.url)))
   run("bun", [fileURLToPath(new URL("../src/main.ts", import.meta.url)), ...args]);
 else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -34,7 +34,8 @@
     "typecheck": "tsc --noEmit && bun run lint",
     "build": "bun build --compile --minify --sourcemap --define ADHERE_BUILD=\"\\\"$(git describe --tags --dirty --always)\\\"\" src/main.ts --asset ./presets --outfile dist/adhere",
     "build:npm": "bun scripts/npm-packages.ts build",
-    "release": "release-it"
+    "release": "release-it",
+    "prepare": "vp config"
   },
   "dependencies": {
     "effect": "4.0.0-rc.118"
@@ -44,12 +45,27 @@
     "@types/bun": "^1.4.2",
     "@types/node": "^24.13.6",
     "release-it": "^21.1.0",
-    "typescript": "7.0.2",
-    "vite-plus": "0.3.2",
-    "vitest": "4.1.11"
+    "typescript": "7.1.0-dev.20261009.1",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite-plus": "1.1.0",
+    "vitest": "5.0.3"
   },
   "overrides": {
-    "@effect/platform-node-shared": "4.0.0-rc.118"
+    "@effect/platform-node-shared": "4.0.0-rc.118",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vitest": "5.0.3"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "bun",
+      "version": "1.4.2",
+      "onFail": "download"
+    },
+    "runtime": {
+      "name": "node",
+      "version": "24.21.0",
+      "onFail": "download"
+    }
   },
   "release-it": {
     "$schema": "https://unpkg.com/release-it@21.1.0/schema/release-it.json",
@@ -64,14 +80,20 @@
     },
     "npm": {
       "allowSameVersion": true,
-      "publish": false
+      "publish": false,
+      "versionArgs": [
+        "--force"
+      ]
     }
   },
+  "versionArgs": [
+    "--force"
+  ],
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.15.0",
-    "@drkmttr/adhere-darwin-x64": "0.15.0",
-    "@drkmttr/adhere-linux-arm64": "0.15.0",
-    "@drkmttr/adhere-linux-x64": "0.15.0",
-    "@drkmttr/adhere-win32-x64": "0.15.0"
+    "@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"
   }
 }

package/skills/adhere/SKILL.md

@@ -24,7 +24,8 @@ adhere init --shared org/repo    # a repo of rules other repos install, with CI
 adhere login                     # save a TypeSafe AI API key; TYPESAFE_API_KEY takes precedence
 adhere validate                  # rule wording, rules a linter could check, contradictions
 adhere lint                      # judge the working directory; exit 1 on an error finding
-adhere lint --limit 0            # show the plan and its cost, judge nothing
+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 --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
@@ -35,7 +36,20 @@ adhere install org/repo[/topic[/rule]][#ref]   # copy them into .adhere/rules/or
 adhere skill [docs|setup|fix]    # print a skill
 ```
 
-`adhere <command> --help` lists every flag.
+`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.
+
+`--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
+rules and cached-location work. Cached-locate-only files count; fully cached and
+already-located files report without consuming slots. After the cap, both judge
+and locate work wait. Known cheap-budget skips refill from later paths; native
+or HTTP-size skips after selection consume a slot without runtime refill.
+A file can generate judge, locate, split-batch, and private hook requests, so
+this is not an HTTP-request or cost cap. Confirm the estimated cost and its
+native-context caveat before execution.
 
 ## Rule files
 
@@ -106,28 +120,21 @@ Front matter besides `description`, all optional:
   one line, scope a rule without widening its description: a finding stands
   only when Jev says the code that breaks the rule is as every `appliesTo`
   describes and as no `excludeIf` does.
-- `reads: ["workspacePackages"]`, a JSON array on one line, names what Jev
-  reads for the rule beside the code, each under that name. There is one so
-  far, `workspacePackages`: each of the repository's own packages, by name,
-  with its directory, read from the root `package.json`'s `workspaces` or
-  `pnpm-workspace.yaml`. Use it for a rule that turns on whether an import is
-  of the repository's own package or an installed one, and name
-  `workspacePackages` in the description. A name adhere does not have refuses
-  the run. The rule costs a request of its own per file, and a changed
-  workspace judges it again.
 
 A rule's directory can hold a `RULE.ts` instead, which default-exports
 `defineRule({...})` from `@drkmttr/adhere`, with the fields a config's inline
 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: { "1": "…", "2": "…" } }`, the file's
-sections as Jev reads them. Use it to give Jev what the file cannot show, such
+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
 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, one more per file judged, and its judgments are not
-redone when what the hook reads changes, only when the file or the rule,
-hook included, does. Helpers it imports go beside it in its directory.
+requests of its own, repeating the shared context. Hook-owned external data
+changes are not tracked by the cache; neither are built-in read-context contents
+or reader selection. Judgments are redone when own code, model, rule, matcher,
+or hook source changes, or the user clears the cache. Helpers it imports go
+beside it in its directory.
 
 A rule a regex, an import check, or the type checker could flag every time
 belongs in that tool, not adhere. `adhere validate` reports rules that look
@@ -145,7 +152,8 @@ import { defineConfig } from "@drkmttr/adhere";
 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 may not show enough
+  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
   exclude: ["**/generated/**"], // files no rule judges
   includeComments: false, // true only for rules about comments
   overrides: {
@@ -155,6 +163,108 @@ 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:
+
+- `workspacePackages`: only packages matched by this file's literal imports,
+  as `{ canonicalPackageName: directory }`. Subpaths match the owning package;
+  the discovered workspace catalog is internal and never sent. The cheap lexer
+  recognizes static/type imports, re-exports, dynamic import and require calls,
+  including plain literal templates in calls. Computed modules/template
+  substitutions are skipped and `require` binding is not resolved: this is
+  cheap filtering, not semantic module resolution. No matches yields `{}`.
+- `symbols`: `Record<string, string>`, mapping names to compiler-rendered type
+  blocks plus compiler documentation and JSDoc tags. Distinct same-name binding
+  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
+  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;
+  and whole class/interface/type-alias declarations. Repeated/overlapping scopes
+  merge; disjoint scopes join with `…`. This is syntactic selection, not recursive
+  helper-call expansion: an imported function's called helpers are not added
+  automatically. Indentation and comment/directive policy remain; associated
+  JSDoc stays when `includeComments` is true; compiler docs/tags in `symbols`
+  remain available regardless.
+  Current-file, `.d.ts`, `.d.mts`, `.d.cts`, `node_modules`, and outside-root
+  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`
+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
+projects under solution roots. Unconfigured or excluded files fall back to
+best-effort inferred context, not a refusal. These are complete outgoing AST
+declaration scopes and compiler type/docs strings, not a complete
+workspace-reference graph.
+
+`SourceReads.prepare(paths)` registers metadata only: no file I/O, compiler/SDK
+import, spawn, snapshot, or semantic query, regardless of how many paths are registered.
+The first real read lazily starts one TypeScript `--lsp --stdio` process,
+pinned with its SDK to exactly `7.1.0-dev.20261009.1`. This prerelease contains
+the tuple-reference serialization fix from [microsoft/TypeScript#64080](https://github.com/microsoft/TypeScript/issues/64080);
+the SDK and native executable must match that exact version. `NativeLsp` owns lifecycle only; it makes no `textDocument/hover` calls.
+Types and documentation come directly from the compiler SDK through the public
+API attached with `API.fromLSPConnection` to that process's API pipe. Symbol/type
+queries are batched; independent SDK requests run in chunks of at most 8 within
+the current document transaction.
+
+Only one native transaction owns a permit at a time. It receives the as-written
+text after normalized-code/ignore active-plan validation, opens the current
+document with `didOpen` version 1, uses `textDocument/documentSymbol` as the
+readiness barrier, and calls
+the public, parameterless `API.getCurrentLanguageServerSnapshot()` per read. Success sends `didClose`, performs
+guarded snapshot disposal, and clears the AST cache; native failure closes the
+session under a watchdog. There is no audit-wide immutable snapshot and no
+preload/freeze of registered files. Only current-read text is pinned; keep live
+dependencies/configs stable during the audit.
+
+SDK/write phases and LSP requests have 30-second deadlines and reject on compiler
+exit. Waiting readers are interruptible; the active owner is uninterruptible
+for resource safety. A stalled phase is bounded, with a further 2-second cleanup
+watchdog escalating to `SIGKILL`; this is not a total audit-duration guarantee.
+Native context is serial, but HTTP execution retains concurrency 8.
+
+Even one pending file may require parsing its selected project; warm monorepo
+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.
+
+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.
+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.
+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.
+
 `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`
 in the config, inline or as a directory of rule directories, replaces
@@ -189,10 +299,12 @@ so a private repo needs git's credentials for GitHub.
 
 ## Comments and suppressions
 
-Jev never sees comments: adhere blanks them before judging, since comments
-claiming code is safe hid real violations in the evals. A comment containing
-`@adhere` is a note Jev does read: use it for a checked fact the code relies
-on that the file cannot show, with how you know.
+adhere blanks ordinary comments in judged code and declaration snippets, since
+comments claiming code is safe hid real violations in the evals. Compiler
+documentation and JSDoc tags in `symbols` are separate and can remain even with
+`includeComments: false`. A comment containing `@adhere` is a note Jev does read:
+use it for a checked fact the code relies on that the file cannot show, with
+how you know.
 
 ```ts
 // @adhere DeleteActivity succeeds on a missing activity; probed 2026-09-25.
@@ -210,20 +322,56 @@ file. Name several rules with commas.
 
 ## Cache and API key
 
-Judgments are cached in `.adhere/cache/`, keyed by each file's content without
-comments and by the rule's text. Commit it: every judgment is a paid request,
-and a committed cache gives the team and CI the same findings without paying
-again. A changed file re-judges every rule for it; an edited rule re-judges
-only that rule; a threshold change re-judges nothing. A run where everything
-is cached needs no key or network. Mark it generated to keep it out of diffs:
+Judgments are cached in `.adhere/cache/`, keyed by each file's normalized own code and
+model/rule/matcher/hook-source fingerprints. Commit it: judging uses paid
+requests, and a committed cache gives the team and CI the same findings without
+paying again. Changed own code re-judges every rule for that file; an edited rule
+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
+stale dependency/context judgments.
+
+`planAudit` reads/counts/hashes code, checks the cache, and makes code plus cheap
+workspace estimates without compiler or `SourceReads` calls. It applies `--limit`
+to request-bearing files in path order before budgeting all pending rules and
+cached-location work for each selected file. Rule/cache check totals remain
+overall metrics; deferred/waiting counts are files. Deferred files remain
+unbudgeted until selected and can later be found too large. `--limit 0` skips
+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
+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.
+
+For an explicit refresh, from the audited working directory:
+
+```sh
+rm -rf .adhere/cache
+adhere lint --limit 0  # compiler-free counts/cache plan; budgeting is skipped
+adhere lint           # confirm fresh execution; actual context costs may be higher
+```
+
+This removes judgments and linter tallies and can cause new paid requests. Do
+not clear it automatically when dependencies or readers change. Clear explicitly
+if the user wants to compare fresh compiler type/docs and declaration payloads rather than cached
+answers from an older format. Mark it generated to keep it out of diffs:
 
 ```text
 .adhere/cache/** linguist-generated -diff
 ```
 
 The key comes from `TYPESAFE_API_KEY` or from `adhere login`. lint prints a
-plan with the request count and estimated cost before sending, and asks at a
-terminal.
+compiler-free plan with estimated requests/cost before sending and asks at a
+terminal. Output and prompt warn that native context is omitted and may increase
+actual tokens, cost, and request splits. Only confirmed execution prepares context
+and enforces full budgets before HTTP.
 
 ## Reading a report
 
@@ -241,8 +389,9 @@ line; `×` is an error, `⚠` a warning. `confidence` is Jev's probability that
 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 shows
-enough to decide, colored the same way around the sufficiency threshold, 0.6
+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.
+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
 on something outside the file, and was usually false in the evals: check that

package/skills/adhere-setup/SKILL.md

@@ -37,10 +37,23 @@ wherever this skill says `adhere`, run it the manager's way, as in
 
 With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
 
-In a repo without a `package.json`, use the `adhere` on PATH (`adhere
---version`), or **Ask** before installing the executable from the latest
-release (`adhere-Windows-x86_64.exe` on Windows), which needs no Node or
-package manager:
+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.
+
+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:
 
 ```sh
 curl -fsSL --create-dirs -o ~/.local/bin/adhere \
@@ -48,9 +61,9 @@ curl -fsSL --create-dirs -o ~/.local/bin/adhere \
 chmod +x ~/.local/bin/adhere
 ```
 
-Validate and lint 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.
+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.
 
 ## 2. Find candidates
 
@@ -124,7 +137,12 @@ the wording of any. Revise drafts the user wants changed and show them again.
 - Without a config, run `adhere init`. It also writes two example rules under
   `.adhere/rules/style/`; delete them unless the user chose them.
 - Copy each chosen draft to `.adhere/rules/<topic>/<slug>/RULE.md`.
-- Add chosen presets, or topics, to `presets` in `.adhere/config.ts`.
+- 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.
 - 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.
@@ -146,15 +164,115 @@ which to keep, and apply it. Run it again until it reports no contradictions.
 adhere lint --limit 0
 ```
 
-This shows the plan and judges nothing: files, rules, requests, and the
-estimated cost. Tell the user those numbers. On a large repo, offer to start
-with a subtree, such as `--filter 'src/**'`, or a `--limit`. **Ask** before
-sending, then run it:
+This shows a compiler-free plan and judges nothing: overall files/rules/cache
+check metrics, and files deferred for a later run. Planning reads/counts/hashes
+own code and checks cached answers; `--limit 0` skips budgeting, native reads,
+and HTTP execution. A positive limit counts files needing requests, not rule
+checks. Only selected files' pending rules and cached-location work are budgeted;
+deferred/waiting counts are files, which can later be found too large. Planning never calls
+`SourceReads` or resolves native symbols/references. Explain the output/prompt
+caveat: estimates omit native context and hook-added data, so actual tokens,
+cost, and request splits may be higher. Source reload/hash work is bounded to
+8 files; plans retain compact metadata, not all source text. Files are reloaded
+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.
+
+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
+all pending rules per selected file. Judging plus cached-unlocated work in one
+file uses one slot; a cached-locate-only file also counts. Fully cached and
+already-located files report without using slots. After the cap, both judge and
+locate work wait. Known cheap-budget skips refill from later files, but native
+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:
 
 ```sh
 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
+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
+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.
+
+`symbols` remains `Record<string, string>`: compiler-rendered distinct type
+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
+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
+scopes merge and disjoint scopes join with `…`. This is syntactic scope selection,
+not recursive helper-call expansion: helpers called by an imported function are
+not automatically expanded. Scopes preserve indentation and the comment/directive
+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.
+
+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
+match. This prerelease contains the tuple-reference serialization fix from
+[microsoft/TypeScript#64080](https://github.com/microsoft/TypeScript/issues/64080). `NativeLsp` owns lifecycle only and makes
+no `textDocument/hover` calls. Each read uses the passed as-written text after
+normalized-code/ignore active-plan validation, opens only that document at
+version 1, uses `textDocument/documentSymbol` as its readiness barrier, and calls
+the public, parameterless `API.getCurrentLanguageServerSnapshot()`.
+Success closes the document, disposes that snapshot under a guarded phase, and
+clears AST caches; native failure closes the session under the watchdog.
+
+Keep dependencies/configs stable: only current-read text is pinned, not every
+registered file or an immutable global audit snapshot. Warm compiler project
+graphs can still be large and slow to load; neither total memory nor payload
+size is constant, and contexts may still exceed model budgets.
+
+SDK/write phases and LSP requests have 30-second deadlines and reject on compiler
+exit. Queued readers can be interrupted; the active owner is uninterruptible
+for resource safety. A stalled phase is bounded and cleanup adds a 2-second
+`SIGKILL` watchdog. These are phase/cleanup bounds, not a whole-audit timeout.
+
+If the user explicitly chose a cache refresh, run from the audited working
+directory, using the repo's package launcher as above:
+
+```sh
+rm -rf .adhere/cache
+adhere lint --limit 0
+```
+
+Show the fresh counts/cache plan; `--limit 0` skips budgeting. For selected
+execution work, explain that its estimate omits native context and may understate
+cost/splits, then **Ask** before paid execution. Deleting the cache removes judgments and linter tallies; it can cause
+new paid requests. Use this explicitly if the user wants to compare fresh
+compiler type/docs and declaration payloads with older cached answers. A change in `B.ts` does not
+otherwise invalidate cached judgments for an unchanged importing `A.ts`.
+
 Walk the user through the report:
 
 1. How to read a finding: the rule id, the description, its confidence and
@@ -165,7 +283,8 @@ Walk the user through the report:
 3. For each noisy rule, propose one change from the adhere skill's "Tuning a
    rule": narrow the wording, scope it, raise its threshold, make it a
    warning, or turn it off. **Ask**, apply what the user accepts, and run
-   lint again. Only the edited rules are judged again.
+   lint again. With unchanged own code and model, only the edited rules are
+   judged again; dependency/context changes alone are not tracked.
 
 CI fails on any error finding, so lint must exit 0 before step 8. **Ask** how
 to get there: fix the real findings now with the adhere-fix skill
@@ -212,9 +331,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. In a repo without a `package.json`, skip the
-setup and install, and fetch the executable at the version the user ran
-locally:
+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:
 
 ```yaml
 - run: |