@tekyzinc/gsd-t 5.11.28 → 5.11.30

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.11.30] - 2026-08-11
+
+### Fixed — the scan crashed before any finder ran: `slices is not defined`
+
+The Atos scan died after 4 agents (preflight, probe, graph-wiring) with a
+JavaScript reference error. Nothing was written; no finder ever started.
+
+    618:  slices = budgetPlan.slices;   // never declared at this scope
+
+v5.11.26 added that assignment to a bare name. v5.11.27 then added a
+`const slices` INSIDE a helper function — a different scope entirely, which made
+the name look declared to anyone skimming the file. The workflow sandbox runs in
+strict mode, where assigning to an undeclared name throws.
+
+`slices` is now declared where the code that uses it runs, starting as the
+probe's own carve so the budget-failed branch needs no assignment at all.
+
+**Nothing caught this, which is the more important half.** `node --check` parses
+an undeclared assignment happily — it is legal syntax, and only strict mode makes
+it an error, at runtime. The sandbox lint checks banned requires and `args`
+handling, not scope. No test executes this path, because the workflow only runs
+against a real project.
+
+- `templates/workflows/gsd-t-scan.workflow.js`: `let slices = rawSlices` at the
+  scope that runs them.
+- `test/m112-workflow-undeclared-assignment.test.js`: a static check over every
+  workflow for an assignment to a name its scope never declares, with a
+  function-body map so an `if`/`else` block is not mistaken for a nested scope.
+
+The check was itself wrong twice before it worked, and the meta-test is what
+caught it: the first version tested a hand-written sample with the offending line
+at column zero and passed while missing the real bug, which is indented two
+spaces inside an `if`. Verified against the actual shipped file — it reports
+line 618 there and passes the fixed one.
+
+## [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)

package/README.md

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

package/templates/workflows/gsd-t-scan.workflow.js

@@ -602,6 +602,21 @@ const budgetPlan = await runCli(
   "slice-budget"
 );
 
+// What the finders will actually run. Declared HERE, at the scope that uses it.
+//
+// [RULE] slices-declared-at-the-scope-that-runs-them
+//
+// v5.11.26 assigned to a bare `slices` that was never declared anywhere, and
+// v5.11.27 added a `const slices` inside probePlaceholderFaults() — a different
+// scope entirely. The workflow sandbox runs in strict mode, so the assignment
+// below threw `slices is not defined` and killed the Atos scan after 4 agents,
+// before a single finder ran. Nothing had checked it: `node --check` parses an
+// undeclared assignment happily, and no test executed this path.
+//
+// It starts as the probe's own slices, so the failure branch below needs no
+// assignment — an unmeasured plan still runs what the probe carved.
+let slices = rawSlices;
+
 if (budgetPlan && budgetPlan.ok && Array.isArray(budgetPlan.slices) && budgetPlan.slices.length) {
   const a = budgetPlan.after || {};
   if (budgetPlan.slices.length > rawSlices.length) {