@tekyzinc/gsd-t 4.10.12 → 4.11.11

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.11.11] - 2026-06-27
+
+### Fixed — SCIP resolution missed nested/monorepo tsconfig (call-graph empty on subdir-tsconfig projects)
+
+`runScipTypescript` ran scip-typescript without `--infer-tsconfig`, so projects whose `tsconfig.json` lives in a subdirectory (`web/tsconfig.json`, monorepo packages) produced 0 resolved call edges — scip-typescript found no root tsconfig and skipped resolution.
+
+- `bin/gsd-t-graph-scip-upgrade.cjs`: add `--infer-tsconfig` so scip-typescript discovers a nested tsconfig; bumped the timeout to 180s for larger inferred projects.
+
+Proven on ClaudeWebCLI (tsconfig at `web/tsconfig.json`): 0 → 1,149 resolved call edges. Suite: 2519/2519 pass.
+
+## [4.11.10] - 2026-06-27
+
+### Added — M97: the code graph is the default for ambient code-reading (grep-intercept), + 3 call-resolution fixes
+
+A PostToolUse hook on Claude's built-in `Grep` makes structural searches consult the code graph instead of raw text. The graph only powered explicit GSD-T commands before; now any "where is this used / who calls this" grep gets a precomputed graph answer.
+
+- `bin/gsd-t-grep-classifier.cjs`: NEW — conservative structural-vs-text classifier (bare symbol / call shape / member call / import → structural verb; strings/regex/phrases → TEXT pass-through).
+- `scripts/gsd-t-graph-intercept.js`: NEW — PostToolUse hook on Grep. Structural + graph-present → query the graph, REPLACE the grep output via `updatedToolOutput` (original hits kept beneath, labeled by tier); else pass through. FAIL-OPEN, never calls Grep/Read (no loop), no-op without a graph.
+- `bin/gsd-t.js`: `gsd-t install` registers the hook (matcher `Grep`), idempotent.
+
+**Fixed — the call-graph was EMPTY on real projects (3 bugs):**
+- `bin/gsd-t-graph-index.cjs`: the CLI `build` path passed the upgrader MODULE as the `scip` option, so `build_index` skipped auto-building the resolver → 0 resolved edges on every `gsd-t graph index` (fixtures passed via the direct `build_index({dbPath})` path). Now the CLI lets build_index auto-build.
+- `bin/gsd-t-scip-reader.cjs`: method names after `#` (`Class#method()`) weren't extracted (split on `/` only) — now split on last `/` OR `#`; and build-output docs (`dist-*`/`build-*`/`out-*`) are skipped so minified bundles don't pollute who-calls.
+- `bin/gsd-t-graph-query-cli.cjs`: who-calls dropped results on a funcId `@line`-suffix mismatch (funcEntities key `file#name@line`, callGraph keys `file#name`) — now tolerant.
+- `bin/gsd-t-graph-freshness.cjs`: hashed files with md5 while the indexer stores sha256 — every file read as "changed" → whole-repo re-index on every query (`gsd-t graph status` 30s→0.38s on a large project). Now sha256(16), excludes synced.
+
+binvoice (real project): 2,579 resolved call edges; `who-calls(getSessionToken)` → real callers. Hook latency ~0.46s/call (node startup; query <100ms). Suite: 2519/2519 pass.
+
 ## [4.10.12] - 2026-06-27
 
 ### Fixed — freshness hash mismatch made every graph query re-index the whole repo

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.10.12** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.11.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-graph-freshness.cjs

@@ -76,6 +76,20 @@ const EXCLUDE_DIRS = new Set([
   '.idea', '.vscode', 'tmp', '.tmp', 'site-packages',
 ]);
 
+// Build-output dirs with a suffix (dist-local, build-ios, out-prod) — prefix
+// match, matching the indexer's shouldSkipDir. [RULE] freshness-excludes-match-indexer-skipdirs
+const EXCLUDE_DIR_PREFIXES = ['dist', 'build', 'out'];
+function shouldExcludeDir(name) {
+  if (EXCLUDE_DIRS.has(name)) return true;
+  for (const pre of EXCLUDE_DIR_PREFIXES) {
+    if (name.length > pre.length && name.startsWith(pre) &&
+        (name[pre.length] === '-' || name[pre.length] === '.' || name[pre.length] === '_')) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function walkTree(dir, results = []) {
   // Defense-in-depth: refuse to walk the filesystem root or the user's home dir.
   // A bogus projectRoot (e.g. "/") from a fake store path would otherwise recurse
@@ -90,9 +104,9 @@ function walkTree(dir, results = []) {
   catch { return results; }
   for (const e of entries) {
     if (e.name.startsWith('.') && e.name !== '.claude') {
-      if (EXCLUDE_DIRS.has(e.name)) continue;
+      if (shouldExcludeDir(e.name)) continue;
     }
-    if (EXCLUDE_DIRS.has(e.name)) continue;
+    if (shouldExcludeDir(e.name)) continue;
     const full = path.join(dir, e.name);
     if (e.isDirectory()) {
       walkTree(full, results);

package/bin/gsd-t-graph-index.cjs

@@ -77,6 +77,23 @@ const SKIP_DIRS = new Set([
   '.idea', '.vscode', 'tmp', '.tmp', 'site-packages',
 ]);
 
+// Build-output dirs often carry a suffix (dist-local, dist-test, build-ios,
+// out-prod). Prefix-match these so generated/minified bundles never pollute the
+// graph (binvoice indexed dist-local/dist-test → duplicate symbols in who-calls).
+const SKIP_DIR_PREFIXES = ['dist', 'build', 'out'];
+
+function shouldSkipDir(name) {
+  if (SKIP_DIRS.has(name)) return true;
+  for (const pre of SKIP_DIR_PREFIXES) {
+    // exact 'dist' is already in SKIP_DIRS; match 'dist-*'/'dist.*' variants.
+    if (name.length > pre.length && name.startsWith(pre) &&
+        (name[pre.length] === '-' || name[pre.length] === '.' || name[pre.length] === '_')) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // ── Content hash ──────────────────────────────────────────────────────────────
 
 /**
@@ -97,7 +114,7 @@ function enumerateFiles(root) {
     catch { return; }
     for (const e of entries) {
       if (e.isDirectory()) {
-        if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name));
+        if (!shouldSkipDir(e.name)) walk(path.join(dir, e.name));
       } else if (e.isFile()) {
         const ext = path.extname(e.name).toLowerCase();
         if (PARSED_EXTS.has(ext)) {
@@ -492,17 +509,14 @@ if (require.main === module) {
   info(`build_index — repo: ${repoRoot}`);
   info(`Store: ${dbPath}`);
 
-  // Load SCIP upgrader if available
-  let scip = null;
-  try {
-    scip = require('./gsd-t-graph-scip-upgrade.cjs');
-  } catch {
-    warn('SCIP upgrader not found — using tree-sitter-floor only');
-  }
-
+  // Pass scip:null so build_index AUTO-BUILDS the repo-level SCIP resolver
+  // (runs scip-typescript once, reads index.scip, resolves call edges). Passing
+  // the raw upgrader MODULE here was the bug: build_index saw a truthy `scip`
+  // context with no `.resolver`, skipped auto-build, and stored 0 resolved edges
+  // on every CLI `gsd-t graph index` (M95/M96 fixtures passed because they called
+  // build_index({dbPath}) directly with scip:null). [RULE] cli-build-auto-resolves-scip
   const result = build_index(repoRoot, {
     dbPath,
-    scip,
     onProgress: ({ file, tier, fileCount, total }) => {
       if (fileCount % 100 === 0) {
         info(`[${fileCount}/${total}] ${tier === 'compiler-accurate' ? C.green : C.dim}${file}${C.reset}`);

package/bin/gsd-t-graph-query-cli.cjs

@@ -573,8 +573,9 @@ function queryWhoCalls(index, identity) {
   const coverage = computeCoverage(index.skippedFiles);
 
   if (isFuncId) {
-    // File-qualified identity — exact funcId lookup
-    const callers = index.callGraph.get(identity);
+    // File-qualified identity — exact funcId lookup (tolerate @line suffix:
+    // callGraph keys on `file#name`, callers may pass `file#name@line`).
+    const callers = index.callGraph.get(identity) || index.callGraph.get(identity.replace(/@\d+$/, ''));
     const results = callers ? Array.from(callers).sort() : [];
     return { results, tier: index.tier, coverage };
   }
@@ -593,8 +594,13 @@ function queryWhoCalls(index, identity) {
   }
 
   if (matchingFuncIds.length === 1) {
-    // Unambiguous bare name — resolve directly
-    const callers = index.callGraph.get(matchingFuncIds[0]);
+    // Unambiguous bare name — resolve directly.
+    // funcEntities key as `file#name@line`, but call edges (and thus callGraph)
+    // key as `file#name` (no @line) — try both so the @line-suffix difference
+    // doesn't drop real callers. [RULE] who-calls-funcid-line-suffix-tolerant
+    const fid = matchingFuncIds[0];
+    const fidNoLine = fid.replace(/@\d+$/, '');
+    const callers = index.callGraph.get(fid) || index.callGraph.get(fidNoLine);
     const results = callers ? Array.from(callers).sort() : [];
     return { results, tier: index.tier, coverage };
   }

package/bin/gsd-t-graph-scip-upgrade.cjs

@@ -134,10 +134,13 @@ function runScipTypescript(projectRoot, outPath) {
   // M95: emit to a REAL file (outPath) so the index can be READ and call edges
   // resolved — not /dev/null. The old /dev/null path only proved invocability.
   const out = outPath || path.join(projectRoot, '.gsd-t', 'index.scip');
-  const scip = spawnSync('scip-typescript', ['index', '--output', out, '.'], {
+  // --infer-tsconfig: resolve a tsconfig even when one isn't at the repo root
+  // (monorepos / nested layouts — e.g. web/tsconfig.json). Without it, projects
+  // whose tsconfig lives in a subdir got 0 resolved call edges. [RULE] scip-infer-nested-tsconfig
+  const scip = spawnSync('scip-typescript', ['index', '--infer-tsconfig', '--output', out, '.'], {
     cwd: projectRoot,
     encoding: 'utf8',
-    timeout: 120_000,
+    timeout: 180_000,
   });
   if (scip.status === 0) return { ok: true, scipPath: out };
   return { ok: false, error: scip.stderr || `exit code ${scip.status}` };

package/bin/gsd-t-grep-classifier.cjs

@@ -0,0 +1,97 @@
+/**
+ * gsd-t-grep-classifier.cjs
+ *
+ * M97 — Classify a Grep tool call as STRUCTURAL (the code graph can answer it
+ * better) or TEXT (let grep run). The grep-intercept hook uses this to decide
+ * whether to replace grep output with a graph answer.
+ *
+ * CONSERVATIVE BY DESIGN: when unsure → TEXT (pass grep through). A false
+ * "structural" hijacks a legitimate text search (bad); a false "text" just means
+ * we miss a graph opportunity (harmless — grep still works). So the bar for
+ * STRUCTURAL is high and the patterns are narrow.
+ *
+ * STRUCTURAL = the pattern is asking "where is this symbol used / who calls it /
+ * who imports it" — answerable from the import/call graph:
+ *   - a bare identifier (a function/class/variable name), no regex metachars
+ *   - an explicit import line for a symbol  (import ... X / from ... import X)
+ *   - a function/method call shape          (foo(  /  X.method()  )
+ *
+ * TEXT = everything else: string literals, error messages, TODOs, regexes,
+ * multi-word phrases, paths, comments, anything with regex metacharacters that
+ * isn't a plain call shape.
+ *
+ * [RULE] grep-classifier-conservative-text-default
+ */
+
+'use strict';
+
+// A plain identifier: starts with a letter/_/$ then word chars. No spaces, no
+// regex metacharacters, no dots (a bare name, not a member access or path).
+const BARE_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// A member-call shape: Obj.method or this.method (optionally with a trailing "(").
+const MEMBER_CALL = /^[A-Za-z_$][A-Za-z0-9_$]*\.[A-Za-z_$][A-Za-z0-9_$]*\(?$/;
+
+// A call shape: foo(  — a bare name immediately followed by "(".
+const CALL_SHAPE = /^[A-Za-z_$][A-Za-z0-9_$]*\($/;
+
+// Import-of-a-symbol shapes (JS/TS + Python). Capture the symbol.
+const IMPORT_SHAPES = [
+  /^import\s+\{?\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*\}?/, // import X / import { X }
+  /^from\s+\S+\s+import\s+([A-Za-z_$][A-Za-z0-9_$]*)/, // from m import X (python)
+];
+
+// Regex metacharacters that signal a TEXT/regex search (not a bare symbol).
+// (We allow a single trailing "(" for the call shape, handled before this.)
+const REGEX_METACHARS = /[\\^$.*+?\[\]{}|()<>:;,"'`@#%&!~ \t]/;
+
+/**
+ * Classify a grep pattern.
+ * @param {string} pattern  the Grep tool's `pattern` input
+ * @param {object} [opts]   reserved (e.g. path hints)
+ * @returns {{ structural: boolean, kind: string, symbol: string|null, verb: string|null }}
+ *   kind: 'bare-symbol' | 'member-call' | 'call-shape' | 'import' | 'text'
+ *   verb: the graph verb to run ('who-calls' | 'who-imports') or null for text
+ */
+function classifyGrep(pattern, opts = {}) {
+  const TEXT = { structural: false, kind: 'text', symbol: null, verb: null };
+
+  if (typeof pattern !== 'string') return TEXT;
+  const p = pattern.trim();
+  if (!p) return TEXT;
+
+  // Too long to be a symbol → text. (Symbols are short; long patterns are prose.)
+  if (p.length > 80) return TEXT;
+
+  // 1. Import-of-a-symbol → who-imports on that symbol.
+  for (const re of IMPORT_SHAPES) {
+    const m = p.match(re);
+    if (m && m[1]) {
+      return { structural: true, kind: 'import', symbol: m[1], verb: 'who-imports' };
+    }
+  }
+
+  // 2. Bare identifier → who-calls + who-imports (the hook unions them).
+  if (BARE_IDENT.test(p)) {
+    return { structural: true, kind: 'bare-symbol', symbol: p, verb: 'who-calls' };
+  }
+
+  // 3. Call shape: foo(  → who-calls on foo.
+  if (CALL_SHAPE.test(p)) {
+    return { structural: true, kind: 'call-shape', symbol: p.slice(0, -1), verb: 'who-calls' };
+  }
+
+  // 4. Member call: Obj.method / this.method → who-calls on the method name.
+  if (MEMBER_CALL.test(p)) {
+    const method = p.replace(/\(?$/, '').split('.').pop();
+    return { structural: true, kind: 'member-call', symbol: method, verb: 'who-calls' };
+  }
+
+  // 5. Anything with regex metachars / spaces / quotes → TEXT (conservative).
+  if (REGEX_METACHARS.test(p)) return TEXT;
+
+  // 6. Fallthrough → TEXT.
+  return TEXT;
+}
+
+module.exports = { classifyGrep, BARE_IDENT, MEMBER_CALL, CALL_SHAPE };

package/bin/gsd-t-scip-reader.cjs

@@ -81,12 +81,14 @@ function loadScipProto() {
  */
 function funcNameFromSymbol(symbol) {
   if (!symbol || typeof symbol !== 'string') return null;
-  // Parameters look like "name().(param)" — skip (they contain "(...)" after "().")
-  // Methods/functions end with "()." possibly preceded by the name.
-  // Take the final descriptor (after the last unescaped '/').
-  const lastSlash = symbol.lastIndexOf('/');
-  const descriptor = lastSlash === -1 ? symbol : symbol.slice(lastSlash + 1);
-  // Method/function descriptor: "<name>()." — capture <name>
+  // Only function/method occurrences (end with "()."). Parameters are "name().(p)"
+  // — they don't end with "()." so they're excluded.
+  if (!/\(\)\.$/.test(symbol)) return null;
+  // The callable name is the last descriptor segment. Top-level functions are
+  // ".../`file.ts`/name()."; methods are ".../`file.ts`/Class#method()." — so the
+  // name follows the LAST '/' OR '#', whichever is later (methods key on '#').
+  const cut = Math.max(symbol.lastIndexOf('/'), symbol.lastIndexOf('#'));
+  const descriptor = cut === -1 ? symbol : symbol.slice(cut + 1);
   const m = descriptor.match(/^([A-Za-z_$][\w$]*)\(\)\.$/);
   return m ? m[1] : null;
 }
@@ -95,6 +97,24 @@ function funcNameFromSymbol(symbol) {
 
 const SYMBOL_ROLE_DEFINITION = 0x1; // SymbolRole.Definition bit
 
+// scip-typescript indexes whatever its tsconfig includes — which on real projects
+// often covers build output (dist-local/, dist-test/, build/). Those generated
+// bundles must NOT enter the graph (duplicate, minified symbols pollute who-calls).
+// Mirror the indexer's SKIP_DIRS prefix logic at the SCIP-doc level.
+function isBuildOutputPath(relPath) {
+  const seg = String(relPath).split('/');
+  for (const s of seg) {
+    if (s === 'node_modules' || s === '.git' || s === 'coverage') return true;
+    for (const pre of ['dist', 'build', 'out']) {
+      if (s === pre || (s.length > pre.length && s.startsWith(pre) &&
+          (s[pre.length] === '-' || s[pre.length] === '.' || s[pre.length] === '_'))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 /**
  * Decode a `.scip` file and build resolution maps.
  *
@@ -128,7 +148,7 @@ function readScipIndex(scipPath) {
   // First pass: collect every DEFINITION occurrence → symbol → funcId.
   for (const doc of docs) {
     const relPath = doc.relative_path;
-    if (!relPath) continue;
+    if (!relPath || isBuildOutputPath(relPath)) continue;
     for (const occ of doc.occurrences || []) {
       const isDef = (occ.symbol_roles & SYMBOL_ROLE_DEFINITION) !== 0;
       if (!isDef) continue;
@@ -142,7 +162,7 @@ function readScipIndex(scipPath) {
   // Second pass: collect every REFERENCE occurrence per file, resolved to the def.
   for (const doc of docs) {
     const relPath = doc.relative_path;
-    if (!relPath) continue;
+    if (!relPath || isBuildOutputPath(relPath)) continue;
     const refs = [];
     for (const occ of doc.occurrences || []) {
       const isDef = (occ.symbol_roles & SYMBOL_ROLE_DEFINITION) !== 0;

package/bin/gsd-t.js

@@ -453,6 +453,13 @@ const CONTEXT_METER_STALE_PATTERNS = [
   /node\s+"?\$CLAUDE_PROJECT_DIR\/scripts\/gsd-t-context-meter\.js"?/,
 ];
 
+// M97 — graph-intercept PostToolUse hook on Grep. Runs from the global package;
+// the script itself fails-open (no-op) in non-GSD-T projects / projects without a
+// graph, so it is safe to register globally with a Grep matcher.
+const GRAPH_INTERCEPT_HOOK_MARKER = "gsd-t-graph-intercept";
+const GRAPH_INTERCEPT_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-intercept.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-intercept.js" || true\'';
+
 // Append entries to {projectDir}/.gitignore. Each entry added only if absent.
 // Idempotent. Returns true if any entries were added, false otherwise.
 function ensureGitignoreEntries(projectDir, entries) {
@@ -789,6 +796,60 @@ function configureContextMeterHooks(settingsPath) {
   return { installed: true, action };
 }
 
+// M97 — register the graph-intercept PostToolUse hook (matcher "Grep").
+// Idempotent: find-by-marker, refresh stale command, else add. Mirrors the
+// context-meter installer. The script fails-open so this is safe globally.
+function configureGraphInterceptHook(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  let settings = {};
+  if (fs.existsSync(targetPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+      if (!settings || typeof settings !== "object") settings = {};
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure graph-intercept hook");
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+
+  const cmd = GRAPH_INTERCEPT_HOOK_COMMAND;
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.PostToolUse) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h || typeof h.command !== "string") continue;
+      if (h.command === cmd || h.command.includes(GRAPH_INTERCEPT_HOOK_MARKER)) {
+        found = true;
+        if (h.command !== cmd) { h.command = cmd; action = "updated"; }
+        // ensure the matcher targets Grep
+        if (entry.matcher !== "Grep") { entry.matcher = "Grep"; action = action === "noop" ? "updated" : action; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.PostToolUse.push({
+      matcher: "Grep",
+      hooks: [{ type: "command", command: cmd }],
+    });
+    action = "added";
+  }
+  if (action === "noop") return { installed: true, action: "noop" };
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return { installed: false, action: "noop" };
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return { installed: false, action: "noop" };
+  }
+  return { installed: true, action };
+}
+
 // Remove any context meter PostToolUse hooks from settings.json.
 // Used during uninstall. Leaves all other hooks intact.
 function removeContextMeterHook(settingsPath) {
@@ -1721,6 +1782,14 @@ async function doInstall(opts = {}) {
     else info("Context meter hook already configured");
   }
 
+  heading("Graph-Intercept (PostToolUse on Grep — M97)");
+  const giHook = configureGraphInterceptHook(SETTINGS_JSON);
+  if (giHook.installed) {
+    if (giHook.action === "added") success("Graph-intercept hook added (structural greps consult the code graph)");
+    else if (giHook.action === "updated") success("Graph-intercept hook refreshed");
+    else info("Graph-intercept hook already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.10.12",
+  "version": "4.11.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-graph-intercept.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-intercept.js — M97
+ *
+ * A PostToolUse hook on the `Grep` tool. When Claude runs a grep that is actually
+ * a STRUCTURAL question (who-calls / who-imports / a bare symbol), this answers it
+ * from the precomputed code graph and REPLACES the grep output the model sees
+ * (via `updatedToolOutput`). Text searches pass through untouched.
+ *
+ * Receives JSON on stdin (PostToolUse):
+ *   { tool_name, tool_input: { pattern, path? }, tool_response/tool_output, cwd, ... }
+ *
+ * Emits JSON on stdout:
+ *   { hookSpecificOutput: { hookEventName: "PostToolUse",
+ *       updatedToolOutput: "<graph answer + original grep beneath>" } }
+ *   ...or nothing (exit 0) to pass the grep through unchanged.
+ *
+ * INVARIANTS:
+ *   - FAIL-OPEN: any error / missing graph / non-structural → pass through (emit nothing).
+ *   - NEVER calls Grep/Read (loop guard). Only spawns the graph query CLI.
+ *   - No graph in this project → pure no-op.
+ *   - Original grep hits are RETAINED beneath the graph answer (no silent hiding).
+ *
+ * [RULE] graph-intercept-fail-open-never-breaks-grep
+ * [RULE] graph-intercept-structural-only-text-passes-through
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const OUTPUT_CAP = 9000; // stay under the 10K hook output cap, leave headroom
+
+function passThrough() {
+  // Emit nothing → the original grep output reaches the model unchanged.
+  process.exit(0);
+}
+
+function emitReplacement(text) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      updatedToolOutput: text.length > OUTPUT_CAP
+        ? text.slice(0, OUTPUT_CAP) + '\n…(truncated — query the graph CLI directly for the full list)'
+        : text,
+    },
+  };
+  process.stdout.write(JSON.stringify(out));
+  process.exit(0);
+}
+
+// Resolve the project-local graph query CLI. Returns null if absent.
+function resolveQueryCli(cwd) {
+  const local = path.join(cwd, 'bin', 'gsd-t-graph-query-cli.cjs');
+  if (fs.existsSync(local)) return local;
+  return null;
+}
+
+function main(payload) {
+  // Only act on Grep.
+  if (!payload || payload.tool_name !== 'Grep') passThrough();
+
+  const cwd = payload.cwd || process.cwd();
+
+  // Must be a GSD-T project with a graph present.
+  if (!fs.existsSync(path.join(cwd, '.gsd-t'))) passThrough();
+  if (!fs.existsSync(path.join(cwd, '.gsd-t', 'graph.db'))) passThrough();
+
+  const pattern = payload.tool_input && payload.tool_input.pattern;
+  if (typeof pattern !== 'string' || !pattern) passThrough();
+
+  // Classify (the classifier itself fails safe → text).
+  let cls;
+  try {
+    const { classifyGrep } = require(path.join(__dirname, '..', 'bin', 'gsd-t-grep-classifier.cjs'));
+    cls = classifyGrep(pattern);
+  } catch { passThrough(); }
+  if (!cls || !cls.structural) passThrough();
+
+  const cliPath = resolveQueryCli(cwd);
+  if (!cliPath) passThrough();
+
+  // Query the graph. who-calls for symbols/calls; who-imports for imports.
+  // For a bare symbol we ALSO try who-imports so the model sees both usages.
+  const verbs = cls.verb === 'who-imports'
+    ? ['who-imports']
+    : ['who-calls', 'who-imports'];
+
+  const sections = [];
+  for (const verb of verbs) {
+    let res;
+    try {
+      res = spawnSync(process.execPath, [cliPath, verb, cls.symbol], {
+        cwd, encoding: 'utf8', timeout: 8000,
+      });
+    } catch { continue; }
+    // Parse the envelope regardless of exit status — an ambiguous-symbol result
+    // exits non-zero with ok:false but still carries a valid structural answer
+    // (the candidate list). Only a missing/garbled stdout is unusable.
+    if (!res || !res.stdout) continue;
+    let env;
+    try { env = JSON.parse(res.stdout.trim().split('\n').pop()); } catch { continue; }
+    if (!env) continue;
+    const results = env.results || [];
+    if (results.length) {
+      const tier = env.tier ? ` [tier: ${env.tier}]` : '';
+      const shown = results.slice(0, 60);
+      const more = results.length > 60 ? ` (+${results.length - 60} more)` : '';
+      sections.push(`${verb}(${cls.symbol})${tier}: ${shown.join(', ')}${more}`);
+    } else if ((env.candidates || []).length) {
+      // ambiguous symbol (ok:false, reason:'ambiguous-function') — the candidate
+      // list IS the structural answer: the symbol exists in N places.
+      const cands = env.candidates.slice(0, 20);
+      const more = env.candidates.length > 20 ? ` (+${env.candidates.length - 20} more)` : '';
+      sections.push(`${verb}(${cls.symbol}) → defined in ${env.candidates.length} place(s): ${cands.join(', ')}${more}`);
+    }
+  }
+
+  // No graph answer → pass the grep through (don't replace with nothing).
+  if (!sections.length) passThrough();
+
+  // Build the replacement: graph answer first (labeled), original grep beneath.
+  const original = payload.tool_response || payload.tool_output || '';
+  const replacement =
+    `▸ Structural answer from the GSD-T code graph (precomputed; faster + more accurate than text grep for "where is this used"):\n` +
+    sections.map((s) => `  • ${s}`).join('\n') +
+    `\n\n─── original grep output (kept for reference) ───\n` +
+    (typeof original === 'string' ? original : JSON.stringify(original));
+
+  emitReplacement(replacement);
+}
+
+// ── stdin → main, fail-open everywhere ────────────────────────────────────────
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => { input += c; });
+process.stdin.on('end', () => {
+  let payload;
+  try { payload = JSON.parse(input); } catch { passThrough(); }
+  try { main(payload); } catch { passThrough(); }
+});
+process.stdin.on('error', () => passThrough());