@tekyzinc/gsd-t 5.18.10 → 5.19.10

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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
+
+The launcher prompt offers `"main" = work in main`, but the picker only treated a name as
+"stay here" when it equalled the branch currently checked out. A main checkout left on
+`feat/m26-file-mgmt` (NiceNote) turned `main` into `git worktree add -b main`, which git refused:
+`a branch named 'main' already exists`. The person typing `main` means the FOLDER, not the branch.
+
+- `bin/gsd-t-pick-worktree.cjs`: a typed name means the main checkout when it equals EITHER the branch
+  checked out there OR the repo's default branch as the remote declares it (`origin/HEAD` → `main`);
+  nothing is inferred from the name, so a `trunk` repo with no remote still treats `main` as a new
+  branch. The stderr notice names the branch actually checked out.
+- Same class, other half: naming an EXISTING branch that is checked out nowhere now checks it out
+  into a worktree (`git worktree add <dest> <branch>`) instead of asking git to create it again.
+- 2 regression tests in `test/m111-pick-worktree.test.js`.
+
 ## [5.18.10] - 2026-09-03
 
 ### Added — M115 Test-Plan-First Requirements Interrogation (`/gsd-t-test-plan`)

package/README.md

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

@@ -102,17 +102,20 @@ function main() {
   }
 
   if (wanted) {
-    // Asking for the repo's own default branch means "work here, in the main
-    // checkout" — not "make a worktree called main", which git refuses anyway
-    // because that branch is already checked out. Rare, but it is a real
-    // choice, and the only way to express it is to name it.
-    if (isDefaultBranch(cwd, branchNameFrom(wanted))) {
+    // Naming the main checkout means "work here" — not "make a worktree called
+    // main", which git refuses anyway. The main checkout answers to two names:
+    // the branch it is sitting on right now, and the repo's default branch
+    // (`main` in a repo whose origin/HEAD is main), which is what the launcher
+    // prompt offers even when the checkout has wandered onto a feature branch.
+    // Rare, but it is a real choice, and the only way to express it is to name it.
+    if (meansMainCheckout(cwd, branchNameFrom(wanted))) {
       // Said out loud on stderr: every other path here is silent, but this one
       // is a deliberate choice to work somewhere the house rules steer away
       // from, and silence would read as "the name was ignored". stdout stays
-      // empty because the shell reads it as the directory to move to.
+      // empty because the shell reads it as the directory to move to. The
+      // branch named is the one actually checked out, not the one typed.
       process.stderr.write(
-        `[GSD-T WORKTREE] staying in the main checkout on ${branchNameFrom(wanted)} — ` +
+        `[GSD-T WORKTREE] staying in the main checkout on ${currentBranch(cwd) || "(detached)"} — ` +
         `no worktree created.\n`
       );
       stay();
@@ -138,25 +141,45 @@ function main() {
 }
 
 /**
- * Is this the repo's own default branch — the one the main checkout sits on?
+ * Does this name refer to the main checkout — the folder the session started in?
  *
- * Asked of git rather than matched against a list: a repo may use `master`,
- * `trunk` or anything else, and a hardcoded list would send those repos into a
- * worktree named after their own main branch. The branch currently checked out
- * in the main tree IS the answer, since that is the thing being opted into.
+ * Two names do: the branch checked out there right now, and the repo's default
+ * branch. The second matters because the main checkout is often left on a
+ * feature branch, and the person typing "main" at the launcher prompt means the
+ * FOLDER, not the branch — a worktree on `main` is exactly what git refuses.
  *
- * A repo git cannot answer for is not the default-branch case — it falls
- * through to the ordinary worktree path, which fails loudly on its own if git
- * is genuinely broken.
+ * The default is asked of git (origin/HEAD), never assumed: a repo on `trunk`
+ * with no origin treats `main` as an ordinary new branch name. A repo git
+ * cannot answer for falls through to the ordinary worktree path, which fails
+ * loudly on its own if git is genuinely broken.
  */
-function isDefaultBranch(repo, name) {
+function meansMainCheckout(repo, name) {
+  const typed = String(name).toLowerCase();
+  // Both sides lowercased: a branch name typed at a prompt is a value the user
+  // types, and "Main" must mean main.
+  const current = currentBranch(repo);
+  if (current && current.toLowerCase() === typed) return true;
+  const def = defaultBranch(repo);
+  return Boolean(def) && def.toLowerCase() === typed;
+}
+
+// The branch the main checkout sits on; "" when detached or git cannot say.
+function currentBranch(repo) {
   const r = spawnSync("git", ["branch", "--show-current"], {
     cwd: repo, encoding: "utf8", timeout: 10000,
   });
-  if (r.status !== 0) return false;
-  // Both sides lowercased: a branch name typed at a prompt is a value the user
-  // types, and "Main" must mean main.
-  return String(r.stdout || "").trim().toLowerCase() === String(name).toLowerCase();
+  return r.status === 0 ? String(r.stdout || "").trim() : "";
+}
+
+// The repo's default branch as the remote declares it (origin/HEAD → "main"),
+// or null when there is no remote to ask. Nothing is inferred from the name.
+function defaultBranch(repo) {
+  const r = spawnSync("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], {
+    cwd: repo, encoding: "utf8", timeout: 10000,
+  });
+  if (r.status !== 0) return null;
+  const ref = String(r.stdout || "").trim();
+  return ref.startsWith("origin/") ? ref.slice("origin/".length) : null;
 }
 
 // Turn what the user typed into a name git will accept, without silently
@@ -253,9 +276,13 @@ function enterOrCreate(repo, home, branch) {
 
   fs.mkdirSync(home, { recursive: true });
 
-  const r = spawnSync("git", ["worktree", "add", dest, "-b", branch], {
-    cwd: repo, encoding: "utf8",
-  });
+  // A branch that already exists (a feature branch from last week, nobody in
+  // it) is checked out as it is; `-b` would ask git to create it again, and git
+  // refuses. Only a name git has never seen becomes a new branch.
+  const args = localBranchExists(repo, branch)
+    ? ["worktree", "add", dest, branch]
+    : ["worktree", "add", dest, "-b", branch];
+  const r = spawnSync("git", args, { cwd: repo, encoding: "utf8" });
 
   // git writes progress to stderr even when it succeeds, so the exit code and
   // the directory existing are what actually prove it worked.
@@ -272,6 +299,14 @@ function enterOrCreate(repo, home, branch) {
   return { path: dest };
 }
 
+// Is there a local branch by this exact name? Asked of git's refs, not the
+// worktree list, so a branch checked out nowhere still counts.
+function localBranchExists(repo, branch) {
+  return spawnSync("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], {
+    cwd: repo, stdio: "pipe", timeout: 10000,
+  }).status === 0;
+}
+
 /**
  * Does THIS repo know `dest` as its worktree for `branch`?
  *