@tekyzinc/gsd-t 5.18.11 → 5.19.11

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.19.11] - 2026-09-15
+
+### Fixed — a broken git made the worktree prompt vanish with nothing said
+
+An Xcode update left the licence unaccepted, so every git command exited 69 with a licence
+notice. The worktree picker's first check asks "is this a git repo" and read that failure as
+a plain "no" — which is the ordinary case for most directories, so it exited silently. The
+launcher then skipped the worktree prompt entirely and started the session where it stood.
+A prompt that disappears reads as a GSD-T bug; the actual cause was git, two commands away.
+
+- `bin/gsd-t-pick-worktree.cjs`: "not a repository" and "git could not answer" are now
+  different answers. git's own exit tells them apart — a genuine non-repo says so on stderr;
+  anything else (missing binary, unaccepted licence, broken install) HALTS with what git said
+  and how to fix it. The sibling checks in `gsd-t-worktree-detect.cjs` already halted this way;
+  this one was the inconsistent member.
+- `test/m111-pick-worktree.test.js`: 3 regression tests — a licence-style failure halts, a
+  directory that is genuinely not a repo stays silent, and git missing from PATH also halts.
+
+## [5.19.10] - 2026-09-09
+
+### Added — M117 Graph Search Guard: the graph rule finally fires on the path work actually takes
+
+The rule "read code structure through the graph, never grep around it" had three enforcement
+points and all three missed. The Grep-tool hook and Read-tool hook never fire, because
+bypass-permissions mode routes every search through Bash. The runtime use-gate only runs inside
+`gsd-t verify`, so a plain conversation was never measured. The ledger recorded the result:
+2 grep events in three months, both June test probes, against 34,418 graph queries all issued by
+the graph's own tooling. Not one came from a session choosing to consult it.
+
+- `scripts/gsd-t-graph-search-guard.js`: a PreToolUse hook on Bash and Grep. Three outcomes and no
+  fourth — a structural code search BLOCKS with the graph command to run instead; a search over
+  content the graph does not index (`.md`, `.json`, `.sql`, config, prose) RUNS, because the graph
+  holds no answer to route to; a search that cannot be classified BLOCKS. No fail-open, no bypass
+  env var. A missing or unbuilt graph BLOCKS with `gsd-t graph index`, never a quiet fall back to
+  grep — that fallback is what let a project grep its way through 827 files with the graph unbuilt.
+- `bin/gsd-t-code-search-classifier.cjs`: the three-way classifier. Deliberately NOT merged with
+  `gsd-t-grep-classifier.cjs` — that one feeds a hook that replaces grep output, so unsure means
+  "let grep run"; this one feeds a guard that blocks, so unsure means block. One module cannot hold
+  both defaults, and merging them would silently pick one caller's behaviour for both.
+- `scripts/gsd-t-graph-use-report.js`: a Stop hook covering what no pattern-matcher can see — a turn
+  that answered a structural question by reading files end to end. It reports rather than blocks,
+  because a Stop hook fires after the work is done.
+- Both hooks registered by `gsd-t install`; the classifier ships in both bin registries.
+- `configureWriteEditHook` generalized to `configurePreToolUseHook` with the matcher as a parameter,
+  rather than copied for a Bash|Grep variant.
+- 17 tests in `test/m117-graph-search-guard.test.js`, including the six real searches from the
+  session that prompted this, each of which ran unchallenged at the time.
+
 ## [5.18.11] - 2026-09-07
 
 ### Fixed — `gsd-t pick-worktree --name main` refused when the main checkout sat on a feature branch

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.18.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.19.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-code-search-classifier.cjs

@@ -0,0 +1,318 @@
+/**
+ * gsd-t-code-search-classifier.cjs
+ *
+ * M117 - Decide what a shell search command is asking for, so the search guard
+ * can stop the ones the code graph should answer.
+ *
+ * THIS IS NOT gsd-t-grep-classifier.cjs, AND THE DIFFERENCE IS THE POINT.
+ * That one feeds a hook that REPLACES grep output, so an unsure answer there
+ * means "let grep run" - a wrong guess only costs a missed opportunity. This
+ * one feeds a guard that BLOCKS, and under the graph rule an unsure answer is
+ * the dangerous direction: a search that proceeds because the classifier could
+ * not decide is a search that continued past a failure, which is the fallback
+ * the No-Fallback rule bans. So the defaults are inverted here on purpose.
+ * Merging the two would force one default onto both callers and silently break
+ * whichever one it was not chosen for.
+ *
+ * Three answers, no fourth:
+ *
+ *   'structural'   asking who calls / who imports / where something is defined,
+ *                  over code. The graph answers this. BLOCK.
+ *   'content'      searching text the graph does not index - markdown, JSON,
+ *                  SQL, config, prose, comments, log output. ALLOW. This is not
+ *                  a loophole: the graph has no answer, so there is nothing to
+ *                  route to.
+ *   'unclear'      cannot tell. BLOCK, and say so. Never guessed either way.
+ *
+ * [RULE] search-classifier-unclear-blocks-never-allows
+ * [RULE] search-classifier-content-scope-is-what-graph-cannot-index
+ * [RULE] search-classifier-missing-input-is-unclear-not-content
+ *
+ * Zero dependencies. Pure - no filesystem, no spawning, no environment reads.
+ */
+
+'use strict';
+
+// --- What the graph indexes ------------------------------------------------
+// A search restricted to files OUTSIDE this set is a content search by
+// definition: the graph holds nothing about them, so it cannot be the better
+// answer. Kept as one shared constant because a second copy is where a
+// mismatch hides.
+const CODE_EXT = new Set([
+  '.js', '.cjs', '.mjs', '.jsx', '.ts', '.tsx', '.mts', '.cts',
+  '.py', '.pyi', '.go', '.rs', '.java', '.rb', '.php',
+  '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.swift', '.kt', '.scala',
+]);
+
+// Content the graph does not index, named explicitly so "it is a .md file" is a
+// decision rather than an absence of evidence.
+const CONTENT_EXT = new Set([
+  '.md', '.markdown', '.txt', '.rst',
+  '.json', '.jsonl', '.yaml', '.yml', '.toml', '.ini', '.cfg', '.conf', '.env',
+  '.sql', '.csv', '.tsv',
+  '.sh', '.bash', '.zsh', '.fish',
+  '.html', '.css', '.scss', '.less',
+  '.lock', '.log', '.xml', '.svg',
+]);
+
+// The search programs this guard governs. `find` is here for `-name`, which is
+// a "where does this live" question the graph answers.
+const SEARCH_PROGRAMS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'ripgrep', 'ag', 'ack', 'find', 'ugrep']);
+
+// Flags whose NEXT argument names a file scope.
+const SCOPE_FLAGS = new Set(['--include', '--glob', '-g', '--name', '-name', '-iname']);
+
+// Flags of the form --include=<glob>, carrying the scope inline.
+const INLINE_SCOPE_FLAGS = ['--include=', '--glob='];
+
+// A bare identifier - a function, class, or variable name and nothing else.
+const BARE_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]{1,79}$/;
+
+// A member access or call shape: Obj.method, this.method, foo(
+const MEMBER_OR_CALL = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)?\(?$/;
+
+// Declaration-hunting shapes. These ask where something is DEFINED.
+const DECLARATION_SHAPES = [
+  /^(?:async\s+)?function\s+[A-Za-z_$]/,
+  /^class\s+[A-Za-z_$]/,
+  /^def\s+[A-Za-z_$]/,
+  /^(?:export\s+)?(?:const|let|var)\s+[A-Za-z_$]/,
+  /^func\s+[A-Za-z_$]/,
+  /^(?:pub\s+)?fn\s+[A-Za-z_$]/,
+];
+
+// Import/require shapes - "who depends on this".
+const IMPORT_SHAPES = [
+  /\bimport\s/,
+  /\bfrom\s+\S+\s+import\b/,
+  /\brequire\s*\(/,
+  /\bexport\s+(?:default\s+)?(?:function|class|const)\b/,
+];
+
+// Multi-word English: an error message or a sentence, not a symbol.
+const PROSE_SHAPE = /^[A-Za-z][A-Za-z'-]*(?:\s+[A-Za-z][A-Za-z'-]*)+$/;
+
+// A run of characters shaped like an identifier.
+const IDENTIFIER_RUN = /[A-Za-z_$][A-Za-z0-9_$]{2,}/;
+
+/**
+ * Pull the file extensions a search is scoped to, from its arguments.
+ * Returns a Set; empty means "no scope stated".
+ */
+function scopedExtensions(argv) {
+  const found = new Set();
+
+  const addFrom = (s) => {
+    if (typeof s !== 'string') return;
+    // *.{js,ts} - a brace group naming several at once.
+    const brace = s.match(/\*\.\{([^}]+)\}/);
+    if (brace) {
+      for (const part of brace[1].split(',')) {
+        const e = '.' + part.trim().replace(/^\./, '');
+        if (e.length > 1) found.add(e.toLowerCase());
+      }
+      return;
+    }
+    // *.md, path/to/file.json
+    const m = s.match(/\.([A-Za-z0-9]+)$/);
+    if (m) found.add(('.' + m[1]).toLowerCase());
+  };
+
+  const inlineScopeValue = (arg) => {
+    for (const prefix of INLINE_SCOPE_FLAGS) {
+      if (arg.startsWith(prefix)) return arg.slice(prefix.length);
+    }
+    return null;
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== 'string') continue;
+
+    if (SCOPE_FLAGS.has(a)) {
+      addFrom(argv[i + 1]);
+      i++;
+      continue;
+    }
+
+    const inline = inlineScopeValue(a);
+    if (inline !== null) {
+      addFrom(inline);
+      continue;
+    }
+
+    // ripgrep -t<type> shorthand: -tmd, -tjs. Counted only when the type names
+    // an extension we know; an unknown type states no scope.
+    const typeShorthand = a.match(/^-t([a-z]+)$/);
+    if (typeShorthand) {
+      const asExt = '.' + typeShorthand[1];
+      if (CODE_EXT.has(asExt)) found.add(asExt);
+      else if (CONTENT_EXT.has(asExt)) found.add(asExt);
+      continue;
+    }
+
+    if (!a.startsWith('-')) addFrom(a);
+  }
+  return found;
+}
+
+/**
+ * Is every extension this search touches outside the graph's index?
+ * Only true when a scope was actually stated - an unscoped search reaches code
+ * whether or not the pattern looks like prose.
+ */
+function scopedEntirelyToContent(exts) {
+  if (exts.size === 0) return false;
+  for (const e of exts) {
+    if (!CONTENT_EXT.has(e)) return false;
+  }
+  return true;
+}
+
+function touchesCode(exts) {
+  for (const e of exts) {
+    if (CODE_EXT.has(e)) return true;
+  }
+  return false;
+}
+
+function asksByFileName(argv) {
+  for (const a of argv) {
+    if (a === '-name') return true;
+    if (a === '-iname') return true;
+  }
+  return false;
+}
+
+/**
+ * Classify a search.
+ *
+ * @param {object} input
+ * @param {string} input.pattern   what is being searched for
+ * @param {string[]} [input.argv]  the rest of the command's arguments
+ * @param {string} [input.program] grep | rg | find | ...
+ * @returns {{ verdict:'structural'|'content'|'unclear',
+ *             reason:string, symbol:string|null, verb:string|null }}
+ */
+function classifySearch(input) {
+  // A caller that hands over no pattern has not asked a question this can
+  // answer. Reporting 'content' would ALLOW the search on the strength of an
+  // input that never arrived - deciding by absence of evidence. It is unclear,
+  // and unclear blocks.
+  if (!input) return unclear('no input was given');
+  if (typeof input.pattern !== 'string') return unclear('no search pattern was given');
+  const pattern = input.pattern.trim();
+  if (!pattern) return unclear('the search pattern was empty');
+
+  const argv = Array.isArray(input.argv) ? input.argv : [];
+  const program = typeof input.program === 'string' ? input.program : 'grep';
+
+  const exts = scopedExtensions(argv);
+
+  // Scoped entirely to things the graph does not index. The graph has no
+  // answer, so there is nothing to route to.
+  if (scopedEntirelyToContent(exts)) {
+    return {
+      verdict: 'content',
+      reason: 'scoped to ' + [...exts].join(', ') + ' - the graph does not index these',
+      symbol: null,
+      verb: null,
+    };
+  }
+
+  // `find -name Foo.js` asks where a file lives. The graph knows.
+  if (program === 'find' && asksByFileName(argv) && touchesCode(exts)) {
+    return {
+      verdict: 'structural',
+      reason: 'locating a code file by name',
+      symbol: pattern.replace(/^\*/, '').replace(/\*$/, ''),
+      verb: 'defines',
+    };
+  }
+
+  // Unmistakable prose: several English words. The graph indexes symbols and
+  // edges, not sentences.
+  if (PROSE_SHAPE.test(pattern) && pattern.split(/\s+/).length >= 3) {
+    return { verdict: 'content', reason: 'a phrase, not a symbol', symbol: null, verb: null };
+  }
+
+  // A quoted string literal hunted through the codebase is content.
+  if (/^["'].*["']$/.test(pattern) && pattern.length > 12) {
+    return { verdict: 'content', reason: 'a string literal', symbol: null, verb: null };
+  }
+
+  // --- Structural shapes ---------------------------------------------------
+  for (const re of IMPORT_SHAPES) {
+    if (re.test(pattern)) {
+      return {
+        verdict: 'structural',
+        reason: 'asking who imports or requires something',
+        symbol: extractSymbol(pattern),
+        verb: 'who-imports',
+      };
+    }
+  }
+
+  for (const re of DECLARATION_SHAPES) {
+    if (re.test(pattern)) {
+      return {
+        verdict: 'structural',
+        reason: 'asking where something is defined',
+        symbol: extractSymbol(pattern),
+        verb: 'defines',
+      };
+    }
+  }
+
+  if (BARE_IDENT.test(pattern)) {
+    return {
+      verdict: 'structural',
+      reason: 'a bare symbol name - who calls it and who imports it is a graph question',
+      symbol: pattern,
+      verb: 'who-calls',
+    };
+  }
+
+  if (MEMBER_OR_CALL.test(pattern)) {
+    return {
+      verdict: 'structural',
+      reason: 'a call or member-access shape',
+      symbol: pattern.replace(/\($/, ''),
+      verb: 'who-calls',
+    };
+  }
+
+  // --- Everything left -----------------------------------------------------
+  // A regex, a mixed pattern, something with punctuation. It MIGHT be a text
+  // search and it might be a symbol hunt wearing a regex. Saying "probably
+  // text" here is the guess this classifier exists not to make.
+  //
+  // One narrowing first: a pattern holding no identifier-shaped run has nothing
+  // the graph could be asked about, whatever else it is.
+  if (!IDENTIFIER_RUN.test(pattern)) {
+    return {
+      verdict: 'content',
+      reason: 'no symbol-shaped text in the pattern',
+      symbol: null,
+      verb: null,
+    };
+  }
+
+  return unclear('could be a symbol hunt or a text search - it has to be said which');
+}
+
+function unclear(reason) {
+  return { verdict: 'unclear', reason, symbol: null, verb: null };
+}
+
+// Pull the most likely symbol out of a declaration/import pattern, for the
+// suggested graph command. Null when nothing identifier-shaped is present.
+function extractSymbol(pattern) {
+  const trailing = pattern.match(/([A-Za-z_$][A-Za-z0-9_$]{1,})\s*$/);
+  if (trailing) return trailing[1];
+  const anywhere = pattern.match(/([A-Za-z_$][A-Za-z0-9_$]{1,})/);
+  if (anywhere) return anywhere[1];
+  return null;
+}
+
+module.exports = { classifySearch, CODE_EXT, CONTENT_EXT, SEARCH_PROGRAMS };

package/bin/gsd-t-pick-worktree.cjs

@@ -208,9 +208,50 @@ function isSwitchedOff(cwd) {
   return cfg.enabled === false;
 }
 
-// Most directories are not git repos. That is ordinary, not a failure.
+/**
+ * Is this directory a git repo?
+ *
+ * "No" and "git could not tell me" are DIFFERENT answers and must not collapse
+ * into one. Most directories are genuinely not repos, which is ordinary and
+ * silent. But a git that cannot run at all fails the same probe, and reading
+ * that as "not a repo" makes the whole picker exit silently — the launcher then
+ * skips the worktree prompt entirely and starts the session wherever it stood,
+ * with nothing said. That happened for real on 2026-09-15: an Xcode update left
+ * the license unaccepted, every git command exited 69, and `cc` quietly stopped
+ * asking. The prompt vanishing looked like a GSD-T bug for as long as it took to
+ * run git by hand.
+ *
+ * git distinguishes them itself: a plain "not a repository" exits 128 with that
+ * message on stderr. Anything else — a missing binary, an unaccepted licence, a
+ * broken install — is git failing to answer, and that HALTS with what git said.
+ */
 function isGitRepo(dir) {
-  return spawnSync("git", ["rev-parse", "--git-dir"], { cwd: dir, stdio: "pipe" }).status === 0;
+  const r = spawnSync("git", ["rev-parse", "--git-dir"], {
+    cwd: dir, encoding: "utf8", timeout: 10000,
+  });
+
+  if (r.status === 0) return true;
+
+  // git never ran: no binary on PATH, or it could not be spawned.
+  if (r.error) {
+    fail(
+      `git could not be run (${r.error.message}), so it cannot be told whether ` +
+      `${dir} is a repository. Fix git, then start the session again.`
+    );
+  }
+
+  const stderr = String(r.stderr || "").trim();
+
+  // The ordinary answer: this is simply not a repository.
+  if (/not a git repository/i.test(stderr)) return false;
+
+  // Anything else is git declining to answer, not an answer.
+  fail(
+    `git could not say whether ${dir} is a repository — it exited ${r.status}` +
+    (stderr ? ` saying: ${stderr}` : " with no message") + ".\n" +
+    `Until git works, the worktree prompt cannot run. Fix the cause above, then ` +
+    `start the session again.`
+  );
 }
 
 // Shared with branch-guard so the two cannot drift apart — see

package/bin/gsd-t.js

@@ -514,6 +514,24 @@ const FALLBACK_HOOK_MARKER = "gsd-t-fallback-guard";
 const FALLBACK_HOOK_COMMAND =
   'node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-fallback-guard.js"';
 
+// ─── M117 Graph search guard (PreToolUse Bash|Grep) ─────────────────────────
+// Blocks a search that asks a structural question about code, and names the
+// graph command that answers it. NO `|| true`, for the same reason as the
+// fallback guard: a missing script must fail loudly, not silently re-open the
+// hole. The hole it closes is specific — the Grep-tool and Read-tool hooks
+// never fired, because bypass mode routes every search through Bash.
+const GRAPH_SEARCH_HOOK_MARKER = "gsd-t-graph-search-guard";
+const GRAPH_SEARCH_HOOK_COMMAND =
+  'node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-search-guard.js"';
+
+// ─── M117 Graph use report (Stop) ───────────────────────────────────────────
+// Reports a turn that hit structural questions and never asked the graph. It
+// reports rather than blocks: a Stop hook fires after the work is done, so
+// blocking there punishes rather than redirects. Prevention is the guard above.
+const GRAPH_USE_REPORT_MARKER = "gsd-t-graph-use-report";
+const GRAPH_USE_REPORT_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-use-report.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-use-report.js" || true\'';
+
 // ─── M108 Install self-heal (SessionStart) ──────────────────────────────────
 // Checks the project's tools before any work starts, restores what is missing,
 // and reports what it could not fix. Not a fallback — it repairs the failure
@@ -992,6 +1010,69 @@ function configureFallbackGuardHook(settingsPath) {
   return configureWriteEditHook(settingsPath, FALLBACK_HOOK_MARKER, FALLBACK_HOOK_COMMAND, "fallback guard");
 }
 
+// M117 — register the graph search guard on Bash|Grep. Both doors: bypass mode
+// routes searches through Bash, and leaving either open makes it the habit.
+function configureGraphSearchGuardHook(settingsPath) {
+  return configurePreToolUseHook(
+    settingsPath, GRAPH_SEARCH_HOOK_MARKER, GRAPH_SEARCH_HOOK_COMMAND,
+    "graph search guard", "Bash|Grep"
+  );
+}
+
+// M117 — register the Stop-time graph use report.
+function configureGraphUseReportHook(settingsPath) {
+  return configureStopHook(
+    settingsPath, GRAPH_USE_REPORT_MARKER, GRAPH_USE_REPORT_COMMAND, "graph use report"
+  );
+}
+
+// Register a Stop hook by marker. Same find-refresh-or-add shape as the
+// PreToolUse registrar; Stop entries carry no matcher.
+function configureStopHook(settingsPath, marker, command, label) {
+  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 ${label} hook`);
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.Stop) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h || typeof h.command !== "string") continue;
+      if (h.command === command || h.command.includes(marker)) {
+        found = true;
+        if (h.command !== command) { h.command = command; action = "updated"; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.Stop.push({ hooks: [{ type: "command", command }] });
+    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 };
+}
+
 // M107 RETIRED (v5.11.15). The rewriter shortened a reply after it was written,
 // and a Stop hook cannot unsay what is already on screen — so David read the
 // long version, then the short one. It also cost a whole extra turn, and its
@@ -1097,6 +1178,13 @@ function configureEventHook(settingsPath, event, marker, command, label) {
 }
 
 function configureWriteEditHook(settingsPath, marker, command, label) {
+  return configurePreToolUseHook(settingsPath, marker, command, label, "Write|Edit");
+}
+
+// M117 — the same registrar, with the matcher named rather than assumed. The
+// graph search guard watches Bash|Grep, not Write|Edit, and a second copy of
+// this function is where the two would drift apart.
+function configurePreToolUseHook(settingsPath, marker, command, label, matcher) {
   const targetPath = settingsPath || SETTINGS_JSON;
   let settings = {};
   if (fs.existsSync(targetPath)) {
@@ -1121,13 +1209,13 @@ function configureWriteEditHook(settingsPath, marker, command, label) {
       if (h.command === cmd || h.command.includes(marker)) {
         found = true;
         if (h.command !== cmd) { h.command = cmd; action = "updated"; }
-        if (entry.matcher !== "Write|Edit") { entry.matcher = "Write|Edit"; action = action === "noop" ? "updated" : action; }
+        if (entry.matcher !== matcher) { entry.matcher = matcher; action = action === "noop" ? "updated" : action; }
       }
     }
   }
   if (!found) {
     settings.hooks.PreToolUse.push({
-      matcher: "Write|Edit",
+      matcher,
       hooks: [{ type: "command", command: cmd }],
     });
     action = "added";
@@ -1806,6 +1894,9 @@ const GLOBAL_BIN_TOOLS = [
   // write rather than allowing it unchecked, so an omission here breaks every
   // Write/Edit rather than failing silently. Also in PROJECT_BIN_TOOLS below.
   "gsd-t-fallback-detect.cjs",
+  // M117 — Search classifier. The graph search guard resolves it from the
+  // package when a project has no copy, so it must ship globally too.
+  "gsd-t-code-search-classifier.cjs",
   // M108 — Install self-check, run by the SessionStart hook and by
   // `gsd-t install-check`.
   "gsd-t-install-check.cjs",
@@ -2346,6 +2437,25 @@ async function doInstall(opts = {}) {
   }
 
 
+  // M117 — the graph search guard and its Stop-time report. The graph rule had
+  // three enforcement points before this and all three missed the path actually
+  // taken: the Grep-tool and Read-tool hooks never fire in bypass mode (every
+  // search goes out through Bash), and the runtime use-gate only runs inside
+  // verify, never in a plain conversation.
+  const gsHook = configureGraphSearchGuardHook(SETTINGS_JSON);
+  if (gsHook.installed) {
+    if (gsHook.action === "added") success("Graph search guard added (blocks a structural code search, names the graph query — M117)");
+    else if (gsHook.action === "updated") success("Graph search guard refreshed");
+    else info("Graph search guard already configured");
+  }
+
+  const gurHook = configureGraphUseReportHook(SETTINGS_JSON);
+  if (gurHook.installed) {
+    if (gurHook.action === "added") success("Graph use report added (flags a turn that did structural work without asking the graph — M117)");
+    else if (gurHook.action === "updated") success("Graph use report refreshed");
+    else info("Graph use report already configured");
+  }
+
   const ccHook = removeConciseHook(SETTINGS_JSON);
   if (ccHook.removed) success("Concise-rewrite hook removed — retired in v5.11.15");
 
@@ -3507,6 +3617,11 @@ const PROJECT_BIN_TOOLS = [
   // and it reads the project's OWN .gsd-t/graphDB/logs ledger, so it must live
   // in the project — [[project_global_bin_propagation_gap]].
   "gsd-t-graph-use-gate.cjs",
+  // M117 — Search classifier for the graph search guard. The PreToolUse guard
+  // prefers the project-local copy and DENIES every search if it cannot load
+  // one, so an omission here blocks all work rather than failing quietly —
+  // [[project_global_bin_propagation_gap]].
+  "gsd-t-code-search-classifier.cjs",
   // M107 — Concise rewriter, invoked by the Stop hook.
   // M108 — Install self-check. Every project carries its own copy so it can
   // verify and repair itself even when the global install is what broke.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.18.11",
+  "version": "5.19.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-search-guard.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-search-guard.js
+ *
+ * M117 - PreToolUse hook on Bash and Grep. Blocks a search that asks a
+ * structural question about code, and names the graph command that answers it.
+ *
+ * [RULE] search-guard-blocks-structural-code-search
+ * [RULE] search-guard-unclear-blocks-never-allows
+ * [RULE] search-guard-missing-graph-blocks-never-degrades
+ *
+ * WHY THIS EXISTS
+ *   The graph rule already said "query the graph, do not grep around it", and
+ *   two hooks already enforced it - on the Grep tool and the Read tool. Neither
+ *   ever fired in real work. In bypass-permissions mode the standing house rule
+ *   is to work through Bash, so every structural search went out as `grep` in a
+ *   Bash call and sailed past both hooks. The ledger records the result: two
+ *   grep events in three months, both from June test probes, against 34,418
+ *   graph queries all from the graph's own tooling. The rule had no trigger on
+ *   the path actually taken.
+ *
+ * THE THREE OUTCOMES (there is no fourth, and none of them continues past a
+ * failure):
+ *   structural  BLOCK. Print the graph command to run instead.
+ *   content     ALLOW. Markdown, JSON, SQL, config, prose - the graph does not
+ *               index them, so it has no answer to route to. Not a bypass.
+ *   unclear     BLOCK. The classifier could not read the intent, and guessing
+ *               "probably text" is the guess that keeps the rule toothless.
+ *
+ * A MISSING OR BROKEN GRAPH ALSO BLOCKS. Allowing the grep because the graph is
+ * unavailable is the exact fallback that hid the binvoice failure - a project
+ * grepping its way through 827 files while the graph sat unbuilt. The answer is
+ * `gsd-t graph index`, which the block message says.
+ *
+ * WHAT IT CANNOT SEE, STATED PLAINLY: it governs tool calls, not reasoning.
+ * Reading a file end to end to work out who calls something leaves no pattern
+ * for any guard to match. The Stop-time check (gsd-t-graph-use-report.js) is
+ * what covers that, by comparing structural work against graph queries issued.
+ *
+ * --- Stdin (Claude Code PreToolUse payload) --------------------------------
+ *   { "tool_name": "Bash"|"Grep", "cwd": "...",
+ *     "tool_input": { "command": "..." } | { "pattern": "...", "glob": "..." } }
+ *
+ * --- Decision contract -----------------------------------------------------
+ *   Deny:  {"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ *           "permissionDecision":"deny","permissionDecisionReason":"..."}}
+ *   Allow: exit 0, no output.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }) + "\n");
+  process.exit(0);
+}
+
+function allow() { process.exit(0); }
+
+/**
+ * Locate the classifier. A project without one has an incomplete install, and
+ * the repair is `gsd-t install-check` - not a hunt for a copy elsewhere, and
+ * not silently letting every search through.
+ */
+function findClassifier(projectDir) {
+  const inProject = path.join(projectDir, "bin", "gsd-t-code-search-classifier.cjs");
+  if (fs.existsSync(inProject)) return inProject;
+
+  const inPackage = path.join(__dirname, "..", "bin", "gsd-t-code-search-classifier.cjs");
+  if (fs.existsSync(inPackage)) return inPackage;
+
+  throw new Error(
+    "This project has no copy of the search classifier at " + inProject + ", which " +
+    "means its GSD-T install is incomplete. Run 'gsd-t install-check' to repair it."
+  );
+}
+
+/** Thrown when the settings file exists but cannot be understood. */
+class ConfigUnreadable extends Error {}
+
+/**
+ * Is the guard switched on for this project?
+ * An unreadable settings file throws - assuming "on" or "off" would be a guess
+ * about what the project wanted. Only an ABSENT file means on, because absence
+ * is unambiguous.
+ */
+function isEnabled(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "graph-search-gate.json");
+  if (!fs.existsSync(p)) return true;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new ConfigUnreadable(p + " could not be read: " + e.message);
+  }
+  const cfg = JSON.parse(raw);
+  return cfg.enabled !== false;
+}
+
+// --- Command parsing -------------------------------------------------------
+//
+// Split a shell command into its pipeline stages, then look at each stage that
+// runs a search program. A structural search buried in the middle of a pipe is
+// still a structural search.
+
+const SEARCH_PROGRAMS = new Set(["grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack", "find", "ugrep"]);
+
+// Flags that take a value in the NEXT argument, so that value is not the pattern.
+const FLAGS_TAKING_VALUE = new Set([
+  "-e", "--regexp", "-f", "--file", "--include", "--exclude", "--glob", "-g",
+  "-m", "--max-count", "-A", "-B", "-C", "--after-context", "--before-context",
+  "--context", "-d", "--directories", "--color", "--colour", "-t", "--type",
+  "-name", "-iname", "-path", "-type", "-maxdepth", "-mindepth",
+]);
+
+/**
+ * Break a command line into tokens, keeping quoted runs together and dropping
+ * the quotes. Good enough for reading a search invocation; it is not a shell.
+ */
+function tokenize(command) {
+  const tokens = [];
+  let cur = "";
+  let quote = null;
+  let started = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+
+    if (quote) {
+      if (ch === quote) { quote = null; continue; }
+      cur += ch;
+      started = true;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
+    if (ch === "\\" && i + 1 < command.length) { cur += command[i + 1]; started = true; i++; continue; }
+    if (/\s/.test(ch)) {
+      if (started) { tokens.push(cur); cur = ""; started = false; }
+      continue;
+    }
+    cur += ch;
+    started = true;
+  }
+  if (started) tokens.push(cur);
+  return tokens;
+}
+
+/** Split a token list on shell stage separators. */
+function pipelineStages(tokens) {
+  const SEPARATORS = new Set(["|", "||", "&&", ";", "&"]);
+  const stages = [];
+  let cur = [];
+  for (const t of tokens) {
+    if (SEPARATORS.has(t)) {
+      if (cur.length) stages.push(cur);
+      cur = [];
+      continue;
+    }
+    cur.push(t);
+  }
+  if (cur.length) stages.push(cur);
+  return stages;
+}
+
+
+// --- Where the pattern sits, one reader per spelling -----------------------
+
+function hasExplicitRegexpFlag(argv) {
+  for (const a of argv) {
+    if (a === "-e") return true;
+    if (a === "--regexp") return true;
+  }
+  return false;
+}
+
+function patternFromRegexpFlag(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-e" || argv[i] === "--regexp") return argv[i + 1];
+  }
+  return null;
+}
+
+function patternFromNameFlag(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-name" || argv[i] === "-iname") return argv[i + 1];
+  }
+  return null;
+}
+
+function firstPositional(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (FLAGS_TAKING_VALUE.has(a)) { i++; continue; }
+    if (a.startsWith("-")) continue;
+    return a;
+  }
+  return null;
+}
+
+/**
+ * From one pipeline stage, work out the search program and its pattern.
+ * Returns null when the stage runs no search program.
+ */
+function readSearchStage(stage) {
+  let idx = 0;
+
+  // Step past environment assignments and common prefixes.
+  while (idx < stage.length) {
+    const t = stage[idx];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) { idx++; continue; }
+    if (t === "sudo" || t === "command" || t === "time" || t === "xargs") { idx++; continue; }
+    break;
+  }
+  if (idx >= stage.length) return null;
+
+  const program = path.basename(stage[idx]);
+  if (!SEARCH_PROGRAMS.has(program)) return null;
+
+  const argv = stage.slice(idx + 1);
+
+  // Where the pattern sits depends only on how the command was spelled. These
+  // are three SPELLINGS of the same argument, not three attempts with earlier
+  // ones falling back to later ones: `find` always carries it after -name,
+  // grep-family tools carry it after -e when that flag is used and positionally
+  // otherwise. Which reader applies is decided up front, from the command
+  // itself, so nothing here substitutes for a value that went missing.
+  const pattern = program === "find"
+    ? patternFromNameFlag(argv)
+    : (hasExplicitRegexpFlag(argv) ? patternFromRegexpFlag(argv) : firstPositional(argv));
+
+  // A search program was invoked but no pattern could be read out of it. That
+  // is NOT "no search here" - it is a search this guard could not inspect, and
+  // reporting null would let it run unexamined. It is returned as unreadable so
+  // the caller blocks and says so.
+  if (typeof pattern !== "string") {
+    return { program, pattern: null, argv, unreadable: true };
+  }
+  return { program, pattern, argv, unreadable: false };
+}
+
+// --- Graph availability ----------------------------------------------------
+//
+// A structural question needs a graph to answer it. No graph is a BLOCK with
+// "build it", never a quiet permission to grep instead.
+
+function graphStorePath(projectDir) {
+  const candidates = [
+    path.join(projectDir, ".gsd-t", "graphDB", "graph.db"),
+    path.join(projectDir, ".gsd-t", "graph.db"),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function buildNoGraphReason(found, cls) {
+  return [
+    "This is a structural question about code, and this project has no code graph built.",
+    "",
+    "  searching for: " + found.pattern,
+    "  which is:      " + cls.reason,
+    "",
+    "Build the graph, then ask it:",
+    "",
+    "  gsd-t graph index",
+    "",
+    "Grepping instead would answer a question about relationships by matching text,",
+    "which is a different and wrong answer. A missing graph is a repairable condition,",
+    "not a reason to fall back to grep.",
+  ].join("\n");
+}
+
+function buildStructuralReason(found, cls) {
+  const lines = [];
+
+  const symbol = cls.symbol === null ? found.pattern : cls.symbol;
+  const verb = cls.verb === null ? "who-calls" : cls.verb;
+
+  lines.push(
+    "This is a structural question about code. The graph answers it; grep only matches text.",
+    "",
+    "  searching for: " + found.pattern,
+    "  which is:      " + cls.reason,
+    "",
+    "Ask the graph instead:",
+    "",
+    "  gsd-t graph " + verb + " " + symbol,
+    "",
+    "Other verbs: who-imports, who-calls, defines, blast-radius, body.",
+    "",
+    "If this really is a text search - a phrase in prose, a key in config, a string in a",
+    "document - scope it to the files the graph does not index, and it will run:",
+    "",
+    "  grep --include='*.md' --include='*.json' ..."
+  );
+  return lines.join("\n");
+}
+
+function buildUnclearReason(found, cls) {
+  return [
+    "This search could be asking about code structure, and that has to be settled before",
+    "it runs - a guess in either direction is how the graph rule stopped having teeth.",
+    "",
+    "  searching for: " + found.pattern,
+    "  why unclear:   " + cls.reason,
+    "",
+    "Say which it is:",
+    "",
+    "  Structure (who calls, who imports, where defined):",
+    "    gsd-t graph who-calls <symbol>",
+    "",
+    "  Text in files the graph does not index (.md, .json, .sql, config, prose):",
+    "    add --include='*.md' (or the right extensions) and run it again",
+  ].join("\n");
+}
+
+
+// --- Recording the decision ------------------------------------------------
+//
+// One line per block, into the same ledger the graph's own tooling writes. The
+// Stop-time report reads these to spot a turn that hit structural questions and
+// never asked the graph. Writing it must never change the decision, so a sink
+// failure is swallowed here and nowhere else in this file.
+
+function recordBlock(projectDir, program, pattern, verdict) {
+  try {
+    const dir = path.join(projectDir, ".gsd-t", "graphDB", "logs");
+    if (!fs.existsSync(dir)) return;
+    let names = fs.readdirSync(dir)
+      .filter((n) => n.startsWith("graph-events-") && n.endsWith(".jsonl"));
+    if (names.length === 0) return;
+    names.sort();
+    const file = path.join(dir, names[names.length - 1]);
+    const line = JSON.stringify({
+      kind: "search-blocked",
+      ts: new Date().toISOString(),
+      program,
+      verdict,
+      patternShape: String(pattern).slice(0, 120),
+      consumer: "search-guard",
+    });
+    fs.appendFileSync(file, line + "\n");
+  } catch (e) {
+    // The block still happens - the decision is made above and does not depend
+    // on this record. But the failure is SAID, not swallowed: the Stop-time
+    // report reads these lines, so a ledger that silently stopped accepting
+    // them would make that report quietly under-count and look clean.
+    // stderr, because stdout carries the permission decision.
+    process.stderr.write(
+      "[GSD-T GRAPH] the search-block record could not be written (" + e.message + "). " +
+      "The search was still blocked; the Stop-time graph-use report will under-count.\n"
+    );
+  }
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+  process.stdin.on("end", () => {
+    if (done) return;
+    done = true;
+    decide(input);
+  });
+
+  // A payload that never arrives is not a search to judge. Exiting 0 here is
+  // "nothing was asked", not "a failure was ignored".
+  setTimeout(() => {
+    if (done) return;
+    done = true;
+    decide(input);
+  }, 4000);
+}
+
+function decide(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    // No readable payload means no search to classify. Not applicable.
+    allow();
+    return;
+  }
+
+  const toolName = payload.tool_name;
+  if (toolName !== "Bash" && toolName !== "Grep") { allow(); return; }
+
+  const projectDir = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+
+  // Not a GSD-T project - this rule is GSD-T's, so it does not apply.
+  if (!fs.existsSync(path.join(projectDir, ".gsd-t"))) { allow(); return; }
+
+  let enabled;
+  try {
+    enabled = isEnabled(projectDir);
+  } catch (e) {
+    deny(
+      "The graph-search gate's settings could not be read, so it cannot be known whether " +
+      "this search is allowed: " + e.message + "\n\n" +
+      "Fix or delete .gsd-t/graph-search-gate.json."
+    );
+    return;
+  }
+  if (!enabled) { allow(); return; }
+
+  let classifySearch;
+  try {
+    const mod = require(findClassifier(projectDir));
+    classifySearch = mod.classifySearch;
+  } catch (e) {
+    deny("The graph-search gate could not load its classifier: " + e.message);
+    return;
+  }
+
+  // Gather the search stages this call would run.
+  const found = [];
+  if (toolName === "Grep") {
+    const gi = payload.tool_input;
+    if (!gi) { allow(); return; }
+    const argv = [];
+    if (typeof gi.glob === "string") { argv.push("--glob", gi.glob); }
+    if (typeof gi.path === "string") { argv.push(gi.path); }
+    if (typeof gi.type === "string") { argv.push("-t" + gi.type); }
+    if (typeof gi.pattern !== "string") { allow(); return; }
+    found.push({ program: "rg", pattern: gi.pattern, argv });
+  } else {
+    const command = payload.tool_input === undefined ? undefined : payload.tool_input.command;
+    if (typeof command !== "string") { allow(); return; }
+    for (const stage of pipelineStages(tokenize(command))) {
+      const s = readSearchStage(stage);
+      if (s !== null) found.push(s);
+    }
+  }
+
+  if (found.length === 0) { allow(); return; }
+
+  const hasGraph = graphStorePath(projectDir) !== null;
+
+  for (const f of found) {
+    // A search whose pattern could not be read is a search that cannot be
+    // judged. It blocks: letting it through would be deciding it is safe on
+    // the strength of evidence that could not be gathered.
+    if (f.unreadable === true) {
+      deny(
+        "A " + f.program + " search was invoked but this guard could not read what it " +
+        "searches for, so it cannot tell whether the code graph should answer it instead.\n\n" +
+        "Rewrite it so the pattern is a plain argument (or use -e <pattern>), or ask the " +
+        "graph directly:\n\n  gsd-t graph who-calls <symbol>"
+      );
+      return;
+    }
+
+    let cls;
+    try {
+      cls = classifySearch({ pattern: f.pattern, argv: f.argv, program: f.program });
+    } catch (e) {
+      deny("The graph-search gate could not classify this search: " + e.message);
+      return;
+    }
+
+    if (cls.verdict === "structural") {
+      recordBlock(projectDir, f.program, f.pattern, "structural");
+      if (hasGraph) deny(buildStructuralReason(f, cls));
+      else deny(buildNoGraphReason(f, cls));
+      return;
+    }
+    if (cls.verdict === "unclear") {
+      recordBlock(projectDir, f.program, f.pattern, "unclear");
+      deny(buildUnclearReason(f, cls));
+      return;
+    }
+  }
+
+  allow();
+}
+
+main();

package/scripts/gsd-t-graph-use-report.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-use-report.js
+ *
+ * M117 - A Stop hook. At the end of a turn it compares the structural work the
+ * session did against the graph queries it issued, and says so when the two do
+ * not match.
+ *
+ * [RULE] use-report-measures-behaviour-not-code-shape
+ * [RULE] use-report-never-blocks-it-reports
+ *
+ * WHY A SECOND MECHANISM
+ *   The PreToolUse guard (gsd-t-graph-search-guard.js) blocks structural
+ *   SEARCHES. It governs tool calls, which is all a pattern-matcher can see.
+ *   It cannot see a session that read six files end to end and worked out the
+ *   call graph by eye - there is no grep to catch, and no code shape a static
+ *   scan could find. That is the same blind spot gsd-t-graph-use-gate.cjs was
+ *   built for, and for the same reason: only the runtime ledger records what a
+ *   session actually did.
+ *
+ *   This is the conversational counterpart of that gate. The gate runs inside
+ *   `gsd-t verify`, so it only ever sees workflow runs; most work is a plain
+ *   conversation, which nothing was measuring.
+ *
+ * WHAT IT DOES NOT DO
+ *   It does not block, and it is not a gate. A Stop hook fires after the work
+ *   is finished, so blocking there would punish work already done rather than
+ *   redirect it. It reports - into the ledger always, and to the session when
+ *   the mismatch is worth saying out loud. Prevention is the guard's job.
+ *
+ * --- Stdin (Claude Code Stop payload) --------------------------------------
+ *   { "cwd": "...", "session_id": "...", ... }
+ *
+ * --- Output ----------------------------------------------------------------
+ *   Exit 0 always. When there is something to say, one line on stdout.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+// How far back a "this turn" window reaches. A turn is minutes, not hours.
+const WINDOW_MS = 30 * 60 * 1000;
+
+function quiet() { process.exit(0); }
+
+function say(message) {
+  process.stdout.write(message + "\n");
+  process.exit(0);
+}
+
+function ledgerPath(projectDir) {
+  const dir = path.join(projectDir, ".gsd-t", "graphDB", "logs");
+  if (!fs.existsSync(dir)) return null;
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.startsWith("graph-events-") && n.endsWith(".jsonl"));
+  } catch {
+    return null;
+  }
+  if (names.length === 0) return null;
+  names.sort();
+  return path.join(dir, names[names.length - 1]);
+}
+
+/**
+ * Read the tail of a file without loading all of it. The graph ledger reaches
+ * tens of megabytes, and a Stop hook must not stall a turn.
+ */
+function tailLines(file, maxBytes) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = size > maxBytes ? size - maxBytes : 0;
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, start);
+    const text = buf.toString("utf8");
+    const lines = text.split("\n");
+    if (start > 0) lines.shift(); // the first line is probably cut in half
+    return lines;
+  } catch {
+    return null;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Count what happened inside the window: graph queries issued, and structural
+ * searches the guard blocked.
+ */
+function readRecentActivity(file, sinceMs) {
+  const lines = tailLines(file, 2 * 1024 * 1024);
+  if (lines === null) return null;
+
+  let queries = 0;
+  let blockedStructural = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let ev;
+    try {
+      ev = JSON.parse(trimmed);
+    } catch {
+      continue; // a half-written line at the tail; the next run reads it whole
+    }
+    const ts = Date.parse(ev.ts);
+    if (!Number.isFinite(ts)) continue;
+    if (ts < sinceMs) continue;
+
+    if (ev.kind === "query") queries++;
+    if (ev.kind === "search-blocked") blockedStructural++;
+  }
+
+  return { queries, blockedStructural };
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+  process.stdin.on("end", () => {
+    if (done) return;
+    done = true;
+    report(input);
+  });
+
+  setTimeout(() => {
+    if (done) return;
+    done = true;
+    report(input);
+  }, 3000);
+}
+
+function report(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    quiet();
+    return;
+  }
+
+  const projectDir = typeof payload.cwd === "string" ? payload.cwd : process.cwd();
+  if (!fs.existsSync(path.join(projectDir, ".gsd-t"))) { quiet(); return; }
+
+  const file = ledgerPath(projectDir);
+  if (file === null) { quiet(); return; }
+
+  const activity = readRecentActivity(file, Date.now() - WINDOW_MS);
+  if (activity === null) { quiet(); return; }
+
+  // The guard stopped structural searches this turn and the graph was never
+  // asked. Something structural was wanted and answered another way.
+  if (activity.blockedStructural > 0 && activity.queries === 0) {
+    say(
+      "[GSD-T GRAPH] " + activity.blockedStructural + " structural search(es) were blocked this " +
+      "turn and the graph was never queried. A structural question answered by reading files " +
+      "is the blind spot the guard cannot see - ask the graph: gsd-t graph who-calls <symbol>."
+    );
+    return;
+  }
+
+  quiet();
+}
+
+main();

package/templates/CLAUDE-global.md

@@ -331,6 +331,8 @@ NEED A STRUCTURAL ANSWER? (what imports this, who calls this, what breaks if I c
 
 **This governs plain conversational work, not just `/gsd-t-*` commands.** The failure that produced this rule (binvoice, 2026-08-11) was an ordinary session: it reached for the graph, found none, grepped an 827-file project, and nothing objected. Checking the graph's existence before reasoning about code is the first move, not a fallback.
 
+**ENFORCED, not advised (M117).** A PreToolUse guard on Bash and Grep BLOCKS a search that asks a structural question about code and names the graph query to run instead. Three outcomes, no fourth: structural → blocked; a search over content the graph does not index (`.md`, `.json`, `.sql`, config, prose) → runs, because the graph holds no answer to route to; a search the guard cannot classify → blocked, because guessing "probably text" is how this rule stopped having teeth. **A missing or unbuilt graph BLOCKS too**, with `gsd-t graph index` — allowing grep because the graph is down is the exact fallback that let a project grep its way through 827 files. There is no bypass flag; a project may switch it off only by writing `.gsd-t/graph-search-gate.json` `{"enabled": false}`, which is a recorded decision rather than an absence. A Stop-time report covers what no pattern-matcher can see: a turn that answered a structural question by reading files end to end. Why this was needed: the rule already existed and had three enforcement points, and all three watched paths the work does not take — the Grep-tool and Read-tool hooks never fire in bypass mode, and the runtime use-gate only runs inside verify. The ledger showed two grep events in three months against 34,418 tool-issued queries.
+
 **Absence is a repairable condition, not a stop sign.** When this was checked across the machine, 20 of 27 registered projects had no usable graph — 2 never built, 18 holding a real index at a path the tooling stopped reading after the store moved. Every one of those sessions had been grepping. `gsd-t update-all` now repairs both automatically and reports any it could not.
 
 ## Prime Rule