@tekyzinc/gsd-t 5.0.10 → 5.0.12

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.0.12] - 2026-07-12
+
+### Fixed — graph require-chain shipped incomplete → every project's graph silently dead
+
+`bin/gsd-t-graph-query-cli.cjs` `require()`s `gsd-t-graph-store-resolver.cjs` at load, but that file (added to source in M99, 2026-06-30) was never added to `PROJECT_BIN_TOOLS` — so `update-all` copied the query CLI and 6 of its 7 dependencies and silently omitted the 7th. In every registered project the CLI threw on load → the graph was unqueryable → all graph consumers (execute/wave/debug/quick/impact/plan/scan **and `/gsd-t-architect`**) silently fell back to grep. Found by the Binvoice architect run reporting its own reuse-check was disabled. Same class as the M96 / global-bin propagation gaps.
+
+- `bin/gsd-t.js`: added `gsd-t-graph-store-resolver.cjs` to `PROJECT_BIN_TOOLS`; exported `PROJECT_BIN_TOOLS`.
+- `test/graph-require-chain-propagation.test.js` (NEW): statically walks the transitive `require("./…")` chain from the graph entry points and FAILS if any reachable `bin/` file is missing from `PROJECT_BIN_TOOLS` — the mechanical guard that turns this whole drift class into a red test instead of a silent grep-fallback. Proven to fail when the resolver is removed.
+- `.gsd-t/contracts/graph-metrics-contract.md`: refreshed two `bin/gsd-t.js` line citations shifted by the fix.
+
+## [5.0.11] - 2026-07-12
+
+### Fixed — architect hook now ships + installs; de-flaked its test
+
+The M101/v5.0.10 architect-oversight hook existed only in `~/.claude/scripts/` — it was never copied into the repo, so `install`/`update-all` would not propagate it to other machines (the "propagate a tool without shipping it = silent no-op" class). This release ships it properly and hardens it.
+
+- `scripts/gsd-t-architect-oversight-guard.js`: the hook now lives in the repo (ships with the package). Added an unref'd 1500ms watchdog + a stdin `error` handler so the hook can NEVER hang and block a Write/Edit (fail-open guaranteed even if stdin never EOFs).
+- `bin/gsd-t.js`: `configureArchitectHook()` registers the PreToolUse `Write|Edit` hook via the global-package command pattern (same as the graph/read-intercept hooks); wired into `install`; removed on `uninstall`. Exported for tests.
+- `test/m101-architect-oversight-hook.test.js`: replaced the two spawn-per-assertion fail-open tests (which false-failed under full-suite CPU starvation, not a hook bug) with a source-guard assertion + installer idempotency/coexistence tests. Test resolves the repo hook copy.
+- `.gsd-t/contracts/graph-metrics-contract.md`: refreshed the `doMetrics` line citation (shifted by the installer addition).
+
 ## [5.0.10] - 2026-07-12
 
 ### Added — `/gsd-t-architect`: run the Architect's Oversight pass on demand

package/README.md

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

@@ -485,6 +485,15 @@ 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\'';
 
+// M101 — architect-oversight PreToolUse hook on Write|Edit. Same global-package
+// pattern as the intercept hooks: runs the script from the globally-installed
+// package, and the script fails-open (no-op) in non-GSD-T projects / prose writes,
+// so it is safe to register globally with a Write|Edit matcher. It reminds the model
+// to run the Architect's Oversight Six-Stage Pass before writing code (M101).
+const ARCHITECT_HOOK_MARKER = "gsd-t-architect-oversight-guard";
+const ARCHITECT_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.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) {
@@ -928,6 +937,60 @@ function configureReadInterceptHook(settingsPath) {
   return { installed: true, action };
 }
 
+// M101 — register the architect-oversight PreToolUse hook (matcher "Write|Edit").
+// Idempotent: find-by-marker, refresh stale command, else add. Mirrors the M98
+// read-intercept installer but on PreToolUse. The script fails-open so this is
+// safe globally (silent in non-GSD-T projects and on prose/doc writes).
+function configureArchitectHook(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 architect hook");
+      return { installed: false, action: "noop" };
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
+
+  const cmd = ARCHITECT_HOOK_COMMAND;
+  let action = "noop";
+  let found = false;
+  for (const entry of settings.hooks.PreToolUse) {
+    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(ARCHITECT_HOOK_MARKER)) {
+        found = true;
+        if (h.command !== cmd) { h.command = cmd; action = "updated"; }
+        if (entry.matcher !== "Write|Edit") { entry.matcher = "Write|Edit"; action = action === "noop" ? "updated" : action; }
+      }
+    }
+  }
+  if (!found) {
+    settings.hooks.PreToolUse.push({
+      matcher: "Write|Edit",
+      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) {
@@ -941,17 +1004,28 @@ function removeInterceptHooks(settingsPath) {
     warn("settings.json has invalid JSON — cannot remove intercept hooks");
     return false;
   }
-  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return false;
+  if (!settings.hooks) 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;
+  const postMarkers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
+  const preMarkers = [ARCHITECT_HOOK_MARKER];
+  let removed = 0;
+
+  const stripByMarkers = (arr, markers) => {
+    if (!Array.isArray(arr)) return arr;
+    const before = arr.length;
+    const out = arr.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))
+      );
+    });
+    removed += before - out.length;
+    return out;
+  };
+
+  settings.hooks.PostToolUse = stripByMarkers(settings.hooks.PostToolUse, postMarkers);
+  settings.hooks.PreToolUse = stripByMarkers(settings.hooks.PreToolUse, preMarkers);
+  if (removed === 0) return false;
 
   if (isSymlink(targetPath)) {
     warn("Skipping settings.json write — target is a symlink");
@@ -1915,6 +1989,13 @@ async function doInstall(opts = {}) {
     else info("Read-intercept hook already configured");
   }
 
+  const archHook = configureArchitectHook(SETTINGS_JSON);
+  if (archHook.installed) {
+    if (archHook.action === "added") success("Architect-oversight hook added (Six-Stage Pass reminder before writing code — M101)");
+    else if (archHook.action === "updated") success("Architect-oversight hook refreshed");
+    else info("Architect-oversight hook already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 
@@ -2901,6 +2982,13 @@ const PROJECT_BIN_TOOLS = [
   // [[project_code_graph_universal_consumer]] [[feedback_graph_is_architectural_anchor]]
   "gsd-t-graph-query-cli.cjs", "gsd-t-graph-index.cjs", "gsd-t-graph-freshness.cjs",
   "gsd-t-graph-edge-extract.cjs", "gsd-t-graph-scip-upgrade.cjs", "gsd-t-scip-reader.cjs",
+  // M99 (added 2026-06-30, resolver added to the copy list 2026-07-12) — the query
+  // CLI `require`s gsd-t-graph-store-resolver.cjs at load time (line ~76). It was
+  // added to the source in M99 but NEVER added here, so update-all copied the CLI
+  // and 6 of its 7 deps and silently omitted this one → the CLI threw on require →
+  // graph dead → grep fallback (found by the Binvoice architect run 2026-07-12).
+  // Same class as [[project_global_bin_propagation_gap]] / [[project_m96_graph_runs_in_projects]].
+  "gsd-t-graph-store-resolver.cjs",
   // M96 — multi-location resolver for the store engine (better-sqlite3), so a
   // copied tool finds the engine from the GSD-T global package, not the project's
   // own (usually absent) node_modules. Fail-loud with remediation if all miss.
@@ -4831,6 +4919,7 @@ module.exports = {
   ensureDir,
   copyFile,
   copyBinToolsToProject,
+  PROJECT_BIN_TOOLS,
   hasPlaywright,
   hasSwagger,
   hasApi,
@@ -4909,6 +4998,7 @@ module.exports = {
   // M97/M98: intercept hook installers
   configureGraphInterceptHook,
   configureReadInterceptHook,
+  configureArchitectHook,
   removeInterceptHooks,
   promptForApiKeyIfMissing,
   resolveApiKeyEnvVar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.0.10",
+  "version": "5.0.12",
   "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-architect-oversight-guard.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * GSD-T PreToolUse hook (Write|Edit) — Architect's Oversight trigger (M101).
+ *
+ * The Architect's Oversight Doctrine lives in ~/.claude/CLAUDE.md, but a doctrine
+ * carried in context can be MISSED under load. This hook fires the TRIGGER at the
+ * exact moment it matters — right before code is written/edited — and injects a
+ * ONE-LINE pointer back to the doctrine. It carries NO nuance (that stays in
+ * CLAUDE.md); it only guarantees the Six-Stage Pass is CONSIDERED before a build.
+ *
+ * Design (mirrors the doctrine's §Enforcement three-layer split):
+ *   - CLAUDE.md  = the definition (what the doctrine IS)
+ *   - THIS hook  = the trigger    (don't forget it right now, no context bloat)
+ *   - workflow   = the execution  (actually run the stages, with evidence)
+ *
+ * Receives JSON on stdin: { tool_name, tool_input: { file_path, ... }, cwd, ... }
+ * Emits (stdout, PreToolUse additionalContext): a single reminder line, or nothing.
+ *
+ * NON-NEGOTIABLE: fail-open. Never block the tool, never throw, never exit non-zero.
+ * A malformed payload, missing field, or any error → silent pass-through (exit 0,
+ * no output). This hook can only ADD a reminder; it can never stop a write.
+ *
+ * Scope gates (emit ONLY when all hold), to avoid noise:
+ *   1. GSD-T project — cwd contains .gsd-t/ (matches the auto-route/profile gate).
+ *   2. The target is CODE, not prose — skip .md / .txt / pseudocode / docs, since
+ *      the doctrine's own artifacts (CLAUDE.md, pseudocode, contracts) are writes
+ *      too, and reminding while writing the reminder is noise. Code = the moment
+ *      the Binvoice waste would have been caught.
+ *
+ * Zero-dep by design: runs from ~/.claude/scripts where the package may be absent.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// One line. A pointer, not the doctrine. Keeps context cost ~nil.
+const REMINDER =
+  "[GSD-T ARCHITECT] About to write/edit code — run the Architect's Oversight " +
+  "Six-Stage Pass FIRST (Objective → Conflict → Reuse[query the graph] → " +
+  "Simplicity → Reuse-forecast → Risk), each answered with evidence not conviction. " +
+  "Is this the simplest design, and does something reusable already exist? " +
+  "See ~/.claude/CLAUDE.md § Architect's Oversight Doctrine.";
+
+// File extensions that are PROSE/config, not code — skip the reminder for these.
+// (The doctrine's own artifacts are markdown; reminding while authoring them is noise.)
+const PROSE_EXT = new Set([
+  ".md", ".markdown", ".txt", ".rst", ".adoc",
+  ".json", ".yaml", ".yml", ".toml", ".lock",
+  ".csv", ".tsv", ".svg", ".png", ".jpg", ".jpeg", ".gif", ".pdf",
+]);
+
+/**
+ * Decide whether to emit the reminder for a given cwd + target file.
+ * Pure + total: never throws, returns a boolean.
+ * @param {string} cwd
+ * @param {string} filePath — the Write/Edit target
+ * @returns {boolean}
+ */
+function shouldRemind(cwd, filePath) {
+  try {
+    if (!cwd || typeof cwd !== "string") return false;
+    // Gate 1 — GSD-T project only.
+    if (!fs.existsSync(path.join(cwd, ".gsd-t"))) return false;
+    // No target path → can't classify → stay quiet (fail-open toward silence).
+    if (!filePath || typeof filePath !== "string") return false;
+
+    const lower = filePath.toLowerCase();
+    const ext = path.extname(lower);
+
+    // Gate 2 — skip prose/config/asset writes (incl. the doctrine's own artifacts).
+    if (PROSE_EXT.has(ext)) return false;
+    // Skip anything under a docs/ or pseudocode/ tree even if code-extensioned.
+    if (/[\\/](docs|pseudocode)[\\/]/.test(lower)) return false;
+
+    return true;
+  } catch (_) {
+    return false; // fail-open: any error → no reminder, never block
+  }
+}
+
+if (require.main === module) {
+  let input = "";
+  let done = false;
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+
+  const finish = () => {
+    if (done) return; // run once — whichever of end/error/watchdog fires first
+    done = true;
+    try {
+      let data = null;
+      try { data = JSON.parse(input); } catch (_) { process.exit(0); }
+      if (!data || typeof data !== "object") process.exit(0);
+
+      const cwd = (typeof data.cwd === "string" && data.cwd) ? data.cwd : process.cwd();
+      const ti = data.tool_input && typeof data.tool_input === "object" ? data.tool_input : {};
+      const filePath = typeof ti.file_path === "string" ? ti.file_path : "";
+
+      if (shouldRemind(cwd, filePath)) {
+        process.stdout.write(REMINDER + "\n");
+      }
+    } catch (_) {
+      // Belt-and-suspenders: never block a write.
+    }
+    process.exit(0);
+  };
+
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish); // stdin read error → fail-open, never hang
+  // Watchdog: if stdin never delivers EOF (spawn-under-load edge, closed pipe),
+  // proceed anyway with whatever we have. A hook must NEVER hang and block a write.
+  const wd = setTimeout(finish, 1500);
+  if (wd.unref) wd.unref(); // don't keep the event loop alive solely for the watchdog
+}
+
+module.exports = { shouldRemind, REMINDER };