chore: honesty + hygiene cleanup pass (3-agent audit findings)

A 3-agent audit (code cleanliness · feature-interaction · fresh-clone health)
verified the session's work is 100% on build/tests/install (fresh clone:
1097/1097 green, all features smoke-verified, clean tarball) and surfaced three
real honesty/cleanliness issues, now fixed:

- Grep handler claimed its caller list was 'ranked' — but findCallers returns an
  alphabetical sort, not an importance ranking. Dropped 'ranked' from the
  agent-facing packet + the header comment + ADR-0001 + CHANGELOG (the *real*
  PageRank query-ranking in README/query.ts is untouched — only the false
  grep-caller claim). Matches the v4.1 honesty discipline.
- Read dedup pointer said 'its contents are already in your context' — overstated
  when the first read returned a structural packet (the agent has the summary,
  not the contents). Softened to 'what you saw then is still in your context'
  (true whether the first read served a packet or passed the raw file through).
- served-reads.ts: corrected a comment that described the  timestamp refresh
  backwards.

Also:
up to date, audited 188 packages in 931ms

50 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities (non-breaking) cleared all 6 transitive vulns (1 high
fast-uri via the MCP SDK → ajv, 5 moderate) → 0 vulnerabilities, production +
dev. Only package-lock.json changed.

No code-behaviour change. Audit: tsc clean; full suite 1097/1097; build clean;
npm audit 0 vulns; leak-scan 0 hits. Feature-interaction audit verdict SHIP
(landmine not reintroduced, opt-outs independent, no state collisions).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NickCirv

CHANGELOG.md

@@ -22,7 +22,7 @@ All notable changes to engram are documented here. Format based on
   `PreToolUse:Grep` handler answers symbol-usage searches from the `calls`
   reference graph instead of letting a raw match dump flood the context window.
   When the agent greps a bare identifier that's a known symbol with references,
-  engram denies the grep and returns the ranked list of files that reference it,
+  engram denies the grep and returns the list of files that reference it,
   plus the exact `rg -n "<pattern>"` escalation command. **Recall-safe by
   construction:** regex/text/multi-word/stopword patterns and unknown symbols
   pass straight through (grep out-recalls the structural graph there), and the

docs/adr/0001-grep-symbol-intercept.md

@@ -11,13 +11,13 @@ still runs every `Grep` raw, and a symbol search across a large repo floods the
 match lines (often 2–20k tokens). The W1.9 benchmark shows engram already wins exactly on the
 explore-heavy workloads (troubleshooting +24.9%, code-understanding +23.3%) and is neutral/negative on
 linear edits — i.e. the value is in *exploration elimination*, which this gap leaves on the table. The
-`calls` reference graph + `findCallers/findCallees/findImpact` (PageRank-ranked) already exist but are
+`calls` reference graph + `findCallers/findCallees/findImpact` (pure traversal, alphabetically sorted) already exist but are
 CLI-only — never wired into the hook.
 
 ## Decision
 
 Add a `PreToolUse:Grep` handler that intercepts **only** a bare-identifier pattern that matches a known
-symbol with references in the `calls` graph, denies the grep, and returns engram's ranked caller list.
+symbol with references in the `calls` graph, denies the grep, and returns engram's caller list (the files that reference it).
 For anything else — regex/metacharacter patterns, multi-word/text searches, stopword identifiers, or a
 symbol the graph doesn't know — it returns PASSTHROUGH so the real grep runs.
 
@@ -27,7 +27,7 @@ wholesale would blind the agent — a correctness regression. We mitigate by (a)
 the pattern is a known symbol with ≥1 caller (high precision), and (b) **always emitting the exact
 `rg -n "<pattern>"` escalation command** in the deny reason, so the agent can recover full textual
 matches in one step if it needs them. The token win comes from the common case ("where is this symbol
-used") being answered from a ranked file list (~tens–hundreds of tokens) instead of a raw match dump,
+used") being answered from a caller-file list (~tens–hundreds of tokens) instead of a raw match dump,
 while correctness is preserved by the escalation path. The discarded alternative — augment-don't-deny
 (let grep run AND add engram's note) — preserves recall perfectly but saves zero tokens (grep still
 runs + we add tokens), which defeats the purpose. If the precision gate proves too narrow or too broad

package-lock.json

@@ -16,8 +16,8 @@
  * real grep runs. Default to doing nothing; act only when provably helpful.
  *
  * Returns:
- *   - A deny response whose reason is engram's ranked caller list, when the
- *     pattern is a known symbol with references.
+ *   - A deny response whose reason is engram's caller list (the files that
+ *     reference the symbol), when the pattern is a known symbol with references.
  *   - PASSTHROUGH (null) otherwise — caller writes nothing, exits 0, the real
  *     Grep runs unchanged.
  * Never throws. Every error path resolves to PASSTHROUGH via wrapSafely.
@@ -106,7 +106,7 @@ function buildGrepAnswer(pattern: string, callerFiles: string[]): string {
   const list = callerFiles.map((f) => `  - ${f}`).join("\n");
   return [
     `[engram] "${pattern}" is referenced by ${callerFiles.length} file(s) ` +
-      `in the reference graph (structural \`calls\` edges, ranked):`,
+      `in the reference graph (structural \`calls\` edges):`,
     list,
     "",
     "This is engram's structural answer — resolved function/class references " +

src/intercept/handlers/grep.ts

@@ -63,7 +63,7 @@ export const READ_CONFIDENCE_THRESHOLD = 0.7;
 function buildDedupPointer(relPath: string): string {
   return (
     `[engram] You already read \`${relPath}\` earlier in this session and it ` +
-    `has not changed since — its contents are already in your context above, ` +
+    `has not changed since — what you saw then is still in your context above, ` +
     `no need to re-read it. (If you believe it changed, read it again: engram ` +
     `only dedupes byte-identical files within one session and resets on context ` +
     `compaction.)`

src/intercept/handlers/read.ts

@@ -136,8 +136,9 @@ export function dedupOrRecord(
     }
 
     // First read (or changed, or tiny, or stale): record and continue. `at` is
-    // refreshed only on a real (re-)serve, so dedup-eligibility ages from when
-    // the content last entered context, not from the last pointer.
+    // set here, on a record — never on a dedup hit (which returns above without
+    // touching it) — so dedup-eligibility ages from when this version of the
+    // content last entered context, not from the last pointer.
     map[key] = { mtimeMs: st.mtimeMs, size: st.size, at: now };
     capEntries(map);
     try {