@tekyzinc/gsd-t 5.8.10 → 5.9.10

package/scripts/gsd-t-concise-hook.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-concise-hook.js
+ *
+ * M107-D2 — Stop hook. Sends a long reply to a fresh Claude for a shorter
+ * rewrite, then blocks the stop so the short version is what David reads.
+ *
+ * [RULE] concise-hook-never-loops
+ * [RULE] concise-hook-fails-open-on-rewrite-failure
+ *
+ * A Stop hook cannot edit a reply that is already written. It can only block
+ * the stop and hand back an instruction. So: read the reply from the
+ * transcript, get the short version, and block once with "replace your last
+ * reply with this". The model then emits the short version and stops.
+ *
+ * ─── Stdin (Claude Code Stop payload) ───────────────────────────────────────
+ *   { "transcript_path": "...", "stop_hook_active": true|false, "cwd": "..." }
+ *
+ * ─── Loop guard ─────────────────────────────────────────────────────────────
+ *   stop_hook_active === true means this Stop is already a re-entry from our
+ *   own block. Exit 0 immediately. One rewrite per turn, never two.
+ *
+ * ─── Fail-open, deliberately ────────────────────────────────────────────────
+ *   Unlike the fallback guard, this one ALLOWS on failure. It governs how a
+ *   reply READS, not whether it is true. A broken rewriter must never gag a
+ *   correct answer — showing a long reply is a poor outcome, showing none is a
+ *   wrong one. The rewriter itself returns the original when it cannot do
+ *   better, so no content is ever lost.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const DEFAULT_SKIP_UNDER = 60; // words
+
+function allow() { process.exit(0); }
+
+function block(reason) {
+  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
+  process.exit(0);
+}
+
+/** Only read transcripts from the Claude projects directory. */
+function safeTranscriptPath(p) {
+  if (typeof p !== "string" || !p) return null;
+  if (!path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const root = path.resolve(home, ".claude", "projects") + path.sep;
+  const resolved = path.resolve(p);
+  return resolved.startsWith(root) ? resolved : null;
+}
+
+function readTail(filePath, bytes) {
+  let fd = -1;
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile() || st.size === 0) return "";
+    const want = Math.min(bytes, st.size);
+    const start = st.size - want;
+    fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(want);
+    fs.readSync(fd, buf, 0, want, start);
+    let s = buf.toString("utf8");
+    if (start > 0) {
+      const nl = s.indexOf("\n");
+      if (nl >= 0) s = s.slice(nl + 1);
+    }
+    return s;
+  } catch (_) {
+    return "";
+  } finally {
+    if (fd >= 0) { try { fs.closeSync(fd); } catch (_) { /* already closed */ } }
+  }
+}
+
+/**
+ * Pull the last assistant turn's visible text from the transcript.
+ * Returns { text, toolOnly } — a tool-only turn has no prose to shorten.
+ */
+function lastAssistantText(transcriptPath) {
+  const tail = readTail(transcriptPath, 512 * 1024);
+  if (!tail) return null;
+  const lines = tail.split("\n").filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let rec;
+    try { rec = JSON.parse(lines[i]); } catch (_) { continue; }
+    const msg = rec && rec.message;
+    if (!msg || msg.role !== "assistant") continue;
+    const content = Array.isArray(msg.content) ? msg.content : [];
+    const text = content.filter((b) => b && b.type === "text")
+      .map((b) => b.text || "").join("\n").trim();
+    const hasTool = content.some((b) => b && b.type === "tool_use");
+    return { text, toolOnly: !text && hasTool };
+  }
+  return null;
+}
+
+function wordCount(s) {
+  return (String(s).trim().match(/\S+/g) || []).length;
+}
+
+function readConfig(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "concise.json");
+  if (!fs.existsSync(p)) return { enabled: true, skipUnder: DEFAULT_SKIP_UNDER };
+  try {
+    const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+    return {
+      enabled: cfg.enabled !== false,
+      skipUnder: Number.isFinite(cfg.skipUnder) ? cfg.skipUnder : DEFAULT_SKIP_UNDER,
+    };
+  } catch (_) {
+    return { enabled: true, skipUnder: DEFAULT_SKIP_UNDER };
+  }
+}
+
+/**
+ * Locate the rewriter. Every project carries its own copy; if it does not, the
+ * install is broken and the SessionStart heal hook repairs it. Two exact
+ * locations, no hunting.
+ */
+function findRewriter(projectDir) {
+  const inProject = path.join(projectDir, "bin", "gsd-t-concise-rewrite.cjs");
+  if (fs.existsSync(inProject)) return inProject;
+  const inPackage = path.join(__dirname, "..", "bin", "gsd-t-concise-rewrite.cjs");
+  if (fs.existsSync(inPackage)) return inPackage;
+  return null; // the caller lets the reply through — see the note on main()
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+
+  const finish = () => {
+    if (done) return;
+    done = true;
+
+    let data;
+    try { data = JSON.parse(input); } catch (_) { return allow(); }
+    if (!data || typeof data !== "object") return allow();
+
+    // One rewrite per turn. This Stop is our own re-entry — let it through.
+    if (data.stop_hook_active === true) return allow();
+
+    const cwd = (typeof data.cwd === "string" && data.cwd) ? data.cwd : process.cwd();
+    const cfg = readConfig(cwd);
+    if (!cfg.enabled) return allow();
+
+    const tPath = safeTranscriptPath(data.transcript_path);
+    if (!tPath) return allow();
+
+    const last = lastAssistantText(tPath);
+    if (!last || last.toolOnly || !last.text) return allow();
+    if (wordCount(last.text) < cfg.skipUnder) return allow();
+
+    const rewriter = findRewriter(cwd);
+    if (!rewriter) return allow();
+
+    const run = spawnSync(process.execPath,
+      [rewriter, "--text", last.text, "--project", cwd, "--json"],
+      { encoding: "utf8", timeout: 60000, maxBuffer: 8 * 1024 * 1024 });
+
+    if (run.error || !run.stdout) return allow();
+
+    let result;
+    try { result = JSON.parse(run.stdout); } catch (_) { return allow(); }
+
+    // The rewriter returns the original when it cannot do better. Nothing was
+    // lost, so there is nothing to replace.
+    if (!result.ok || !result.text || result.skipped) return allow();
+    if (result.text.trim() === last.text.trim()) return allow();
+
+    const saved = (result.words || 0) - (result.wordsAfter || 0);
+    if (saved < 15) return allow(); // not worth the extra turn
+
+    block(
+      "Your last reply was longer than it needed to be. Replace it with this " +
+      "shorter version, exactly as written, and add nothing:\n\n" +
+      result.text
+    );
+  };
+
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish);
+  const wd = setTimeout(finish, 70000);
+  if (wd.unref) wd.unref();
+}
+
+if (require.main === module) main();
+
+module.exports = { lastAssistantText, wordCount, readConfig, findRewriter, safeTranscriptPath };

package/scripts/gsd-t-fallback-guard.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-fallback-guard.js
+ *
+ * M106-D2 — PreToolUse hook on Write|Edit. Denies a write that introduces a
+ * fallback the user never approved.
+ *
+ * [RULE] fallback-guard-denies-unapproved
+ * [RULE] fallback-guard-halts-never-allows-on-error
+ *
+ * A fallback added while chasing a bug never appears in any plan — this is the
+ * only trigger point that can catch it, because it fires at the moment the code
+ * is written.
+ *
+ * ─── Stdin (Claude Code PreToolUse payload) ─────────────────────────────────
+ *   { "tool_name": "Write"|"Edit", "cwd": "...",
+ *     "tool_input": { "file_path": "...", "content"|"new_string": "..." } }
+ *
+ * ─── Decision contract ──────────────────────────────────────────────────────
+ *   Deny:  {"hookSpecificOutput":{"hookEventName":"PreToolUse",
+ *           "permissionDecision":"deny","permissionDecisionReason":"..."}}
+ *   Allow: exit 0, no output.
+ *
+ * ─── HALT, never allow-on-error ─────────────────────────────────────────────
+ *   This guard governs the No-Fallback rule, so it must not contain one. If the
+ *   detector cannot run or its answer cannot be read, the write is DENIED with
+ *   the reason — never quietly permitted. The single exception is a payload
+ *   that is not a Write/Edit of source at all: that is "not applicable", not a
+ *   failure, and it exits 0.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const SOURCE_EXT = new Set([".js", ".cjs", ".mjs", ".jsx", ".ts", ".tsx"]);
+const TEST_PATH_RE = /(?:^|[\\/])(?:test|tests|__tests__|spec|e2e|fixtures?)[\\/]|\.(?:test|spec)\.[cm]?[jt]sx?$/i;
+
+function deny(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  }) + "\n");
+  process.exit(0);
+}
+
+function allow() { process.exit(0); }
+
+/**
+ * Locate the detector.
+ *
+ * Every project is supposed to carry its own copy. If it does not, the
+ * project's install is broken, and the answer is to REPAIR it — which the
+ * SessionStart heal hook does — not to hunt around for a copy somewhere else.
+ * Hunting is what let binvoice run for weeks on 20 of 38 tools while every
+ * update reported success.
+ *
+ * Returns the path, or throws with what is wrong. It never returns "not found"
+ * as if that were an ordinary answer.
+ */
+function findDetector(projectDir) {
+  const inProject = path.join(projectDir, "bin", "gsd-t-fallback-detect.cjs");
+  if (fs.existsSync(inProject)) return inProject;
+
+  // Running from inside the package itself (developing GSD-T).
+  const inPackage = path.join(__dirname, "..", "bin", "gsd-t-fallback-detect.cjs");
+  if (fs.existsSync(inPackage)) return inPackage;
+
+  throw new Error(
+    `This project has no copy of the fallback detector at ${inProject}, which means ` +
+    `its GSD-T install is incomplete. Run 'gsd-t install-check' to repair it — do not ` +
+    `work around it.`
+  );
+}
+
+/** Thrown when the settings file exists but cannot be understood. */
+class ConfigUnreadable extends Error {}
+
+/**
+ * Is the gate switched on for this project?
+ *
+ * A settings file that cannot be read is NOT assumed to mean "on" — that would
+ * be a guess about what the project wanted. It throws, and the caller denies
+ * the write and says why. Only an ABSENT file means "on", because absence is
+ * unambiguous.
+ */
+function isEnabled(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "fallback-gate.json");
+  if (!fs.existsSync(p)) return true; // absent = on, by design
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new ConfigUnreadable(`${p} could not be read: ${e.message}`);
+  }
+  const cfg = JSON.parse(raw); // a parse failure throws, and the caller denies
+  return cfg.enabled !== false;
+}
+
+function buildReason(findings, filePath) {
+  const lines = [
+    `This write adds ${findings.length === 1 ? "a fallback" : `${findings.length} fallbacks`} that was never approved.`,
+    "",
+  ];
+  for (const f of findings.slice(0, 5)) {
+    lines.push(`  ${f.what}`);
+    if (f.snippet) lines.push(`    ${f.snippet}`);
+    lines.push("");
+  }
+  lines.push(
+    "A fallback continues after a failure. It produces wrong data that looks correct,",
+    "and it removes the alarm for the bug that caused the failure.",
+    "",
+    "Do one of these:",
+    "",
+    "  1. Replace it with a halt — stop, and report what could not be done.",
+    "     This is almost always the right answer.",
+    "",
+    "  2. Ask David for approval. Tell him, in plain words:",
+    "       - what fails",
+    "       - how often it really fails, with evidence",
+    "       - why stopping is worse than continuing",
+    "       - what it does instead (never a guessed value, never a partial result)",
+    "     If he agrees, add the entry to .gsd-t/fallbacks.json and write again.",
+    "",
+    `  File: ${filePath}`
+  );
+  return lines.join("\n");
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+
+  const finish = () => {
+    if (done) return;
+    done = true;
+
+    let data;
+    try {
+      data = JSON.parse(input);
+    } catch (_) {
+      // An unparseable payload is not a write we can inspect — not applicable.
+      return allow();
+    }
+    if (!data || typeof data !== "object") return allow();
+
+    const tool = data.tool_name;
+    if (tool !== "Write" && tool !== "Edit") return allow();
+
+    const ti = (data.tool_input && typeof data.tool_input === "object") ? data.tool_input : {};
+    const filePath = typeof ti.file_path === "string" ? ti.file_path : "";
+    if (!filePath) return allow();
+
+    const ext = path.extname(filePath);
+    if (!SOURCE_EXT.has(ext)) return allow();          // not source — not applicable
+    if (TEST_PATH_RE.test(filePath.replace(/\\/g, "/"))) return allow(); // tests are exempt
+
+    const content = typeof ti.content === "string" ? ti.content
+      : typeof ti.new_string === "string" ? ti.new_string
+      : "";
+    if (!content.trim()) return allow();
+
+    const cwd = (typeof data.cwd === "string" && data.cwd) ? data.cwd : process.cwd();
+    let on;
+    try {
+      on = isEnabled(cwd);
+    } catch (e) {
+      return deny(
+        "The fallback gate's settings could not be read, so it is unclear whether\n" +
+        `this project has switched the gate off.\n\n${e.message}\n\n` +
+        "Fix the file, or delete it to leave the gate on."
+      );
+    }
+    if (!on) return allow();                          // switched off for this project
+
+    let detector;
+    try {
+      detector = findDetector(cwd);
+    } catch (e) {
+      return deny(
+        `${e.message}\n\n` +
+        "This write cannot be checked, and allowing it unchecked is exactly what this\n" +
+        "guard exists to prevent."
+      );
+    }
+
+    const run = spawnSync(process.execPath,
+      [detector, "--text", content, "--file", filePath, "--project", cwd, "--json"],
+      { encoding: "utf8", timeout: 10000, maxBuffer: 8 * 1024 * 1024 });
+
+    if (run.error || typeof run.stdout !== "string" || !run.stdout.trim()) {
+      return deny(
+        "The fallback check could not run, so this write cannot be verified.\n" +
+        `Reason: ${run.error ? run.error.message : "the detector produced no output"}\n\n` +
+        "This guard halts rather than letting an unchecked write through."
+      );
+    }
+
+    let result;
+    try {
+      result = JSON.parse(run.stdout);
+    } catch (_) {
+      return deny("The fallback check returned something unreadable, so this write cannot be verified.");
+    }
+
+    if (result.exitCode === 64) {
+      return deny(
+        `The fallback check could not decide: ${result.error || "unknown reason"}\n\n` +
+        (result.halt || "Fix the problem above, then write again.")
+      );
+    }
+
+    if (result.ok) return allow();
+
+    return deny(buildReason(result.findings || [], filePath));
+  };
+
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish);
+  const wd = setTimeout(finish, 8000);
+  if (wd.unref) wd.unref();
+}
+
+if (require.main === module) main();
+
+module.exports = { buildReason, findDetector, isEnabled };

package/scripts/gsd-t-install-heal.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-install-heal.js
+ *
+ * M108 — SessionStart hook. Checks this project's install, repairs what is
+ * missing, and reports anything it could not fix.
+ *
+ * [RULE] install-heal-repairs-before-work-starts
+ * [RULE] install-heal-reports-what-it-could-not-fix
+ *
+ * This is NOT a fallback. A fallback continues past a failure with a worse
+ * answer. This one FIXES the failure — copies the missing tool from the
+ * installed package — so the session then runs with everything present. When it
+ * cannot fix something it says so loudly rather than letting the session
+ * proceed on a broken install.
+ *
+ * It also surfaces the shared repair log: if the same tool keeps going missing
+ * across projects, the installer is what needs fixing, not each project.
+ *
+ * ─── Stdin (Claude Code SessionStart payload) ───────────────────────────────
+ *   { "hook_event_name": "SessionStart", "cwd": "...", "session_id": "..." }
+ *
+ * ─── Output ─────────────────────────────────────────────────────────────────
+ *   Prints to stdout, which Claude Code shows as session context. Silent when
+ *   the install is already complete — the common case, and no news is good news.
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync, execFileSync } = require("child_process");
+
+/**
+ * Find the install checker. It ships beside this hook, so one place answers it.
+ * Throws with what is wrong — never returns nothing as an ordinary answer.
+ */
+function findChecker() {
+  const beside = path.join(__dirname, "..", "bin", "gsd-t-install-check.cjs");
+  if (fs.existsSync(beside)) return beside;
+  throw new Error(
+    `The install checker is not at ${beside}, where it ships. The GSD-T install ` +
+    `itself is incomplete — reinstall it.`
+  );
+}
+
+function main() {
+  let input = "";
+  let done = false;
+
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (c) => { input += c; });
+
+  const finish = () => {
+    if (done) return;
+    done = true;
+
+    // Which project is this? The payload says. Guessing with process.cwd()
+    // could check — and repair — a different project than the one the session
+    // is in, so an unreadable payload stops instead.
+    let data;
+    try {
+      data = JSON.parse(input);
+    } catch (e) {
+      process.stdout.write(
+        `[GSD-T INSTALL] Could not tell which project this session is in, so its ` +
+        `install was not checked: ${e.message}\n`
+      );
+      process.exit(0);
+    }
+    const cwd = (data && typeof data.cwd === "string" && data.cwd) ? data.cwd : null;
+    if (!cwd) {
+      process.stdout.write(
+        "[GSD-T INSTALL] The session did not say which folder it is in, so this " +
+        "project's install was not checked.\n"
+      );
+      process.exit(0);
+    }
+
+    // Not a GSD-T project — nothing to check.
+    if (!fs.existsSync(path.join(cwd, ".gsd-t"))) { process.exit(0); }
+
+    let checker;
+    try {
+      checker = findChecker();
+    } catch (e) {
+      process.stdout.write(`[GSD-T INSTALL] ${e.message}\n`);
+      process.exit(0);
+    }
+
+    const run = spawnSync(process.execPath, [checker, "--project", cwd, "--json"], {
+      encoding: "utf8", timeout: 60000, maxBuffer: 8 * 1024 * 1024,
+    });
+
+    if (run.error || !run.stdout) {
+      process.stdout.write(
+        `[GSD-T INSTALL] The install check could not run: ${run.error ? run.error.message : "no output"}\n`
+      );
+      process.exit(0);
+    }
+
+    let result;
+    try {
+      result = JSON.parse(run.stdout);
+    } catch (_) {
+      process.stdout.write("[GSD-T INSTALL] The install check returned something unreadable.\n");
+      process.exit(0);
+    }
+
+    const repaired = result.repaired || [];
+    const unfixable = result.unrepairable || [];
+
+    if (repaired.length) {
+      process.stdout.write(
+        `[GSD-T INSTALL] This project was missing ${repaired.length} tool(s). ` +
+        `They have been restored from the installed package, and the session can proceed normally.\n`
+      );
+    }
+
+    if (unfixable.length) {
+      process.stdout.write(
+        `[GSD-T INSTALL] ${unfixable.length} tool(s) could NOT be restored:\n`
+      );
+      for (const u of unfixable) {
+        process.stdout.write(`  ${u.tool} — ${u.reason}\n`);
+      }
+      process.stdout.write(
+        "Anything that depends on these will fail. Tell David the install is broken " +
+        "before doing work that relies on them.\n"
+      );
+    }
+
+    // If one tool keeps going missing across several projects, the installer is
+    // the cause, not each project. Say so ONCE — repeating it every session
+    // turns a real signal into noise you stop reading.
+    if (repaired.length) {
+      try {
+        const lib = require(checker);
+        const { entries } = lib.readLog();
+        const suspects = lib.installerSuspects({}, entries).filter((s) => s.projects.length >= 3);
+        const seenPath = path.join(os.homedir(), ".claude", "gsd-t-install-suspects-seen.json");
+        let alreadyTold = [];
+        if (fs.existsSync(seenPath)) {
+          alreadyTold = JSON.parse(fs.readFileSync(seenPath, "utf8"));
+        }
+        const fresh = suspects.filter((s) => !alreadyTold.includes(s.tool));
+        if (fresh.length) {
+          process.stdout.write(
+            "[GSD-T INSTALL] These tools have gone missing across several projects, which " +
+            "points at the installer rather than any one project:\n"
+          );
+          for (const s of fresh.slice(0, 5)) {
+            process.stdout.write(`  ${s.tool} — ${s.projects.length} projects\n`);
+          }
+          process.stdout.write("This is worth fixing in GSD-T itself.\n");
+          fs.writeFileSync(seenPath, JSON.stringify([...alreadyTold, ...fresh.map((s) => s.tool)]));
+        }
+      } catch (e) {
+        // The repair above already happened and is unaffected. But this is the
+        // signal that tells you the INSTALLER is at fault rather than each
+        // project — losing it silently is how the underlying cause stays hidden.
+        process.stdout.write(
+          `[GSD-T INSTALL] Repairs were made, but the cross-project pattern could ` +
+          `not be read: ${e.message}\n`
+        );
+      }
+    }
+
+    process.exit(0);
+  };
+
+  process.stdin.on("end", finish);
+  process.stdin.on("error", finish);
+  const wd = setTimeout(finish, 20000);
+  if (wd.unref) wd.unref();
+}
+
+if (require.main === module) main();
+
+module.exports = { findChecker };