@tekyzinc/gsd-t 5.18.10 → 5.19.10

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

@@ -154,7 +154,7 @@ WHEN creating a worktree directly (git worktree add, isolation: "worktree", etc.
 
 **A worktree is NOT usable until it is provisioned (M112).** `git worktree add` brings only what git TRACKS, so every ignored file stays behind — `.env` and its secrets, local settings, and the installed dependencies. The new folder looks complete and is not: tests fail on a missing module and the app cannot reach its database, both reading as broken code rather than a setup gap. `bin/gsd-t-worktree-provision.cjs` runs automatically inside `gsd-t-pick-worktree` and treats the three kinds of ignored file differently — **CARRY** local config and secrets (`.env*`, `.npmrc`, credentials; permissions preserved, so a 600 secret does not become world-readable), **SKIP** per-session `.gsd-t` state, build output and OS junk (copying another session's briefs/heartbeats is how two sessions come to believe they own the same work), and **INSTALL** dependencies from the worktree's own lockfile rather than copying or symlinking (a symlink makes a lockfile change in one tree silently alter the other). Anything it cannot read or copy is REPORTED, and a failed install HALTS — a worktree that came up short says so instead of looking ready. Creating a worktree by hand skips all of this, so prefer `gsd-t-pick-worktree --name <branch>`.
 
-**Naming an existing worktree WALKS YOU INTO IT (M113).** `gsd-t pick-worktree --name <branch>` used to refuse whenever the folder was already there, which refused the ordinary case — your own worktree, from yesterday, nobody in it — and left no way back except quitting the session and starting one by hand. It now ENTERS a worktree git confirms as this repo's, on that branch, with no interactive session in it. Two cases still STOP, because each is a way of landing on somebody's uncommitted work: a directory git does not know as that branch's worktree (a stray folder, or another branch's), and a worktree an interactive session already occupies (the M105 collision). `gsd-t pick-worktree --list` prints one line per worktree as `free|busy<TAB><path>`, so the launcher can show what exists before asking for a name.
+**Naming an existing worktree WALKS YOU INTO IT (M113).** `gsd-t pick-worktree --name <branch>` used to refuse whenever the folder was already there, which refused the ordinary case — your own worktree, from yesterday, nobody in it — and left no way back except quitting the session and starting one by hand. It now ENTERS a worktree git confirms as this repo's, on that branch, with no interactive session in it. Two cases still STOP, because each is a way of landing on somebody's uncommitted work: a directory git does not know as that branch's worktree (a stray folder, or another branch's), and a worktree an interactive session already occupies (the M105 collision). `gsd-t pick-worktree --list` prints one line per worktree as `free|busy<TAB><path>`, so the launcher can show what exists before asking for a name. **Typing the DEFAULT branch (`main`) means the main checkout FOLDER, even when that checkout sits on a feature branch** — the picker asks git for the remote-declared default (`origin/HEAD`) as well as the current branch, and stays put on either; an existing branch checked out nowhere is checked out into a worktree, never re-created.
 
 
 **The expected-branch rule governs the MAIN checkout only (M112).** A worktree exists precisely to be on its own branch, so `branch-guard` passes there and names the skip; a **detached HEAD in a worktree FAILS**, because commits made with no branch attached are easily lost. The rule is read from the project CLAUDE.md in either shape — a sentence (`Expected branch: main`) or a table row (`| Expected branch | main |`) — and when no rule is declared the check says `NOT CHECKED` rather than returning a bare pass.
@@ -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