@tekyzinc/gsd-t 5.11.27 → 5.11.29

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.11.29] - 2026-08-11
+
+### Fixed — 20 of 27 projects had no usable code graph, and nothing said so
+
+A binvoice session reached for the graph, found none, and read an 827-file
+project by grep. `update-all` had reported that project as current for months,
+because it was: every file GSD-T ships was in place. The graph is not a shipped
+file — it is built state, created only when someone runs `gsd-t graph index` by
+hand, and no propagation step creates it.
+
+Checking for it exposed a second, larger failure. M99 moved the store from
+`.gsd-t/graph.db` to `.gsd-t/graphDB/graph.db` — it changed where the code LOOKS
+without moving what was already there. 18 projects still held a real, populated
+index at the old path that every tool walked straight past.
+
+    never built        2  (binvoice, newman)
+    at the old path   18  — a full index, invisible to the tooling
+    working            7
+
+**Absence is now repaired, not reported.** Per David's rule: a missing graph is
+BUILT, a stale one is UPDATED, a misplaced one is MOVED, and grep is reserved
+for content that cannot be indexed at all (`.md`, `.sql`, `.json`, config,
+prose). The prior contract said HALT on an absent graph — correct 20 times here,
+and it would have repaired nothing.
+
+The rule now also governs plain conversational sessions. The binvoice failure
+was not a wired command; it was ordinary work, and the contract only ever
+covered `/gsd-t-*` commands.
+
+- `bin/gsd-t.js`: `graphState()` tells the two faults apart; `migrateLegacyGraph()`
+  moves a pre-M99 store (the resolver's own migration, already written for M99
+  and never called on existing projects); `buildGraph()` indexes from scratch and
+  verifies a store actually landed rather than trusting the indexer's exit code.
+  A failed repair is reported per project and never counted as fixed.
+- `.gsd-t/contracts/graph-consumer-wiring-contract.md`: FAIL-LOUD now repairs
+  before halting.
+- `~/.claude/CLAUDE.md` + `templates/CLAUDE-global.md`: the rule reaches every
+  session, not only wired commands.
+- `test/m112-graph-health-check.test.js`: 11 regressions.
+
+Run once here: 18 stores moved, 2 graphs built (binvoice 639 files/56,822 edges,
+newman 610 files/27,582 edges), all verified answering.
+
+## [5.11.28] - 2026-08-11
+
+### Fixed — the graph stored the alias edges, then could not find them (two bugs)
+
+`who-imports src/lib/db.ts` returned 5 importers on hilo-figma-atos.
+`grep -rl '@/lib/db' src` returned 793. Found by David, who halted the scan
+rather than running it on a graph that was answering wrongly.
+
+v5.11.26 taught the INDEXER to expand `@/lib/db` into `src/lib/db`, and it does
+— the edges are in the database, correctly. It never met the QUERY side, which
+is what turns `src/lib/db` into the real file id `src/lib/db.ts`. Two
+independent bugs there, and fixing either alone still returns nothing:
+
+1. The resolver opened with `if (!dst.startsWith(".")) return dst` — an expanded
+   alias has no leading dot, so it was classed as an external package like
+   "react" and returned untouched. The extension was never appended.
+2. The set of known files was built from FUNCTION nodes, so a module exporting
+   only constants, types, or re-exports was not in it. Atos's `src/lib/db.ts`
+   exports a constant. The indexer already records every file it walked in the
+   `files` table — the authoritative list was stored all along.
+
+- `bin/gsd-t-graph-query-cli.cjs`: resolve non-relative targets against the file
+  set (packages still pass through untouched, and an expanded alias is NOT
+  re-joined to the importer's directory); read the file set from the `files`
+  table, announcing the degradation on an older graph that lacks it.
+- `test/m112-alias-query-resolution.test.js`: 7 regressions, all going through
+  the QUERY rather than the stored edge.
+
+Every v5.11.26 test asserted the edge was STORED correctly. Not one asked
+whether it could then be FOUND — the feature was tested at the write and called
+done. These tests close that gap.
+
+Requires `gsd-t graph index` only if the graph predates the `files` table;
+otherwise the fix applies to existing indexes immediately.
+
 ## [5.11.27] - 2026-08-11
 
 ### Fixed — the scan's volume probe returned a stand-in, and the whole run was built on it

package/README.md

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

@@ -437,10 +437,68 @@ function loadSqliteStore(dbPath) {
     // TS/JS routinely omit the extension; the graph keys on real file ids.
     // Every indexed file appears as the `file` of its nodes (the indexer does not
     // emit dedicated FILE nodes), so collect the distinct file set from there.
-    const fileIds = new Set(nodes.map((n) => norm(n.file)).filter(Boolean));
+    // [RULE] query-file-set-comes-from-files-table-not-inferred-from-functions
+    //
+    // hilo-figma-atos, 2026-08-11, the second half of the same miss. This set
+    // decides whether an extensionless import target can be matched to a real
+    // file. Built from node rows, it contains only files that declare a
+    // FUNCTION — so `src/lib/db.ts`, which exports a constant, was not in it,
+    // and no query could ever resolve an import of it. A file of constants,
+    // types, or re-exports is exactly the kind of shared module a whole codebase
+    // imports, and it was invisible.
+    //
+    // The indexer records every file it walked in the `files` table. That is the
+    // authoritative list; inferring one from functions was always an
+    // approximation of a fact already stored.
+    let fileIds;
+    const hasFilesTable = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='files'")
+      .get();
+    if (hasFilesTable) {
+      fileIds = new Set(
+        db.prepare("SELECT file FROM files").all().map((r) => norm(r.file)).filter(Boolean)
+      );
+    } else {
+      // A graph built before the files table existed. Node-derived is what this
+      // has always done — announced, because it under-reports imports of any
+      // file that declares no function.
+      fileIds = new Set(nodes.map((n) => norm(n.file)).filter(Boolean));
+      process.stderr.write(
+        "[graph] this index predates the files table — imports of constant-only/type-only files may be missed; re-run `gsd-t graph index`\n"
+      );
+    }
     const EXTS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", "/index.ts", "/index.tsx", "/index.js"];
+    // [RULE] query-resolves-expanded-alias-not-only-relative
+    //
+    // hilo-figma-atos, 2026-08-11: `who-imports src/lib/db.ts` returned 5 of 793
+    // real importers. The 788 missing ones all wrote `@/lib/db`.
+    //
+    // The two halves of the alias fix did not meet. The indexer (v5.11.26)
+    // expands `@/lib/db` to `src/lib/db` — correct, and stored. But this
+    // resolver, which is what appends the file extension, skipped it: the gate
+    // below returned early for anything not starting with ".", treating an
+    // expanded project path exactly like the package import `react`. So the edge
+    // sat in the database as `src/lib/db` while the query asked for
+    // `src/lib/db.ts`, and the two never met.
+    //
+    // A relative specifier is resolved against its source file's directory; an
+    // expanded alias is ALREADY project-relative and must not be — joining it to
+    // the importer's directory would produce `src/app/src/lib/db`. So the two
+    // take different routes to the same place: add the extension either way.
     const resolveDst = (srcFile, dst) => {
-      if (typeof dst !== "string" || !dst.startsWith(".")) return dst; // package/external
+      if (typeof dst !== "string" || !dst) return dst;
+
+      if (!dst.startsWith(".")) {
+        // Not relative. Either a package ("react", "next/navigation") or an
+        // alias the indexer already expanded to a project path. The file set is
+        // what tells them apart — a package matches nothing in it.
+        const base = norm(dst);
+        for (const ext of EXTS) {
+          if (fileIds.has(base + ext)) return base + ext;
+        }
+        return dst; // genuinely external — keep it exactly as written
+      }
+
       const base = path.posix.normalize(path.posix.join(path.posix.dirname(norm(srcFile)), norm(dst)));
       // Prefer an actual indexed file id (try the bare path, then common extensions).
       for (const ext of EXTS) {

package/bin/gsd-t.js

@@ -2917,10 +2917,129 @@ function createProjectChangelog(projectDir, projectName) {
   }
 }
 
+/**
+ * Does this project have a built code graph, and does it have code worth one?
+ *
+ * [RULE] health-reports-missing-graph-never-assumes-built
+ *
+ * binvoice, 2026-08-11: a session reached for the graph, found nothing, and fell
+ * back to grep — in an 827-file project. The tooling was installed and
+ * propagated like everywhere else; the index had simply never been built.
+ * Nothing builds it automatically, so a project has a graph only if someone once
+ * ran `gsd-t graph index` there by hand.
+ *
+ * Nothing ever said so. `update-all` reported the project as current, because it
+ * was — every file it ships was in place. The gap lived in state no propagation
+ * step creates, and stayed invisible until a session hit it mid-task.
+ *
+ * Reported, never auto-built: indexing a large repo is slow, and doing it to 33
+ * of them inside an update would be a surprise nobody asked for.
+ */
+function graphState(projectDir) {
+  // Where the store lives is the resolver's answer alone. If it cannot answer,
+  // this check HALTS the caller rather than reporting a project as healthy — a
+  // silent "graph fine" here is exactly the blindness being fixed.
+  const resolver = require("./gsd-t-graph-store-resolver.cjs");
+  const storePath = resolver.resolveStorePath(projectDir);
+  if (storePath && fs.existsSync(storePath)) return { missing: false, files: 0 };
+
+  // A graph at the pre-M99 location (.gsd-t/graph.db) EXISTS — it is just where
+  // the resolver no longer looks. Telling the user to build one would be wrong
+  // twice over: the work is already done, and the real problem (a store the
+  // tooling cannot find) would go unnamed.
+  const legacyPath = resolver.resolveLegacyStorePath(projectDir);
+  if (legacyPath && fs.existsSync(legacyPath)) return { missing: false, files: 0, legacy: true };
+
+  let n = 0;
+  const SKIP = new Set(["node_modules", ".git", ".next", "dist", "build", ".venv", "venv", "out", "coverage"]);
+  const EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]);
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    if (n > 400) return; // enough to answer "is this a real codebase?"
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      // An unreadable subdirectory makes the count a floor, not a lie: the
+      // result is only ever compared against a low threshold, and a miscount
+      // downward can only omit a project from a report, never invent one.
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (SKIP.has(e.name)) continue;
+        if (e.name.startsWith(".")) continue;
+        walk(path.join(dir, e.name), depth + 1);
+        continue;
+      }
+      if (EXT.has(path.extname(e.name))) n++;
+    }
+  };
+  walk(projectDir, 0);
+
+  // A project with almost no source has nothing for a graph to map; calling that
+  // "missing" would be noise on every docs-only or config-only repo.
+  return { missing: n >= 25, files: n };
+}
+
+/**
+ * Move a graph that sits at the pre-M99 path into the one the tooling reads.
+ *
+ * The store already holds a full index — M99 changed where every tool LOOKS
+ * without moving what was there, so the graph was present and unreachable. The
+ * resolver's own migration does the move, checkpoints the write-ahead log, and
+ * verifies the result is readable.
+ */
+function migrateLegacyGraph(projectDir) {
+  try {
+    const r = require("./gsd-t-graph-store-resolver.cjs").migrateGraphStore(projectDir);
+    if (r && r.migrated) return { ok: true };
+    return { ok: false, err: (r && r.reason) || "migration reported no result" };
+  } catch (e) {
+    return { ok: false, err: e.message || String(e) };
+  }
+}
+
+/**
+ * Build a project's code graph from scratch.
+ *
+ * Slow on a large repo, so the caller announces it before this runs. A failure
+ * is returned, never swallowed: a project left without a graph must say so, so
+ * the next session halts instead of quietly grepping.
+ */
+function buildGraph(projectDir) {
+  try {
+    const idx = path.join(__dirname, "gsd-t-graph-index.cjs");
+    const r = require("child_process").spawnSync(process.execPath, [idx], {
+      cwd: projectDir,
+      encoding: "utf8",
+      timeout: 15 * 60 * 1000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (r.error) return { ok: false, err: r.error.message };
+    if (r.status !== 0) {
+      const tail = String(r.stderr || r.stdout || "").trim().split("\n").slice(-2).join(" ");
+      return { ok: false, err: `exit ${r.status}${tail ? ` — ${tail}` : ""}` };
+    }
+    // The indexer reporting success is not proof a store landed. Verify the file
+    // the tooling will actually read.
+    const storePath = require("./gsd-t-graph-store-resolver.cjs").resolveStorePath(projectDir);
+    if (!fs.existsSync(storePath)) return { ok: false, err: "indexer reported success but no store was written" };
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, err: e.message || String(e) };
+  }
+}
+
 async function checkProjectHealth(projects) {
   heading("Project Health");
   const playwrightMissing = [];
   const swaggerMissing = [];
+  const graphMissing = [];
+  const graphLegacy = [];
+  const graphMigrated = [];
+  const graphBuilt = [];
+  const graphRepairFailed = [];
   const playwrightAutoInstalled = [];
   const playwrightInstallFailed = [];
 
@@ -2929,6 +3048,42 @@ async function checkProjectHealth(projects) {
     const name = path.basename(projectDir);
     if (!hasPlaywright(projectDir)) playwrightMissing.push(name);
     if (hasApi(projectDir) && !hasSwagger(projectDir)) swaggerMissing.push(name);
+    const g = graphState(projectDir);
+    if (g.missing) graphMissing.push({ name, dir: projectDir, files: g.files });
+    if (g.legacy) graphLegacy.push({ name, dir: projectDir });
+  }
+
+  // [RULE] graph-missing-is-built-not-reported
+  //
+  // A missing graph is not a status to report — it is work to do. Every session
+  // in a project without one silently falls back to grep, which reads a fraction
+  // of what the graph knows and answers a different question. Reporting it and
+  // moving on leaves that in place until a human notices, which for binvoice
+  // (827 files) meant months.
+  //
+  // Two different faults, two different repairs:
+  //
+  //   · at the old path  — the store EXISTS and holds a full index. M99 changed
+  //     where the tooling looks without moving what was there, so 18 projects
+  //     were reading past a perfectly good graph. This is a file move plus a
+  //     write-ahead-log checkpoint, and takes no time at all.
+  //   · never built      — there is nothing to move. Indexing is genuinely slow
+  //     on a large repo, so this is announced before it runs rather than
+  //     appearing as an unexplained pause.
+  //
+  // A repair that fails is REPORTED and the project is left as it was. It is not
+  // retried differently and never half-applied: a graph that came up short would
+  // answer confidently with partial data, which is worse than not having one.
+  for (const { name, dir } of graphLegacy) {
+    const r = migrateLegacyGraph(dir);
+    if (r.ok) graphMigrated.push(name);
+    else graphRepairFailed.push({ name, what: "move", err: r.err });
+  }
+  for (const { name, dir, files } of graphMissing) {
+    log(`  building code graph for ${name} (${files}+ source files) — first build, this takes a while`);
+    const r = buildGraph(dir);
+    if (r.ok) graphBuilt.push(name);
+    else graphRepairFailed.push({ name, what: "build", err: r.err });
   }
 
   // M50 D1: auto-install Playwright for any UI project that's missing it.
@@ -2947,6 +3102,19 @@ async function checkProjectHealth(projects) {
     }
   }
 
+  if (graphMigrated.length > 0) {
+    success(`Code graph moved to where the tooling reads it: ${graphMigrated.join(", ")}`);
+  }
+  if (graphBuilt.length > 0) {
+    success(`Code graph built: ${graphBuilt.join(", ")}`);
+  }
+  if (graphRepairFailed.length > 0) {
+    for (const f of graphRepairFailed) {
+      warn(`  ${f.name} — graph ${f.what} FAILED: ${f.err}`);
+    }
+    info("Those projects have no usable graph. Fix before working in them — a session there cannot answer structural questions.");
+  }
+
   if (playwrightMissing.length === 0 && swaggerMissing.length === 0) {
     success("All projects have Playwright and Swagger configured");
   } else {
@@ -2978,6 +3146,11 @@ async function checkProjectHealth(projects) {
   return {
     playwrightMissing,
     swaggerMissing,
+    graphMissing,
+    graphLegacy,
+    graphMigrated,
+    graphBuilt,
+    graphRepairFailed,
     playwrightAutoInstalled,
     playwrightInstallFailed,
   };
@@ -3155,6 +3328,7 @@ async function doUpdateAll() {
     playwrightMissing,
     swaggerMissing,
     playwrightAutoInstalled,
+    graphMissing,
   } = await checkProjectHealth(projects);
   showUpdateAllSummary(
     projects.length,
@@ -3163,6 +3337,7 @@ async function doUpdateAll() {
     swaggerMissing,
     syncCount,
     playwrightAutoInstalled,
+    graphMissing,
   );
 }
 
@@ -3693,6 +3868,7 @@ function showUpdateAllSummary(
   swaggerMissing,
   syncCount,
   playwrightAutoInstalled,
+  graphMissing,
 ) {
   log("");
   heading("Update All Complete");
@@ -3706,6 +3882,9 @@ function showUpdateAllSummary(
     log(`  Auto-installed Playwright in: ${playwrightAutoInstalled.length} project(s)`);
   }
   if (swaggerMissing.length > 0) log(`  Missing Swagger:     ${swaggerMissing.length}`);
+  if (Array.isArray(graphMissing) && graphMissing.length > 0) {
+    log(`  No code graph:       ${graphMissing.length}`);
+  }
   if (syncCount > 0) log(`  Global rules synced: ${syncCount}`);
   log("");
 }
@@ -5336,6 +5515,7 @@ function showHelp() {
 // ─── Exports (for testing) ───────────────────────────────────────────────────
 
 module.exports = {
+  graphState,
   validateProjectName,
   applyTokens,
   normalizeEol,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.11.27",
-  "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",
+  "version": "5.11.29",
+  "description": "GSD-T: Contract-Driven Development for Claude Code \u2014 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",
   "repository": {

package/templates/CLAUDE-global.md

@@ -310,6 +310,25 @@ When any GSD-T command creates or modifies an API endpoint:
 
 This applies during: `gsd-t-execute`, `gsd-t-quick`, `gsd-t-integrate`, `gsd-t-wave`, and any command that touches API code.
 
+## Code Graph — build it, never grep around it (MANDATORY)
+
+**Read code structure through the graph. If the graph is missing, BUILD it. If it is out of date, UPDATE it. Grep only where the answer cannot be indexed.**
+
+```
+NEED A STRUCTURAL ANSWER? (what imports this, who calls this, what breaks if I change it)
+  ├── Graph present and fresh?      → query it
+  ├── Graph missing?                → `gsd-t graph index` — BUILD IT, then query
+  ├── Graph stale?                  → re-index the touched set, then query
+  ├── Graph at the old path?        → it EXISTS; move it (`gsd-t graph index`), then query
+  └── Build/repair FAILED?          → HALT and say so. Never answer the structural question by grep.
+```
+
+**Grep is correct ONLY where the content cannot be indexed** — `.md`, `.sql`, `.json`, `.sh`, config, prose, comments. For anything about code structure, grep is not a weaker answer, it is a **different and wrong one**: it matches text, the question is about relationships.
+
+**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.
+
+**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
 KEEP GOING. Only stop for:
 1. Unrecoverable errors after 2 fix attempts (delegate to `gsd-t headless --debug-loop` first — only stop if exit code 4)