@tekyzinc/gsd-t 5.7.10 → 5.9.10

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 };

package/templates/CLAUDE-global.md

@@ -449,10 +449,12 @@ See memory pointer: `feedback_auto_research_external_gaps`.
 
 ### Architect's Oversight Doctrine (M101 — governed, enforced)
 
-**Contract:** `.gsd-t/contracts/architects-oversight-contract.md` v1.0.0 STABLE
+**Contract:** `.gsd-t/contracts/architects-oversight-contract.md` v1.1.0 STABLE
 
 **Never build before the design has passed the architect's interrogation.** GSD-T staffs verifiers (Red Team, QA, code-review, pre-mortem) — all asking "is this correct?" — but no seat asked "is this the *smartest, simplest* design given what we already have?" The result: the wrong thing built correctly, then thoroughly tested, then shipped (the Binvoice completeness-scan waste — a whole-page scan re-deriving a count already stored locally). This doctrine fills the empty architect seat. Sibling to the Unproven-Assumption Doctrine: that one bars unproven *facts*; this one bars unproven *necessity*.
 
+**§Stage 0 — GROUND BEFORE YOU ASSESS (runs first; contract §0).** A field audit of 16 real architect runs found 21 user corrections, and **13 of them were facts the user already held** — settled rules the architect re-derived and got wrong ("that rule was implemented last week"), and runtime behavior it asserted from a saved page instead of asking ("I believe you're wrong. When scrolling the feed…"). **Asking is cheaper than deriving.** So before the pass: read the code AND the standing rules (CLAUDE.md constraints, `[RULE]` guard maps, contracts, recent Decision Log); label every evidence item **LIVE or SNAPSHOT** (a runtime claim resting on a snapshot is unproven); then **interview the user** — lead by showing your read of *how it works today* as a plain-English flow for confirmation, echo back the rules you're treating as fixed, and ask only what code cannot answer. **Research** (how others solve this class of problem) runs only when you're not confident, and only AFTER the interview so it can't anchor the questions. Loop interview↔research, **max 3 cycles** (1-2 expected); still unsure at the cap → ask the user whether to halt or proceed with the uncertainty flagged. A run succeeded if the build it directed needed few follow-ups — not if the report read well.
+
 **The Six-Stage Pass — run IN ORDER before proposing or building any solution. Each stage can KILL the plan. Every "am I sure?" is answered with EVIDENCE (a grep, a Read, a graph query), never conviction — self-confidence is what produced the waste.**
 
 1. **Objective** — What is the core objective? Why is it the core objective? *(Kills: building the wrong thing.)*