@tekyzinc/gsd-t 5.22.10 → 5.23.10

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

@@ -0,0 +1,81 @@
+'use strict';
+/**
+ * gsd-t-graph-exclude.cjs — per-project exclude list for the code graph.
+ *
+ * Some repos carry large trees that are not the production application —
+ * design exports, Figma-generated component dumps, prototypes, archived
+ * scripts. They bloat the index, slow SCIP, and put look-alike symbols into
+ * who-calls. A project lists them in `.gsd-t/graph-exclude.json`:
+ *
+ *   { "exclude": ["design/", "figma-exports/**", "scripts/archive/", "**\/*.figma.tsx"] }
+ *
+ * Pattern rules (paths are repo-relative, forward slashes, matched case-insensitively):
+ *   - no `*`            → a path prefix: "design/" or "design" excludes that folder
+ *   - `*`               → any run of characters except "/"
+ *   - `**`              → any run of characters including "/"
+ *
+ * The indexer AND the freshness walker both read this module, so a file the
+ * indexer skipped never shows up as a phantom "new file" on the next query.
+ * [RULE] freshness-excludes-match-indexer-skipdirs
+ *
+ * A malformed file HALTS (throws): silently ignoring it would index exactly the
+ * trees the user asked to keep out, with nothing saying so.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EXCLUDE_FILE = path.join('.gsd-t', 'graph-exclude.json');
+const REGEX_SPECIALS = /[.+?^${}()|[\]\\]/g;
+
+function toRegex(pattern) {
+  const p = String(pattern).trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+  if (!p) return null;
+  if (!p.includes('*')) {
+    // Plain prefix: the path itself, or anything under it.
+    const base = p.replace(/\/+$/, '').replace(REGEX_SPECIALS, '\\$&');
+    return new RegExp(`^${base}(/|$)`, 'i');
+  }
+  let re = '';
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === '*' && p[i + 1] === '*') {
+      i++;
+      if (p[i + 1] === '/') { i++; re += '(?:.*/)?'; } else re += '.*';
+    } else if (c === '*') re += '[^/]*';
+    else re += c.replace(REGEX_SPECIALS, '\\$&');
+  }
+  return new RegExp(`^${re}(/|$)`, 'i');
+}
+
+function validateList(parsed) {
+  const list = parsed ? parsed.exclude : undefined;
+  if (!Array.isArray(list)) return false;
+  return list.every((x) => typeof x === 'string');
+}
+
+/**
+ * Load the project's exclude list. Throws on a malformed file.
+ * @returns {{ patterns: string[], source: string|null, isExcluded: (relPath: string) => boolean }}
+ */
+function loadGraphExcludes(projectRoot) {
+  const file = path.join(projectRoot, EXCLUDE_FILE);
+  if (!fs.existsSync(file)) return { patterns: [], source: null, isExcluded: () => false };
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { throw new Error(`${EXCLUDE_FILE} is not valid JSON (${e.message}) — fix it or delete it`); }
+  if (!validateList(parsed)) {
+    throw new Error(`${EXCLUDE_FILE} must be { "exclude": ["folder/", "glob/**", ...] }`);
+  }
+  const regexes = parsed.exclude.map(toRegex).filter(Boolean);
+  return {
+    patterns: parsed.exclude,
+    source: EXCLUDE_FILE,
+    isExcluded: (relPath) => {
+      const rel = String(relPath).split(path.sep).join('/');
+      return regexes.some((r) => r.test(rel));
+    },
+  };
+}
+
+module.exports = { loadGraphExcludes, EXCLUDE_FILE, _toRegex: toRegex };

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

@@ -220,7 +220,11 @@ function compute_touched_files(db, projectRoot) {
   }
 
   // Walk the current working tree
-  const liveFiles = walkTree(projectRoot);
+  // Same exclude list as the indexer, so an excluded file is never a phantom ADD
+  // and a newly-excluded one drops out as a DELETE. [RULE] freshness-excludes-match-indexer-skipdirs
+  const { isExcluded } = require('./gsd-t-graph-exclude.cjs').loadGraphExcludes(projectRoot);
+  const liveFiles = walkTree(projectRoot)
+    .filter((abs) => !isExcluded(path.relative(projectRoot, abs)));
 
   const liveRelSet = new Set();
   const edits = [];

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

@@ -196,18 +196,21 @@ function contentHash(absPath) {
 
 function enumerateFiles(root) {
   const results = [];
+  // Project exclude list (.gsd-t/graph-exclude.json) — ancillary trees such as
+  // design/Figma exports that are not the application. Throws on a malformed file.
+  const { isExcluded } = require('./gsd-t-graph-exclude.cjs').loadGraphExcludes(root);
   function walk(dir) {
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
     catch { return; }
     for (const e of entries) {
+      const absPath = path.join(dir, e.name);
+      const relPath = path.relative(root, absPath).split(path.sep).join('/');
       if (e.isDirectory()) {
-        if (!shouldSkipDir(e.name)) walk(path.join(dir, e.name));
+        if (!shouldSkipDir(e.name) && !isExcluded(relPath)) walk(absPath);
       } else if (e.isFile()) {
         const ext = path.extname(e.name).toLowerCase();
-        if (PARSED_EXTS.has(ext)) {
-          const absPath = path.join(dir, e.name);
-          const relPath = path.relative(root, absPath).split(path.sep).join('/');
+        if (PARSED_EXTS.has(ext) && !isExcluded(relPath)) {
           results.push({ absPath, relPath, ext });
         }
       }
@@ -404,12 +407,16 @@ function parse_and_put(absPath, relPath, options) {
       finalEntities = upgraded.entities;
       finalEdges = upgraded.edges;
     }
-  } else if (existingTier === 'compiler-accurate') {
+  } else if (existingTier === 'compiler-accurate' || existingTier === 'compiler-partial') {
     // [RULE] reindex-tier-never-silently-downgraded — no SCIP context this call
     // (e.g. a metadata-only re-index like M98's body end-line backfill). A file that
     // WAS compiler-accurate must NOT silently drop to plain floor; label it STALE-SCIP
     // so the tier reflects "previously accurate, not re-resolved" rather than a lie.
     tier = 'tree-sitter-floor-STALE-SCIP';
+  } else if (existingTier === 'tree-sitter-floor-SCIP-MISSING') {
+    // Same principle: a file SCIP never indexed stays labelled as such until a
+    // full build (with SCIP) says otherwise. [RULE] scip-missing-file-detected-never-silent
+    tier = existingTier;
   }
 
   // Normalize edges to store schema (map from parser-floor shape to store shape)
@@ -530,8 +537,12 @@ function build_index(repoRoot, options) {
   let edgeCount = 0;
   let tierFloor = 0;
   let tierUpgraded = 0;
+  let tierPartial = 0; // [RULE] scip-tier-proportional
+  let callEdges = 0;
+  let callEdgesUnresolved = 0;
   let errors = 0;
   const skippedFiles = [];
+  const scipMissing = []; // files SCIP ran for but produced no document for
 
   // Stream: parse + put each file one at a time (never accumulate the full set)
   for (const { absPath, relPath } of files) {
@@ -541,7 +552,14 @@ function build_index(repoRoot, options) {
       entityCount += result.entities.length;
       edgeCount += result.edges.length;
       if (result.tier === 'compiler-accurate') tierUpgraded++;
+      else if (result.tier === 'compiler-partial') tierPartial++;
       else tierFloor++;
+      for (const e of result.edges) {
+        if (e.kind !== 'call-site' && e.kind !== 'CALL') continue;
+        callEdges++;
+        if (String(e.target || e.dst).startsWith('UNRESOLVED#')) callEdgesUnresolved++;
+      }
+      if (result.tier === 'tree-sitter-floor-SCIP-MISSING') scipMissing.push(relPath);
       if (typeof onProgress === 'function') {
         onProgress({ file: relPath, tier: result.tier, fileCount, total: files.length });
       }
@@ -592,11 +610,23 @@ function build_index(repoRoot, options) {
     console.error(`\x1b[33m[IDX NOTICE]\x1b[0m ${scipNotice}`);
   }
 
+  // A file the SCIP indexer skipped keeps every call target unresolved, so
+  // who-calls cannot see its callers. Loud, every build — not a fallback, a
+  // report. `gsd-t graph status` repeats it. [RULE] scip-missing-file-detected-never-silent
+  if (scipMissing.length) {
+    const shown = scipMissing.slice(0, 10).join(', ');
+    warn(`${scipMissing.length} file(s) not in the SCIP index — their call edges stay unresolved ` +
+      `(tier tree-sitter-floor-SCIP-MISSING): ${shown}${scipMissing.length > 10 ? ', …' : ''}`);
+  }
+
   return {
     fileCount,
     entityCount,
     edgeCount,
-    tier: { floor: tierFloor, upgraded: tierUpgraded },
+    tier: { floor: tierFloor, upgraded: tierUpgraded, partial: tierPartial },
+    callEdges,
+    callEdgesUnresolved,
+    scipMissing,
     scipAvailable: scipActive,
     scipNotice,
     errors,
@@ -648,7 +678,11 @@ if (require.main === module) {
   });
 
   good(`Indexed ${result.fileCount} files, ${result.entityCount} entities, ${result.edgeCount} edges in ${result.durationMs}ms`);
-  good(`Tiers — floor: ${result.tier.floor}, compiler-accurate: ${result.tier.upgraded}`);
+  good(`Tiers — floor: ${result.tier.floor}, compiler-accurate: ${result.tier.upgraded}, compiler-partial: ${result.tier.partial}`);
+  if (result.callEdges) {
+    info(`Call edges unresolved: ${result.callEdgesUnresolved} of ${result.callEdges} ` +
+      `(${(100 * result.callEdgesUnresolved / result.callEdges).toFixed(1)}% — library calls such as console.log never resolve)`);
+  }
   if (result.errors > 0) warn(`${result.errors} files had parse errors (skipped)`);
 
   const envelope = {
@@ -660,6 +694,7 @@ if (require.main === module) {
     entityCount: result.entityCount,
     edgeCount: result.edgeCount,
     tier: result.tier,
+    scipMissingCount: result.scipMissing.length,
     errors: result.errors,
     durationMs: result.durationMs,
   };

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

@@ -204,6 +204,16 @@ function isTestFile(funcId, patterns) {
 // in the implFuncs coverage set.
 
 const UNRESOLVED_PREFIX = "UNRESOLVED#";
+// A file the SCIP indexer ran for but never produced a document for (see
+// gsd-t-graph-scip-upgrade.cjs). [RULE] scip-missing-file-detected-never-silent
+const SCIP_MISSING_TIER = "tree-sitter-floor-SCIP-MISSING";
+// A file SCIP indexed but where too few repo-resolvable calls resolved to call it
+// compiler-accurate. [RULE] scip-tier-proportional
+const COMPILER_PARTIAL_TIER = "compiler-partial";
+// Tiers whose call edges SCIP actually looked at. An UNRESOLVED call in one of
+// these files is SCIP saying "not a repo function" (a local, a mock, a library),
+// so it is never name-matched. [RULE] name-match-only-where-scip-never-looked
+const SCIP_BACKED_TIERS = new Set(["compiler-accurate", COMPILER_PARTIAL_TIER]);
 
 /**
  * Load records from a JSONL store directory.
@@ -379,7 +389,7 @@ function buildIndex(records, skippedFiles) {
     allFiles.add(rec.file);
     if (rec.tier) fileTier.set(rec.file, rec.tier);
 
-    if (rec.tier === "tree-sitter-floor") hasFloor = true;
+    if (rec.tier === "tree-sitter-floor" || rec.tier === SCIP_MISSING_TIER || rec.tier === COMPILER_PARTIAL_TIER) hasFloor = true;
     if (rec.tier === "tree-sitter-floor-STALE-SCIP") hasStaleScip = true;
 
     // Index entities for bare-name disambiguation + tier labeling
@@ -420,6 +430,7 @@ function buildIndex(records, skippedFiles) {
   return {
     importGraph,
     callGraph,
+    nameMatchedCallGraph: buildNameMatchedCallGraph(forwardCallEdges, funcEntities, fileTier),
     forwardCallEdges,
     funcEntities,
     allFiles,
@@ -429,6 +440,76 @@ function buildIndex(records, skippedFiles) {
   };
 }
 
+/**
+ * Name-matched reverse call edges: `UNRESOLVED#<name>` → the ONE function in the
+ * repo named <name>, for callers in files SCIP never resolved (no SCIP document,
+ * floor, stale). A labelled answer, never a compiler one: who-calls reports these
+ * callers under `nameMatched` with `resolution: "name-matched"`.
+ * A name defined 2+ times is never matched — it stays in
+ * coverage.unresolvedCallSites. [RULE] unique-name-unresolved-call-name-matched
+ * [RULE] name-match-only-where-scip-never-looked
+ *
+ * @returns {Map<string,Set<string>>} dstFuncId (both `file#name@line` and `file#name`) → callers
+ */
+function buildNameMatchedCallGraph(forwardCallEdges, funcEntities, fileTier) {
+  const byName = new Map(); // name → [funcId, ...]
+  for (const [funcId, meta] of funcEntities) {
+    if (!byName.has(meta.name)) byName.set(meta.name, []);
+    byName.get(meta.name).push(funcId);
+  }
+  const graph = new Map();
+  for (const { src, dst } of forwardCallEdges) {
+    if (!dst.startsWith(UNRESOLVED_PREFIX)) continue;
+    const defs = byName.get(dst.slice(UNRESOLVED_PREFIX.length));
+    if (!defs || defs.length !== 1) continue;
+    // [RULE] name-match-only-where-scip-never-looked: include a caller ONLY if its
+    // file was NOT SCIP-backed (not compiler-accurate or compiler-partial). Files
+    // missing from fileTier default to tree-sitter-floor (SCIP never looked), so
+    // they are included. [ISSUE] M119: files outside tsconfig have no fileTier entry
+    // yet contribute valid UNRESOLVED edges → include them.
+    const callerFile = src.split("#")[0];
+    const callerTier = fileTier.get(callerFile);
+    // A missing tier → never SCIP-backed → include it (tree-sitter-floor by default)
+    if (callerTier !== undefined && SCIP_BACKED_TIERS.has(callerTier)) continue;
+    for (const key of new Set([defs[0], defs[0].replace(/@\d+$/, "")])) {
+      if (!graph.has(key)) graph.set(key, new Set());
+      graph.get(key).add(src);
+    }
+  }
+  return graph;
+}
+
+/**
+ * Callers of `funcId` found only by name match (not already compiler callers).
+ * @returns {string[]}
+ */
+function nameMatchedCallersOf(index, funcId, compilerCallers) {
+  if (!index.nameMatchedCallGraph) return [];
+  const set = index.nameMatchedCallGraph.get(funcId) || index.nameMatchedCallGraph.get(funcId.replace(/@\d+$/, ""));
+  if (!set) return [];
+  return Array.from(set).filter((c) => !compilerCallers.has(c)).sort();
+}
+
+/**
+ * who-calls envelope: compiler callers + labelled name-matched callers. A
+ * name-matched caller leaves coverage.unresolvedCallSites (it is accounted for).
+ */
+function whoCallsResult(index, funcId, baseCoverage, identity) {
+  const compiler = index.callGraph.get(funcId) || index.callGraph.get(funcId.replace(/@\d+$/, "")) || new Set();
+  const matched = nameMatchedCallersOf(index, funcId, compiler);
+  const results = Array.from(compiler).concat(matched).sort();
+  const coverage = withUnresolvedSites(baseCoverage, index, identity, matched);
+  if (!matched.length) return { results, tier: index.tier, coverage };
+  const out = { results, tier: index.tier, coverage };
+  out.nameMatched = {
+    resolution: "name-matched",
+    note: "unresolved call sites naming the only function in the repo with this name, in files SCIP never resolved — name-matched, not compiler-resolved",
+    count: matched.length,
+    callers: matched,
+  };
+  return out;
+}
+
 // ─── Load store + build index (fail-loud on any failure) ─────────────────────
 
 /**
@@ -595,6 +676,13 @@ function loadSqliteStore(dbPath) {
       if (n.tier && n.tier !== 'compiler-accurate') r.tier = n.tier;
       else if (!r.tier) r.tier = n.tier || 'compiler-accurate';
     }
+    // The files table is where a SCIP-MISSING label lives even for a file that
+    // declares no function — so `graph status` can list every one of them.
+    if (hasFilesTable) {
+      for (const r of db.prepare("SELECT file, tier FROM files WHERE tier IN (?, ?)").all(SCIP_MISSING_TIER, COMPILER_PARTIAL_TIER)) {
+        rec(norm(r.file)).tier = r.tier;
+      }
+    }
     for (const e of edges) {
       // src for an IMPORT edge is the source FILE; for a CALL edge it's a funcId
       // (file#fn@line). The owning file record is the src's file part.
@@ -602,6 +690,15 @@ function loadSqliteStore(dbPath) {
       const dst = e.kind === "IMPORT" ? resolveDst(srcFile, e.dst) : e.dst;
       rec(srcFile).edges.push({ kind: e.kind, src: e.src, dst });
     }
+    // A file with call edges but no function node (top-level code only) got no
+    // tier from the node pass. Name matching needs to know whether SCIP looked
+    // at it, so take its tier from the files table. [RULE] name-match-only-where-scip-never-looked
+    if (hasFilesTable) {
+      for (const r of db.prepare("SELECT file, tier FROM files").all()) {
+        const f = norm(r.file);
+        if (r.tier && byFile.has(f) && !byFile.get(f).tier) byFile.get(f).tier = r.tier;
+      }
+    }
     db.close();
     return { records: Array.from(byFile.values()) };
   } catch (_e) {
@@ -733,6 +830,42 @@ function queryWhoImports(index, target) {
   return { results, tier: index.tier, coverage };
 }
 
+// ─── Unresolved call sites that name the target ──────────────────────────────
+//
+// When coverage is incomplete, the calls the graph could not resolve are still
+// in it — as `UNRESOLVED#<name>` edges from a known caller. They are NOT results
+// (a name match is not a resolved call), so they are reported inside `coverage`,
+// labelled, with the files to open. That turns "[] and incomplete" into a named
+// place to look. [RULE] incomplete-empty-answer-names-a-path-forward
+
+function unresolvedCallSitesFor(index, identity, accounted) {
+  const name = identity.split("#").pop().replace(/@\d+$/, "");
+  if (!name) return null;
+  const exact = UNRESOLVED_PREFIX + name;
+  const member = "." + name;
+  const callers = new Set();
+  for (const { src, dst } of index.forwardCallEdges) {
+    if (dst === exact || (dst.startsWith(UNRESOLVED_PREFIX) && dst.endsWith(member))) callers.add(src);
+  }
+  // A caller already reported as name-matched is accounted for, not unknown.
+  if (accounted) for (const c of accounted) callers.delete(c);
+  if (callers.size === 0) return null;
+  const sorted = Array.from(callers).sort();
+  const files = Array.from(new Set(sorted.map((c) => c.split("#")[0]))).sort();
+  return {
+    count: sorted.length,
+    note: "name-match only — these callers call something named '" + name + "' that the graph could not resolve; open these files to confirm",
+    callers: sorted.slice(0, 100),
+    files: files.slice(0, 50),
+  };
+}
+
+function withUnresolvedSites(coverage, index, identity, accounted) {
+  if (!coverage || coverage.complete !== false) return coverage;
+  const sites = unresolvedCallSitesFor(index, identity, accounted);
+  return sites ? { ...coverage, unresolvedCallSites: sites } : coverage;
+}
+
 // ─── Query: who-calls ─────────────────────────────────────────────────────────
 
 /**
@@ -755,14 +888,13 @@ function queryWhoImports(index, target) {
  */
 function queryWhoCalls(index, identity) {
   const isFuncId = identity.includes("#");
-  const coverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
+  const baseCoverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
+  const coverage = withUnresolvedSites(baseCoverage, index, identity);
 
   if (isFuncId) {
     // 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 };
+    return whoCallsResult(index, identity, baseCoverage, identity);
   }
 
   // Bare name — disambiguate against all funcIds
@@ -783,11 +915,7 @@ function queryWhoCalls(index, identity) {
     // 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 };
+    return whoCallsResult(index, matchingFuncIds[0], baseCoverage, identity);
   }
 
   // Multiple matches — ambiguous, NEVER merge
@@ -951,12 +1079,17 @@ function queryBlastRadius(index, target) {
     for (const [funcId, meta] of index.funcEntities) {
       if (meta.file === target) {
         initialFrontier.add(funcId);
+        // SCIP-resolved call edges key on `file#name` (no @line) — seed that
+        // form too, or a file's callers never enter the radius.
+        // [RULE] who-calls-funcid-line-suffix-tolerant
+        initialFrontier.add(funcId.replace(/@\d+$/, ""));
       }
     }
   }
 
   // BFS over the UNION of reverse import + call edges, transitive closure
   const visited = new Set();
+  const nameMatchedReached = new Set();
   const queue = Array.from(initialFrontier);
 
   while (queue.length > 0) {
@@ -972,10 +1105,13 @@ function queryBlastRadius(index, target) {
       }
     }
 
-    // Reverse call edges: who calls this function node?
-    const callers = index.callGraph.get(node);
-    if (callers) {
+    // Reverse call edges: who calls this function node? (compiler + name-matched;
+    // name-matched ones are listed separately below) [RULE] unique-name-unresolved-call-name-matched
+    for (const graph of [index.callGraph, index.nameMatchedCallGraph]) {
+      const callers = graph && graph.get(node);
+      if (!callers) continue;
       for (const caller of callers) {
+        if (graph !== index.callGraph && !(index.callGraph.get(node) || new Set()).has(caller)) nameMatchedReached.add(caller);
         if (!visited.has(caller)) queue.push(caller);
       }
     }
@@ -988,8 +1124,15 @@ function queryBlastRadius(index, target) {
   }
 
   const results = Array.from(visited).sort();
-  const coverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
-  return { results, tier: index.tier, coverage };
+  const matched = Array.from(nameMatchedReached).filter((c) => visited.has(c)).sort();
+  const coverage = withUnresolvedSites(
+    computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) }),
+    index, target, matched);
+  if (!matched.length) return { results, tier: index.tier, coverage };
+  return {
+    results, tier: index.tier, coverage,
+    nameMatched: { resolution: "name-matched", count: matched.length, callers: matched.slice(0, 100) },
+  };
 }
 
 // ─── Query: status ────────────────────────────────────────────────────────────
@@ -1004,7 +1147,12 @@ function queryBlastRadius(index, target) {
  * @returns {object}
  */
 function queryStatus(index, storePath) {
+  // [RULE] scip-missing-file-detected-never-silent — status names them.
+  const scipMissing = [];
+  for (const [file, tier] of index.fileTier || []) if (tier === SCIP_MISSING_TIER) scipMissing.push(file);
+  scipMissing.sort();
   return {
+    scipMissing: { count: scipMissing.length, files: scipMissing.slice(0, 50) },
     queryable: true,
     storePath,
     fileCount: index.allFiles.size,
@@ -1203,7 +1351,7 @@ function queryDeadCode(index) {
     // [RULE] orphan-tier-labeled-candidate-not-certainty:
     // Floor-tier results are CANDIDATE (a missed unresolved call could explain the absence).
     const tier = meta.tier || index.tier;
-    const isFloor = tier === "tree-sitter-floor" || tier === "tree-sitter-floor-STALE-SCIP";
+    const isFloor = tier === "tree-sitter-floor" || tier === "tree-sitter-floor-STALE-SCIP" || tier === SCIP_MISSING_TIER;
     const candidateLabel = isFloor ? "CANDIDATE" : null;
 
     results.push({ funcId, file: meta.file, tier, candidateLabel });
@@ -1346,6 +1494,32 @@ function queryTestImpl(index, options) {
   return { results: untested, tier: index.tier, mode: "untested-impl" };
 }
 
+// ─── Incomplete-empty marker (read by the M117 search guard) ──────────────────
+//
+// The search guard runs BEFORE a grep and cannot see what the graph just said.
+// When who-calls / blast-radius answers [] with coverage incomplete, record it,
+// so the guard's block message can name a path forward (the files to open, the
+// re-index) instead of leaving none. A write failure is said on stderr.
+// [RULE] incomplete-empty-answer-names-a-path-forward
+
+const INCOMPLETE_MARKER_NAME = "last-incomplete-answer.json";
+
+function writeIncompleteAnswerMarker(projectRoot, verb, target, coverage) {
+  const file = path.join(projectRoot, ".gsd-t", "graphDB", INCOMPLETE_MARKER_NAME);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({
+      ts: new Date().toISOString(),
+      verb,
+      target,
+      note: coverage.note || null,
+      unresolvedCallSites: coverage.unresolvedCallSites || null,
+    }, null, 2));
+  } catch (e) {
+    process.stderr.write("[graph] could not record the incomplete answer for the search guard (" + e.message + ")\n");
+  }
+}
+
 // ─── Public API (for tests to import directly) ────────────────────────────────
 // Tests build an index from fixture records, then call these pure functions.
 // The query CLI is the only caller of runFreshnessCheck (integration seam).
@@ -1384,6 +1558,10 @@ module.exports = {
   COUPLING_THRESHOLD,
   DEFAULT_TEST_PATTERNS,
   UNRESOLVED_PREFIX,
+  SCIP_MISSING_TIER,
+  unresolvedCallSitesFor,
+  writeIncompleteAnswerMarker,
+  INCOMPLETE_MARKER_NAME,
   getTestPatterns,
   isTestFile,
 };
@@ -1522,7 +1700,12 @@ if (require.main === module) {
       });
       process.exit(2);
     }
-    emit({ ok: true, verb, target, results: queryResult.results, tier: queryResult.tier, coverage: queryResult.coverage });
+    if (queryResult.results.length === 0 && queryResult.coverage && queryResult.coverage.complete === false) {
+      writeIncompleteAnswerMarker(_resolver.deriveProjectRoot(storePath), verb, target, queryResult.coverage);
+    }
+    const env = { ok: true, verb, target, results: queryResult.results, tier: queryResult.tier, coverage: queryResult.coverage };
+    if (queryResult.nameMatched) env.nameMatched = queryResult.nameMatched; // [RULE] unique-name-unresolved-call-name-matched
+    emit(env);
 
   } else if (verb === "body") {
     if (!target) fail({ ok: false, reason: "missing-target", verb });
@@ -1576,12 +1759,19 @@ if (require.main === module) {
 
   } else if (verb === "blast-radius") {
     if (!target) fail({ ok: false, reason: "missing-target", verb });
-    const { results, tier, coverage } = queryBlastRadius(index, target);
-    emit({ ok: true, verb, target, results, tier, coverage });
+    const { results, tier, coverage, nameMatched } = queryBlastRadius(index, target);
+    if (results.length === 0 && coverage && coverage.complete === false) {
+      writeIncompleteAnswerMarker(_resolver.deriveProjectRoot(storePath), verb, target, coverage);
+    }
+    const env = { ok: true, verb, target, results, tier, coverage };
+    if (nameMatched) env.nameMatched = nameMatched; // [RULE] unique-name-unresolved-call-name-matched
+    emit(env);
 
   } else if (verb === "status") {
     const statusData = queryStatus(index, storePath);
-    emit({ ok: true, verb: "status", ...statusData });
+    // Name the project exclude list so a missing folder is never a mystery.
+    const ex = require("./gsd-t-graph-exclude.cjs").loadGraphExcludes(_resolver.deriveProjectRoot(storePath));
+    emit({ ok: true, verb: "status", ...statusData, excludes: { source: ex.source, patterns: ex.patterns } });
 
   } else if (verb === "cluster") {
     const { results, tier } = queryCluster(index);