@tekyzinc/gsd-t 4.11.11 → 4.13.10

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.13.10] - 2026-06-29
+
+### Added — The graph serves code (function-level slices) + Read-intercept (M98)
+
+The code graph was index-only (names, files, line numbers, call/import edges — no code). M98 makes it SERVE CODE: a new query returns a single function's source, and a Read-intercept hook points structural code-reads at it.
+
+- **`gsd-t graph body <funcId|symbol>`** (`bin/gsd-t-graph-query-cli.cjs`) — returns a function's SOURCE sliced LIVE from disk by line range, with its import lines, enclosing class header (for methods), and caller list attached. Reads live (never stores bodies — files are local, always fresh); the query path re-indexes a stale file BEFORE slicing so line ranges are current. Ambiguous bare symbol → candidate list, never a merged body. A pre-M98 node (no end line) is re-indexed inline to populate it; never guesses.
+- **Function END lines captured** (`bin/gsd-t-graph-edge-extract.cjs`, `bin/gsd-t-graph-index.cjs`) — each function/method/class entity now records `endPosition` as `nodes.end_line` (the only schema change; idempotently `ALTER TABLE`-migrated onto a pre-M98 graph; kept fresh by the existing DELETE-then-reinsert re-index path).
+- **Read-intercept hook** (`scripts/gsd-t-read-intercept.js`, PostToolUse on `Read`) — when a code read's offset/limit lands inside exactly one known function, AUGMENTS the output (original retained) with a pointer to `graph body <funcId>`. Default = pass-through: a bare/edit-intent read is NEVER shrunk (no-regression). Fail-open, no-op without a graph, code files only. Registered + removed by `gsd-t install` / uninstall (`configureReadInterceptHook` / `removeInterceptHooks`).
+
+Measured on real binvoice: `body selectCommentId` returned the exact 43-line function from a 1,334-line file — 21× fewer characters — compiler-accurate, with imports + 11 callers. Suite: 2538/2538 pass (17 new M98 tests; all 7 ACs green incl. the AC-3 freshness + AC-4 ambiguity killing tests).
+
+## [4.12.10] - 2026-06-27
+
+### Added — Python call-graph resolution (scip-python)
+
+The precise call-graph now covers Python, not just TS/JS. `buildScipResolver` runs scip-python alongside scip-typescript and merges both resolution maps — a repo with both languages gets one unified call-graph.
+
+- `bin/gsd-t-graph-scip-upgrade.cjs`: run scip-python when Python source is present; merge its `fileRefs` into the resolver. New `detectRepoLanguages()` skips an indexer when its language is absent (no wasted run). `runScipPython` now emits to a real `.gsd-t/index-python.scip` and passes `--project-name` + `--project-version 0.0.0` (scip-python crashes on an undefined version).
+- The SCIP reader was already language-agnostic (Python symbols use the same `name().` descriptor form), so cross-file Python calls resolve with no reader change.
+- `gsd-t install` / `gsd-t doctor` already covered scip-python (added in M95/M96).
+
+Proven on BDS (35 .py): 125 → 1,331 resolved calls (1,206 Python); `who-calls` returns real Python callers. Fixture test resolves a cross-file `pkg.util.compute_total` call. Suite: 2521/2521 pass.
+
 ## [4.11.11] - 2026-06-27
 
 ### Fixed — SCIP resolution missed nested/monorepo tsconfig (call-graph empty on subdir-tsconfig projects)

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.11.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.13.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-graph-edge-extract.cjs

@@ -255,6 +255,7 @@ function walkPython(rootNode, relPath, entities, edges) {
           name,
           type: 'function',
           line: node.startPosition.row + 1,
+          endLine: node.endPosition.row + 1,
           exported: false,
         });
         // walk body with this funcId as enclosing
@@ -275,6 +276,7 @@ function walkPython(rootNode, relPath, entities, edges) {
           name,
           type: 'class',
           line: node.startPosition.row + 1,
+          endLine: node.endPosition.row + 1,
           exported: false,
         });
         const body = node.childForFieldName('body');
@@ -390,6 +392,7 @@ function walkTSJS(rootNode, relPath, entities, edges) {
           name,
           type: enclosingClass ? 'method' : 'function',
           line: node.startPosition.row + 1,
+          endLine: node.endPosition.row + 1,
           exported: isExportedNode(node),
           ...(enclosingClass ? { parentClass: enclosingClass } : {}),
         });
@@ -412,6 +415,7 @@ function walkTSJS(rootNode, relPath, entities, edges) {
           name,
           type: 'method',
           line: node.startPosition.row + 1,
+          endLine: node.endPosition.row + 1,
           exported: true, // methods are implicitly exported via their class
           parentClass: enclosingClass || undefined,
         });
@@ -432,6 +436,7 @@ function walkTSJS(rootNode, relPath, entities, edges) {
           name,
           type: 'class',
           line: node.startPosition.row + 1,
+          endLine: node.endPosition.row + 1,
           exported: isExportedNode(node),
         });
         // Walk children with class context
@@ -462,6 +467,7 @@ function walkTSJS(rootNode, relPath, entities, edges) {
               name,
               type: 'function',
               line: decl.startPosition.row + 1,
+              endLine: valueNode.endPosition.row + 1,
               exported: isExp,
             });
             // Walk arrow/function body with this funcId

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

@@ -172,7 +172,8 @@ function buildSchema(db) {
       content_hash TEXT NOT NULL,
       file         TEXT NOT NULL,
       name         TEXT,
-      func_id      TEXT
+      func_id      TEXT,
+      end_line     INTEGER
     );
     CREATE TABLE IF NOT EXISTS edges (
       kind    TEXT    NOT NULL,
@@ -185,6 +186,21 @@ function buildSchema(db) {
     CREATE INDEX IF NOT EXISTS edges_kind_dst  ON edges(kind, dst);
     CREATE INDEX IF NOT EXISTS nodes_file      ON nodes(file);
   `);
+  migrateEndLine(db);
+}
+
+/**
+ * M98 — idempotent migration: add `nodes.end_line` to a pre-M98 graph that was
+ * built before the column existed. `CREATE TABLE IF NOT EXISTS` won't alter an
+ * existing table, so an older graph keeps its 7-column `nodes` until this runs.
+ * Safe to call on every open: checks PRAGMA first, ALTERs only when absent, never
+ * loses data. A NULL end_line is allowed (D2 re-indexes the file to populate it).
+ */
+function migrateEndLine(db) {
+  const cols = db.prepare("PRAGMA table_info(nodes)").all();
+  if (!cols.some((c) => c.name === 'end_line')) {
+    db.exec('ALTER TABLE nodes ADD COLUMN end_line INTEGER');
+  }
 }
 
 /**
@@ -210,7 +226,7 @@ function getWriteStmts(db) {
     deleteNodes: db.prepare('DELETE FROM nodes WHERE file = ?'),
     deleteEdgesSrc: db.prepare("DELETE FROM edges WHERE src = ? OR src LIKE ? OR src = ?"),
     insFile: db.prepare('INSERT OR REPLACE INTO files (file, content_hash, tier, indexed_at) VALUES (?, ?, ?, ?)'),
-    insNode: db.prepare('INSERT OR REPLACE INTO nodes (id, kind, tier, content_hash, file, name, func_id) VALUES (?, ?, ?, ?, ?, ?, ?)'),
+    insNode: db.prepare('INSERT OR REPLACE INTO nodes (id, kind, tier, content_hash, file, name, func_id, end_line) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'),
     insEdge: db.prepare('INSERT INTO edges (kind, src, dst, partial) VALUES (?, ?, ?, ?)'),
   };
   // db.transaction() wrapper is also created once (it closes over the stmts).
@@ -220,7 +236,7 @@ function getWriteStmts(db) {
     stmts.deleteEdgesSrc.run(file, `${file}#%`, file);
     stmts.insFile.run(file, hash, tier, now);
     for (const entity of entities) {
-      stmts.insNode.run(entity.id, entity.type || 'function', tier, hash, file, entity.name || null, entity.id);
+      stmts.insNode.run(entity.id, entity.type || 'function', tier, hash, file, entity.name || null, entity.id, entity.endLine ?? null);
     }
     for (const edge of edges) {
       stmts.insEdge.run(edge.kind, edge.src, edge.dst, edge.partial ? 1 : 0);
@@ -300,6 +316,12 @@ function parse_and_put(absPath, relPath, options) {
       finalEntities = upgraded.entities;
       finalEdges = upgraded.edges;
     }
+  } else if (existingTier === 'compiler-accurate') {
+    // [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';
   }
 
   // Normalize edges to store schema (map from parser-floor shape to store shape)
@@ -337,6 +359,7 @@ function parse_and_put(absPath, relPath, options) {
     file: relPath,
     exported: e.exported,
     parentClass: e.parentClass,
+    endLine: e.endLine ?? null,   // M98 — function end line for body-slice
   }));
 
   if (db) {

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

@@ -9,6 +9,7 @@
  * Verbs (D5 — original):
  *   gsd-t graph who-imports <file>             — file→file reverse import edges
  *   gsd-t graph who-calls <file#function>      — function→function reverse call edges (funcId-keyed)
+ *   gsd-t graph body <file#function|symbol>    — (M98) a function's SOURCE sliced LIVE from disk + imports + class header + callers
  *   gsd-t graph blast-radius <target>          — UNION of import-graph + call-graph reverse-reachable set (transitive)
  *   gsd-t graph status                         — live queryable index state
  *
@@ -129,7 +130,7 @@ function resolveStorePath() {
 
 /**
  * @typedef {{ importGraph: Map<string,Set<string>>, callGraph: Map<string,Set<string>>,
- *             funcEntities: Map<string,{name:string,file:string,tier:string}>,
+ *             funcEntities: Map<string,{name:string,file:string,tier:string,endLine:?number}>,
  *             allFiles: Set<string>, tier: string,
  *             skippedFiles: Set<string> }} IndexStructure
  *
@@ -329,6 +330,7 @@ function buildIndex(records, skippedFiles) {
             name: ent.name,
             file: ent.file || rec.file,
             tier: ent.tier || rec.tier,
+            endLine: ent.endLine ?? null,
           });
         }
       }
@@ -399,7 +401,13 @@ function loadSqliteStore(dbPath) {
   let db;
   try {
     db = new Database(dbPath, { readonly: true });
-    const nodes = db.prepare("SELECT id, kind, tier, file, name, func_id FROM nodes").all();
+    // M98: end_line is a post-M98 column; a pre-M98 graph (read-only here, so the
+    // write-path migration can't run) lacks it. Detect and select conditionally so
+    // an older index still loads (end_line just comes back null → body re-indexes).
+    const hasEndLine = db.prepare("PRAGMA table_info(nodes)").all().some((c) => c.name === "end_line");
+    const nodes = db.prepare(
+      `SELECT id, kind, tier, file, name, func_id, ${hasEndLine ? "end_line" : "NULL AS end_line"} FROM nodes`
+    ).all();
     const edges = db.prepare("SELECT kind, src, dst FROM edges").all();
 
     const norm = (p) => p.replace(/\\/g, "/");
@@ -427,7 +435,7 @@ function loadSqliteStore(dbPath) {
       return byFile.get(file);
     };
     for (const n of nodes) {
-      if (n.func_id) rec(n.file).entities.push({ funcId: n.func_id, name: n.name, file: n.file, tier: n.tier });
+      if (n.func_id) rec(n.file).entities.push({ funcId: n.func_id, name: n.name, file: n.file, tier: n.tier, endLine: n.end_line });
     }
     for (const e of edges) {
       // src for an IMPORT edge is the source FILE; for a CALL edge it's a funcId
@@ -609,6 +617,116 @@ function queryWhoCalls(index, identity) {
   return { ambiguous: true, candidates: matchingFuncIds.sort() };
 }
 
+// ─── Query: body (M98) ────────────────────────────────────────────────────────
+
+/**
+ * body(identity): return a single function's SOURCE — read LIVE from disk by line
+ * range — plus context (the file's import lines + the enclosing class header if a
+ * method + the caller list from the call graph). The headline "smart-reach" win:
+ * ~180 tokens for one function vs ~7,750 for the whole file.
+ *
+ * Resolution mirrors who-calls disambiguation [RULE] who-calls-function-identity-disambiguated:
+ *   - exact funcId (`file#name@line`) → that node
+ *   - bare `name` matching exactly one node → that node
+ *   - bare `name` matching N>1 → { ambiguous:true, candidates:[...] } — NEVER a merged body
+ *   - no match → { notFound:true }
+ *
+ * INVARIANTS (feed verify gate, contract §2):
+ *   [RULE] body-reads-live-never-stored          — source comes from a live disk read, not a DB blob
+ *   [RULE] body-freshness-reindex-before-slice    — Step-1 freshness re-indexes a stale file BEFORE this runs
+ *   [RULE] body-ambiguous-never-merged            — ambiguous symbol → candidates, never a wrong/joined body
+ *   [RULE] body-end-line-required                 — a node with NULL end_line returns needsReindex (caller re-indexes)
+ *
+ * @param {IndexStructure} index
+ * @param {string} identity   funcId or bare name
+ * @param {string} projectRoot  repo root (live file read is relative to this)
+ * @returns {{ ok?:boolean, funcId?:string, file?:string, lineRange?:[number,number],
+ *             tier?:string, imports?:string[], classHeader?:?string, source?:string,
+ *             callers?:string[], ambiguous?:boolean, candidates?:string[],
+ *             notFound?:boolean, needsReindex?:boolean }}
+ */
+function queryBody(index, identity, projectRoot) {
+  // ── Resolve identity → a single funcId ──
+  let funcId = null;
+  if (identity.includes("#")) {
+    // File-qualified. Tolerate a missing @line suffix (funcEntities key carries it).
+    if (index.funcEntities.has(identity)) {
+      funcId = identity;
+    } else {
+      const noLine = identity.replace(/@\d+$/, "");
+      for (const fid of index.funcEntities.keys()) {
+        if (fid === noLine || fid.replace(/@\d+$/, "") === noLine) { funcId = fid; break; }
+      }
+    }
+  } else {
+    // Bare name — disambiguate, NEVER merge.
+    const matches = [];
+    for (const [fid, meta] of index.funcEntities) {
+      if (meta.name === identity) matches.push(fid);
+    }
+    if (matches.length === 1) funcId = matches[0];
+    else if (matches.length > 1) return { ambiguous: true, candidates: matches.sort() };
+  }
+
+  if (!funcId) return { notFound: true };
+
+  const meta = index.funcEntities.get(funcId);
+  // Start line is encoded in the funcId suffix `@<line>`; end_line from the node.
+  const startMatch = /@(\d+)$/.exec(funcId);
+  const startLine = startMatch ? parseInt(startMatch[1], 10) : null;
+  const endLine = meta.endLine;
+
+  // [RULE] body-end-line-required — a pre-M98 node has no end_line; caller re-indexes.
+  if (startLine == null || endLine == null) {
+    return { needsReindex: true, funcId, file: meta.file };
+  }
+
+  // [RULE] body-reads-live-never-stored — slice the live file by line range.
+  const absFile = path.isAbsolute(meta.file) ? meta.file : path.join(projectRoot, meta.file);
+  let lines;
+  try { lines = fs.readFileSync(absFile, "utf8").split("\n"); }
+  catch (_e) { return { notFound: true, file: meta.file }; }
+
+  const source = lines.slice(startLine - 1, endLine).join("\n");
+
+  // Context: the file's top-level import/require lines.
+  const imports = [];
+  for (const ln of lines) {
+    const t = ln.trim();
+    if (/^(import\s|export\s.*\sfrom\s|const\s+\w+\s*=\s*require\(|.*\brequire\()/.test(t) && /from\s|require\(/.test(t)) {
+      imports.push(ln);
+    }
+    if (imports.length >= 40) break; // safety cap
+  }
+
+  // Context: enclosing class header (if this funcId is a method — its line sits
+  // inside a `class X {` block above it). Best-effort: nearest preceding class line.
+  let classHeader = null;
+  for (let i = startLine - 2; i >= 0; i--) {
+    const m = /^\s*(export\s+)?(abstract\s+)?class\s+[A-Za-z_$][\w$]*/.exec(lines[i]);
+    if (m) { classHeader = lines[i].trim(); break; }
+    // Stop if we hit a top-level non-indented statement that isn't a class (cheap bound).
+    if (/^\S/.test(lines[i]) && !/^(export|import|\/\/|\/\*|\*)/.test(lines[i])) break;
+  }
+
+  // Context: callers from the existing call graph (free).
+  const fidNoLine = funcId.replace(/@\d+$/, "");
+  const callerSet = index.callGraph.get(funcId) || index.callGraph.get(fidNoLine);
+  const callers = callerSet ? Array.from(callerSet).sort() : [];
+
+  return {
+    ok: true,
+    funcId,
+    file: meta.file,
+    lineRange: [startLine, endLine],
+    tier: meta.tier || index.tier,
+    imports,
+    classHeader,
+    source,
+    callers,
+  };
+}
+
 // ─── Query: blast-radius ──────────────────────────────────────────────────────
 
 /**
@@ -1070,6 +1188,7 @@ module.exports = {
   buildIndexFromRecords,
   queryWhoImports,
   queryWhoCalls,
+  queryBody,
   queryBlastRadius,
   queryStatus,
   // D9 additions
@@ -1107,7 +1226,7 @@ if (require.main === module) {
   }
 
   const ALL_VERBS = [
-    "who-imports", "who-calls", "blast-radius", "status",
+    "who-imports", "who-calls", "body", "blast-radius", "status",
     "cluster", "dead-code", "orphan", "dangling", "test-impl",
   ];
 
@@ -1157,6 +1276,57 @@ if (require.main === module) {
     }
     emit({ ok: true, verb, target, results: queryResult.results, tier: queryResult.tier, coverage: queryResult.coverage });
 
+  } else if (verb === "body") {
+    if (!target) fail({ ok: false, reason: "missing-target", verb });
+    const projectRoot = path.dirname(path.dirname(storePath));
+    let bodyResult = queryBody(index, target, projectRoot);
+
+    // [RULE] body-end-line-required — a pre-M98 node lacks end_line and its file
+    // wasn't stale (so Step-1 freshness didn't re-index it). Re-index that ONE file
+    // inline to populate end_line, reload, retry. Never guess an end.
+    // [RULE] body-reindex-preserves-tier — pass the file's EXISTING tier as
+    // existingTier so this read-path re-index does NOT silently downgrade a
+    // compiler-accurate file to tree-sitter-floor (parse_and_put without SCIP would).
+    if (bodyResult.needsReindex && bodyResult.file) {
+      try {
+        const { parse_and_put } = require(path.join(__dirname, "gsd-t-graph-index.cjs"));
+        const { openDb } = loadFreshnessModule() || {};
+        const absFile = path.isAbsolute(bodyResult.file) ? bodyResult.file : path.join(projectRoot, bodyResult.file);
+        const db = typeof openDb === "function" ? openDb(projectRoot, storePath) : null;
+        if (db && parse_and_put) {
+          // Read the file's stored tier so it is preserved through the re-index.
+          let existingTier = null;
+          try {
+            const row = db.prepare("SELECT tier FROM files WHERE file = ?").get(bodyResult.file);
+            existingTier = row ? row.tier : null;
+          } catch { /* tier preservation is best-effort */ }
+          try {
+            parse_and_put(absFile, bodyResult.file, { db, existingTier });
+          } finally {
+            try { db.close(); } catch {}
+          }
+          const reloaded = loadStore(storePath);
+          if (reloaded.ok) bodyResult = queryBody(reloaded.index, target, projectRoot);
+        }
+      } catch (_e) { /* fall through to the needsReindex envelope below */ }
+    }
+
+    if (bodyResult.ambiguous) {
+      // [RULE] body-ambiguous-never-merged
+      process.stdout.write(JSON.stringify({
+        ok: false, reason: "ambiguous-function", verb, target, candidates: bodyResult.candidates,
+      }) + "\n");
+      process.exit(2);
+    }
+    if (bodyResult.notFound) fail({ ok: false, reason: "not-found", verb, target, file: bodyResult.file });
+    if (bodyResult.needsReindex) fail({ ok: false, reason: "end-line-unavailable", verb, target, file: bodyResult.file });
+    emit({
+      ok: true, verb, target: bodyResult.funcId, file: bodyResult.file,
+      lineRange: bodyResult.lineRange, tier: bodyResult.tier,
+      imports: bodyResult.imports, classHeader: bodyResult.classHeader,
+      source: bodyResult.source, callers: bodyResult.callers,
+    });
+
   } else if (verb === "blast-radius") {
     if (!target) fail({ ok: false, reason: "missing-target", verb });
     const { results, tier, coverage } = queryBlastRadius(index, target);

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

@@ -146,16 +146,53 @@ function runScipTypescript(projectRoot, outPath) {
   return { ok: false, error: scip.stderr || `exit code ${scip.status}` };
 }
 
-function runScipPython(projectRoot) {
-  const scip = spawnSync('scip-python', ['index', '.'], {
+function runScipPython(projectRoot, outPath) {
+  // Emit to a REAL file (separate from the TS index) so it can be READ + merged.
+  // --project-name is required-ish for stable symbols; derive from the dir name.
+  const out = outPath || path.join(projectRoot, '.gsd-t', 'index-python.scip');
+  const projName = path.basename(projectRoot).replace(/[^A-Za-z0-9_-]/g, '-') || 'project';
+  // scip-python REQUIRES a project version — it crashes (makeModuleInit) when the
+  // version is undefined (no pyproject.toml). Pass an explicit fallback version.
+  const scip = spawnSync('scip-python',
+    ['index', '--project-name', projName, '--project-version', '0.0.0', '--output', out, '.'], {
     cwd: projectRoot,
     encoding: 'utf8',
-    timeout: 120_000,
+    timeout: 180_000,
   });
-  if (scip.status === 0) return { ok: true };
+  if (scip.status === 0) return { ok: true, scipPath: out };
   return { ok: false, error: scip.stderr || `exit code ${scip.status}` };
 }
 
+// Cheap shallow language detection — does the repo contain TS/JS or Python source
+// (excluding vendored/build dirs)? Used to skip an indexer when its language is
+// absent. Walks at most a bounded depth to stay fast.
+function detectRepoLanguages(repoRoot) {
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.venv', 'venv',
+    'site-packages', '__pycache__', '.next', 'coverage', 'Pods', '.dart_tool', 'vendor']);
+  let typescript = false, python = false;
+  function isSkip(name) {
+    if (SKIP.has(name)) return true;
+    return ['dist', 'build', 'out'].some(p => name.length > p.length && name.startsWith(p) &&
+      (name[p.length] === '-' || name[p.length] === '.' || name[p.length] === '_'));
+  }
+  function walk(dir, depth) {
+    if ((typescript && python) || depth > 6) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (typescript && python) return;
+      if (e.isDirectory()) { if (!isSkip(e.name)) walk(path.join(dir, e.name), depth + 1); }
+      else if (e.isFile()) {
+        const ext = path.extname(e.name).toLowerCase();
+        if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') typescript = true;
+        else if (ext === '.py') python = true;
+      }
+    }
+  }
+  walk(repoRoot, 0);
+  return { typescript, python };
+}
+
 function runScipRust(projectRoot) {
   // rust-analyzer + scip: run `scip` (the rust-analyzer scip bridge) if available
   // As with TypeScript, Phase-1 is tier-labelling only
@@ -218,32 +255,45 @@ function buildScipResolver(repoRoot, opts = {}) {
   const { readScipIndex } = require('./gsd-t-scip-reader.cjs');
   const avail = detectScip();
 
-  // Phase-1 of M95: TypeScript/JavaScript only (scip-typescript). Python is a
-  // sequenced follow-on. If TS SCIP is absent, the resolver is a no-op (floor).
-  if (!avail.typescript) {
-    return { ok: false, reason: 'scip-typescript-absent', resolveFileEdges: passthroughResolver };
+  // Detect which languages have source present (so we only run the relevant
+  // indexer). Cheap shallow check: does the repo contain .ts/.tsx/.js or .py?
+  const langs = detectRepoLanguages(repoRoot);
+
+  // Run each available+relevant indexer, merge their resolution maps. The reader
+  // is language-agnostic (Python symbols use the same `name().` descriptor form),
+  // so TS and Python refs merge into one fileRefs map keyed by repo-relative path.
+  const fileRefs = new Map(); // relPath → [{symbol, funcId, line}]
+  const ranIndexers = [];
+
+  function mergeRead(read) {
+    if (!read || !read.ok) return;
+    for (const [file, refs] of read.fileRefs) {
+      if (fileRefs.has(file)) fileRefs.get(file).push(...refs);
+      else fileRefs.set(file, refs.slice());
+    }
   }
 
-  const scipPath = path.join(repoRoot, '.gsd-t', 'index.scip');
-  let run;
-  try {
-    run = runScipTypescript(repoRoot, scipPath);
-  } catch (e) {
-    return { ok: false, reason: `scip-run-threw: ${e.message}`, resolveFileEdges: passthroughResolver };
+  if (avail.typescript && langs.typescript) {
+    try {
+      const run = runScipTypescript(repoRoot, path.join(repoRoot, '.gsd-t', 'index.scip'));
+      if (run && run.ok) { mergeRead(readScipIndex(run.scipPath)); ranIndexers.push('typescript'); }
+    } catch { /* degrade to floor for TS */ }
   }
-  if (!run || !run.ok) {
-    return { ok: false, reason: run ? run.error : 'scip-run-failed', resolveFileEdges: passthroughResolver };
+  if (avail.python && langs.python) {
+    try {
+      const run = runScipPython(repoRoot, path.join(repoRoot, '.gsd-t', 'index-python.scip'));
+      if (run && run.ok) { mergeRead(readScipIndex(run.scipPath)); ranIndexers.push('python'); }
+    } catch { /* degrade to floor for Python */ }
   }
 
-  const read = readScipIndex(run.scipPath);
-  if (!read.ok) {
-    return { ok: false, reason: read.reason, resolveFileEdges: passthroughResolver };
+  if (!ranIndexers.length) {
+    // No applicable indexer present/ran → floor mode.
+    const reason = (!avail.typescript && !avail.python) ? 'scip-indexers-absent'
+      : (!langs.typescript && !langs.python) ? 'no-indexable-source'
+      : 'scip-run-failed';
+    return { ok: false, reason, resolveFileEdges: passthroughResolver };
   }
 
-  // Build a fast per-file callee lookup: for a given test/impl file, the set of
-  // funcIds it references (resolved). Used to rewrite UNRESOLVED# call edges.
-  const fileRefs = read.fileRefs; // relPath → [{symbol, funcId, line}]
-
   /**
    * Resolve a single file's call edges. For each CALL edge whose dst is
    * UNRESOLVED#<name>, if SCIP found a reference to <name> in this file that
@@ -276,7 +326,7 @@ function buildScipResolver(repoRoot, opts = {}) {
     return { edges: out, resolved };
   }
 
-  return { ok: true, scipPath: run.scipPath, resolveFileEdges };
+  return { ok: true, indexers: ranIndexers, scipPath: path.join(repoRoot, '.gsd-t', 'index.scip'), resolveFileEdges };
 }
 
 /** No-op resolver used when SCIP is unavailable (floor mode). */

package/bin/gsd-t.js

@@ -460,6 +460,13 @@ const GRAPH_INTERCEPT_HOOK_MARKER = "gsd-t-graph-intercept";
 const GRAPH_INTERCEPT_HOOK_COMMAND =
   'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-intercept.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-graph-intercept.js" || true\'';
 
+// M98 — read-intercept PostToolUse hook on Read. Same global-safe pattern as the
+// M97 grep-intercept: the script fails-open (no-op) in non-GSD-T projects / projects
+// without a graph / non-code reads, so it is safe to register globally with a Read matcher.
+const READ_INTERCEPT_HOOK_MARKER = "gsd-t-read-intercept";
+const READ_INTERCEPT_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-read-intercept.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-read-intercept.js" || true\'';
+
 // Append entries to {projectDir}/.gitignore. Each entry added only if absent.
 // Idempotent. Returns true if any entries were added, false otherwise.
 function ensureGitignoreEntries(projectDir, entries) {
@@ -850,6 +857,97 @@ function configureGraphInterceptHook(settingsPath) {
   return { installed: true, action };
 }
 
+// M98 — register the read-intercept PostToolUse hook (matcher "Read").
+// Idempotent: find-by-marker, refresh stale command, else add. Mirrors the
+// M97 grep-intercept installer. The script fails-open so this is safe globally.
+function configureReadInterceptHook(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  let settings = {};
+  if (fs.existsSync(targetPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+      if (!settings || typeof settings !== "object") settings = {};
+    } catch {
+      warn("settings.json has invalid JSON — cannot configure read-intercept hook");
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+
+  const cmd = READ_INTERCEPT_HOOK_COMMAND;
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.PostToolUse) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h || typeof h.command !== "string") continue;
+      if (h.command === cmd || h.command.includes(READ_INTERCEPT_HOOK_MARKER)) {
+        found = true;
+        if (h.command !== cmd) { h.command = cmd; action = "updated"; }
+        if (entry.matcher !== "Read") { entry.matcher = "Read"; action = action === "noop" ? "updated" : action; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.PostToolUse.push({
+      matcher: "Read",
+      hooks: [{ type: "command", command: cmd }],
+    });
+    action = "added";
+  }
+  if (action === "noop") return { installed: true, action: "noop" };
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return { installed: false, action: "noop" };
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return { installed: false, action: "noop" };
+  }
+  return { installed: true, action };
+}
+
+// M98 — remove the GSD-T intercept PostToolUse hooks (grep + read) from settings.json.
+// Used during uninstall. Marker-based; leaves all other hooks intact. Idempotent.
+function removeInterceptHooks(settingsPath) {
+  const targetPath = settingsPath || SETTINGS_JSON;
+  if (!fs.existsSync(targetPath)) return false;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+    if (!settings || typeof settings !== "object") return false;
+  } catch {
+    warn("settings.json has invalid JSON — cannot remove intercept hooks");
+    return false;
+  }
+  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return false;
+
+  const markers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
+  const before = settings.hooks.PostToolUse.length;
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => {
+    if (!entry || !Array.isArray(entry.hooks)) return true;
+    return !entry.hooks.some(
+      (h) => h && typeof h.command === "string" && markers.some((m) => h.command.includes(m))
+    );
+  });
+  if (before - settings.hooks.PostToolUse.length === 0) return false;
+
+  if (isSymlink(targetPath)) {
+    warn("Skipping settings.json write — target is a symlink");
+    return false;
+  }
+  try {
+    fs.writeFileSync(targetPath, JSON.stringify(settings, null, 2));
+    return true;
+  } catch (e) {
+    warn(`Failed to write settings.json: ${e.message}`);
+    return false;
+  }
+}
+
 // Remove any context meter PostToolUse hooks from settings.json.
 // Used during uninstall. Leaves all other hooks intact.
 function removeContextMeterHook(settingsPath) {
@@ -1790,6 +1888,14 @@ async function doInstall(opts = {}) {
     else info("Graph-intercept hook already configured");
   }
 
+  // M98 — read-intercept: a structural code-read gets a graph note pointing at `graph body`.
+  const riHook = configureReadInterceptHook(SETTINGS_JSON);
+  if (riHook.installed) {
+    if (riHook.action === "added") success("Read-intercept hook added (structural code reads point at graph body slices)");
+    else if (riHook.action === "updated") success("Read-intercept hook refreshed");
+    else info("Read-intercept hook already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 
@@ -2259,6 +2365,11 @@ function doUninstall() {
     success("Context meter PostToolUse hook removed from settings.json");
   }
 
+  // M98 — remove the graph + read intercept PostToolUse hooks
+  if (removeInterceptHooks(SETTINGS_JSON)) {
+    success("Graph/read-intercept PostToolUse hooks removed from settings.json");
+  }
+
   warn("~/.claude/CLAUDE.md was NOT removed (may contain your customizations)");
   info("Remove manually if desired: delete the GSD-T section from ~/.claude/CLAUDE.md");
   info("Project files (.gsd-t/, docs/, CLAUDE.md) were NOT removed");
@@ -4706,6 +4817,10 @@ module.exports = {
   installContextMeter,
   configureContextMeterHooks,
   removeContextMeterHook,
+  // M97/M98: intercept hook installers
+  configureGraphInterceptHook,
+  configureReadInterceptHook,
+  removeInterceptHooks,
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,
   runTaskCounterRetirementMigration,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.11.11",
+  "version": "4.13.10",
   "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-read-intercept.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-read-intercept.js — M98
+ *
+ * A PostToolUse hook on the `Read` tool. When Claude reads an INDEXED code file
+ * with an offset+limit that lands inside exactly one known function's line range,
+ * this APPENDS a graph note pointing at the precise `graph body <funcId>` slice
+ * (which carries the imports + class header + callers + the ~43× token win).
+ *
+ * DEFAULT = PASS-THROUGH. A bare `Read(file)` with no structural signal, a non-code
+ * file, an unindexed file, or any error → the original full-file output reaches the
+ * model UNCHANGED. This hook only ever AUGMENTS (appends a note); it NEVER replaces
+ * or shrinks a file read — silently shrinking would break editing. (M98 Decision #4
+ * + the open-question resolved conservatively: option (c), no-regression.)
+ *
+ * Receives JSON on stdin (PostToolUse):
+ *   { tool_name, tool_input: { file_path, offset?, limit? }, tool_response/tool_output, cwd, ... }
+ *
+ * Emits JSON on stdout:
+ *   { hookSpecificOutput: { hookEventName: "PostToolUse",
+ *       updatedToolOutput: "<original file output> + graph note" } }
+ *   ...or nothing (exit 0) to pass the Read through unchanged.
+ *
+ * INVARIANTS:
+ *   [RULE] read-intercept-fail-open          — any error / missing graph / non-code → pass through
+ *   [RULE] read-intercept-augment-never-shrink — only APPEND; never replace the file body
+ *   [RULE] read-intercept-structural-only      — augment ONLY when offset+limit ∈ one funcId range
+ *   - NEVER calls Read/Grep (loop guard). Reads the graph DB directly (read-only).
+ *   - No graph in this project → pure no-op.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const OUTPUT_CAP = 9000; // stay under the 10K hook output cap
+
+// Code extensions the graph indexes — only these are candidates for a slice note.
+const CODE_EXTS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.rs',
+]);
+
+function passThrough() {
+  // Emit nothing → the original Read output reaches the model unchanged.
+  process.exit(0);
+}
+
+// Append `note` beneath `original`, but NEVER shrink the original the model already
+// has. [RULE] read-intercept-augment-never-shrink: if original + note would exceed
+// the hook output cap, pass through (emit nothing) — the note is advisory; a full
+// file read is not worth truncating to fit a pointer.
+function emitAugment(original, note) {
+  const combined = original + note;
+  if (combined.length > OUTPUT_CAP) passThrough();
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      updatedToolOutput: combined,
+    },
+  };
+  process.stdout.write(JSON.stringify(out));
+  process.exit(0);
+}
+
+function main(payload) {
+  // Only act on Read.
+  if (!payload || payload.tool_name !== 'Read') passThrough();
+
+  const cwd = payload.cwd || process.cwd();
+
+  // Must be a GSD-T project with a graph present.
+  if (!fs.existsSync(path.join(cwd, '.gsd-t'))) passThrough();
+  if (!fs.existsSync(path.join(cwd, '.gsd-t', 'graph.db'))) passThrough();
+
+  const input = payload.tool_input || {};
+  const filePath = input.file_path;
+  if (typeof filePath !== 'string' || !filePath) passThrough();
+
+  // Only code files. (Non-code / docs / config → pass through, AC-6.)
+  if (!CODE_EXTS.has(path.extname(filePath).toLowerCase())) passThrough();
+
+  // STRUCTURAL SIGNAL (conservative): the read must carry an offset+limit. A bare
+  // full-file read has no structural target → pass through (no silent shrinking).
+  const offset = Number(input.offset);
+  const limit = Number(input.limit);
+  if (!Number.isFinite(offset) || !Number.isFinite(limit) || limit <= 0) passThrough();
+  const readStart = offset;          // 1-based first line read (Read's offset is 1-based)
+  const readEnd = offset + limit - 1;
+
+  // Relativize the file path against cwd so it matches stored funcIds (file#name@line).
+  let rel = filePath;
+  if (path.isAbsolute(filePath)) rel = path.relative(cwd, filePath);
+  rel = rel.split(path.sep).join('/');
+
+  // Find the function whose [start,end] range the read window lands inside, by
+  // enumerating this file's funcIds straight from the graph DB (read-only). Cheaper
+  // and more direct than spawning the query CLL — and it's the same store the CLI reads.
+  let match = null;
+  try {
+    // Resolve the store loader from the global package (where this hook ships) first,
+    // falling back to the project's own copy — a synthetic project may have neither,
+    // in which case we fail-open (pass through).
+    let requireStore;
+    try { requireStore = require(path.join(__dirname, '..', 'bin', 'gsd-t-require-store.cjs')); }
+    catch { requireStore = require(path.join(cwd, 'bin', 'gsd-t-require-store.cjs')); }
+    const Database = requireStore.requireBetterSqlite();
+    const db = new Database(path.join(cwd, '.gsd-t', 'graph.db'), { readonly: true });
+    try {
+      const hasEnd = db.prepare('PRAGMA table_info(nodes)').all().some((c) => c.name === 'end_line');
+      if (hasEnd) {
+        const rows = db.prepare(
+          'SELECT func_id, name, end_line FROM nodes WHERE file = ? AND func_id IS NOT NULL AND end_line IS NOT NULL'
+        ).all(rel);
+        for (const r of rows) {
+          const m = /@(\d+)$/.exec(r.func_id);
+          if (!m) continue;
+          const start = parseInt(m[1], 10);
+          const end = r.end_line;
+          // The read window starts inside this function's [start,end] body.
+          if (readStart >= start && readStart <= end) {
+            // Prefer the innermost (largest start) enclosing function.
+            if (!match || start > match.start) match = { funcId: r.func_id, name: r.name, start, end };
+          }
+        }
+      }
+    } finally {
+      try { db.close(); } catch { /* best-effort */ }
+    }
+  } catch (_e) { passThrough(); }
+
+  if (!match) passThrough();
+
+  // Build the augment note (appended beneath the original file output, kept intact).
+  const original = payload.tool_response || payload.tool_output || '';
+  const note =
+    `\n\n▸ GSD-T code graph: this read (lines ${readStart}-${readEnd}) sits inside ` +
+    `\`${match.name}\` (${rel}:${match.start}-${match.end}). For just this function's ` +
+    `source + its imports, class header, and callers (≈10× fewer tokens), run:\n` +
+    `    gsd-t graph body '${match.funcId}'`;
+
+  emitAugment(typeof original === 'string' ? original : JSON.stringify(original), note);
+}
+
+// ── stdin → main, fail-open everywhere ────────────────────────────────────────
+let inputBuf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => { inputBuf += c; });
+process.stdin.on('end', () => {
+  let payload;
+  try { payload = JSON.parse(inputBuf); } catch { passThrough(); }
+  try { main(payload); } catch { passThrough(); }
+});
+process.stdin.on('error', () => passThrough());