@tekyzinc/gsd-t 3.13.12 → 3.13.14

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.13.14] - 2026-04-17
+
+### Fixed — Supervisor no longer requires project-local `bin/gsd-t.js` + sweep self-protection
+
+v3.13.13 successfully swept bee-poc's stray `bin/gsd-t.js`, but exposed a second bug: `bin/gsd-t-unattended.cjs:31` still did `require("./gsd-t.js")` to pull in the `mapHeadlessExitCode` helper. With the stray removed, projects could no longer load the supervisor at all — the require chain now failed on `gsd-t.js` itself instead of `debug-ledger.js`. Three options were on the table (restore both files, resolve from global, or remove all stale copies); we picked the middle path via file extraction.
+
+**Fix 1 — extract `mapHeadlessExitCode` to its own file** (`bin/headless-exit-codes.cjs`, new):
+The exit-code contract helper (0=success, 1=verify fail, 2=context budget, 3=non-zero exit, 4=blocked, 5=unknown command) is now a standalone zero-dependency module. `bin/gsd-t-unattended.cjs:31` now does `require("./headless-exit-codes.cjs")` — no transitive dependency on the full CLI installer. `bin/gsd-t.js` still re-exports `mapHeadlessExitCode` for backward compatibility (top-of-file require + `module.exports`).
+
+**Fix 2 — `headless-exit-codes.cjs` joins `PROJECT_BIN_TOOLS`**: `copyBinToolsToProject` now copies the new helper into every registered project's `bin/` on the next `update-all`, so the supervisor can load it locally without reaching into the global package.
+
+**Fix 3 — sweep self-protection** (`copyBinToolsToProject`):
+While dogfooding v3.13.13, the sweep ran against GSD-T's own source repo (which is registered as a project for eating-our-own-dogfood purposes), recognized the source `bin/gsd-t.js` as matching the installer signature (it IS the installer), and deleted it. The source was restored via `git restore`, but the sweep now carries a guard: if `realpathSync(projectBinDir) === realpathSync(PKG_ROOT/bin)`, skip the sweep entirely. Dogfooding the installer on itself no longer cannibalizes the source.
+
+**Files**:
+- `bin/headless-exit-codes.cjs` — new file, 50 lines, extracted helper with explanatory header.
+- `bin/gsd-t-unattended.cjs` — line 31 now requires the new helper instead of `./gsd-t.js`.
+- `bin/gsd-t.js` — top-of-file re-export of `mapHeadlessExitCode` (backward compat); original declaration replaced with a comment pointing to the extracted module; `PROJECT_BIN_TOOLS` gains `headless-exit-codes.cjs`; sweep logic gains the realpath equality guard.
+- `test/bin-gsd-t-resilience.test.js` — new test: `copyBinToolsToProject refuses to sweep the source package's own bin/` (run sweep with `projectDir = PKG_ROOT`, assert `bin/gsd-t.js` still exists after).
+
+**Tests**: 1240/1240 pass (+1 new self-protection test). E2E: N/A.
+
+**Impact**: bee-poc's supervisor can now load after `gsd-t update-all` copies the new `headless-exit-codes.cjs` helper into `bin/`. No project needs a local `bin/gsd-t.js` for the supervisor to function. Running the installer against its own source repo no longer destroys the source.
+
+## [3.13.13] - 2026-04-17
+
+### Fixed — Stray sweep now matches older-version installer artifacts
+
+v3.13.12 shipped the defensive require + DEPRECATED_BIN_STRAYS sweep, but the sweep's safety check was too narrow: it only deleted strays whose bytes matched the **current** source. Projects left behind with a v3.13.11 (or earlier) `bin/gsd-t.js` would not match the current source (different body), so the sweep refused to delete them and those projects stayed crashed.
+
+**Fix**: sweep now uses a **signature** check rather than a byte-identity check. A stray is deleted when it starts with `#!/usr/bin/env node` AND contains the verbatim JSDoc header `GSD-T CLI Installer` in the first 400 characters. That combination is unique enough to rule out user-owned files (a user's own script would not contain our header) while matching every historical version of this installer — so older-version artifacts are swept correctly.
+
+**Files**:
+- `bin/gsd-t.js` — sweep loop now uses signature match instead of byte-match.
+- `test/bin-gsd-t-resilience.test.js` — new test case covering older-version stray (shebang + header + different body) → must be deleted. Existing byte-match test kept. Existing user-owned test kept.
+
+**Tests**: 1239/1239 pass (+1 new assertion vs v3.13.12). E2E: N/A.
+
+**Impact**: bee-poc and any other project carrying a pre-v3.13.12 `bin/gsd-t.js` now self-heals on the next `gsd-t update-all` pass after installing v3.13.13.
+
 ## [3.13.12] - 2026-04-17
 
 ### Fixed — Project-local `bin/gsd-t.js` crash on missing `debug-ledger.js` + self-heal sweep

package/bin/gsd-t-unattended.cjs

@@ -28,7 +28,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { execSync, spawnSync } = require("child_process");
-const { mapHeadlessExitCode } = require("./gsd-t.js");
+const { mapHeadlessExitCode } = require("./headless-exit-codes.cjs");
 
 // Safety rails (m36-safety-rails) — pure-function checks for pre-launch,
 // supervisor-init, pre-worker, and post-worker hook points per contract §12.

package/bin/gsd-t.js

@@ -34,6 +34,12 @@ try {
   };
 }
 
+// Shared headless exit-code helper — lives in its own file so non-entry
+// modules (e.g. bin/gsd-t-unattended.cjs) can require it without pulling
+// in the full CLI. See commentary near the original declaration site and
+// in headless-exit-codes.cjs itself.
+const { mapHeadlessExitCode } = require(path.join(__dirname, "headless-exit-codes.cjs"));
+
 // ─── Configuration ───────────────────────────────────────────────────────────
 
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
@@ -2110,6 +2116,7 @@ const PROJECT_BIN_TOOLS = [
   "context-meter-config.cjs", "token-budget.cjs",
   "gsd-t-unattended.cjs", "gsd-t-unattended-platform.cjs", "gsd-t-unattended-safety.cjs",
   "handoff-lock.cjs", "headless-auto-spawn.cjs",
+  "headless-exit-codes.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but
@@ -2154,21 +2161,41 @@ function copyBinToolsToProject(projectDir, projectName) {
       }
     }
   }
+  // Self-protection: NEVER sweep the package's own bin/. Without this guard,
+  // running `gsd-t update-all` with the GSD-T source repo itself registered
+  // as a project (legitimate during development) would signature-match
+  // bin/gsd-t.js — which IS the installer — and delete the source file.
+  // Resolve both paths to handle symlinks / relative path quirks.
+  const resolvedProjectBin = fs.realpathSync.native
+    ? (() => { try { return fs.realpathSync(projectBinDir); } catch { return projectBinDir; } })()
+    : projectBinDir;
+  const resolvedPkgBin = (() => {
+    try { return fs.realpathSync(path.join(PKG_ROOT, "bin")); } catch { return path.join(PKG_ROOT, "bin"); }
+  })();
+  const isSourcePackage = resolvedProjectBin === resolvedPkgBin;
   let cleaned = 0;
-  for (const stray of DEPRECATED_BIN_STRAYS) {
-    const strayPath = path.join(projectBinDir, stray);
-    const srcPath = path.join(PKG_ROOT, "bin", stray);
-    if (!fs.existsSync(strayPath)) continue;
-    if (!fs.existsSync(srcPath)) continue;
-    try {
-      const strayContent = fs.readFileSync(strayPath, "utf8");
-      const srcContent = fs.readFileSync(srcPath, "utf8");
-      if (strayContent === srcContent) {
-        fs.unlinkSync(strayPath);
-        cleaned++;
+  if (!isSourcePackage) {
+    for (const stray of DEPRECATED_BIN_STRAYS) {
+      const strayPath = path.join(projectBinDir, stray);
+      if (!fs.existsSync(strayPath)) continue;
+      try {
+        const strayContent = fs.readFileSync(strayPath, "utf8");
+        const head = strayContent.slice(0, 400);
+        // Signature-match any version this installer ever shipped. The marker
+        // is unique enough to rule out user-owned files: node shebang + the
+        // verbatim JSDoc header "GSD-T CLI Installer". Matches every historical
+        // version of bin/gsd-t.js, not just the current one, so older strays
+        // (e.g. v3.13.11 left behind on v3.13.12+) are still swept.
+        const isOurs =
+          head.startsWith("#!/usr/bin/env node") &&
+          head.includes("GSD-T CLI Installer");
+        if (isOurs) {
+          fs.unlinkSync(strayPath);
+          cleaned++;
+        }
+      } catch {
+        // leave the file alone on any read error
       }
-    } catch {
-      // leave the file alone on any read error
     }
   }
   if (cleaned > 0) {
@@ -2846,22 +2873,10 @@ function buildHeadlessCmd(command, cmdArgs) {
  * Exit codes: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error,
  *             4=blocked-needs-human, 5=command-dispatch-failed
  */
-function mapHeadlessExitCode(processExitCode, output) {
-  if (processExitCode !== 0 && processExitCode !== null) return 3;
-  const raw = output || "";
-  const lower = raw.toLowerCase();
-  // Command dispatch failure — `claude -p` prints "Unknown command: /X"
-  // to stdout and still exits 0. Without this sentinel, a mistyped or
-  // namespace-prefixed slash command silently reports success. (M36 Phase 0.)
-  if (/^unknown command:/im.test(raw)) return 5;
-  if (lower.includes("context budget exceeded") || lower.includes("context window exceeded") ||
-      lower.includes("budget exceeded") || lower.includes("token limit")) return 2;
-  if (lower.includes("blocked") && (lower.includes("needs human") || lower.includes("need human") ||
-      lower.includes("human input") || lower.includes("human approval"))) return 4;
-  if (lower.includes("verification failed") || lower.includes("verify failed") ||
-      lower.includes("quality gate failed") || lower.includes("tests failed")) return 1;
-  return 0;
-}
+// mapHeadlessExitCode now lives in ./headless-exit-codes.cjs — see re-export
+// near the top of this file. Kept out-of-line here so non-entry modules
+// (e.g. bin/gsd-t-unattended.cjs) can require the shared helper without
+// pulling in the full CLI at bin/gsd-t.js.
 
 /**
  * Generate a headless log file path.

package/bin/headless-exit-codes.cjs

@@ -0,0 +1,49 @@
+/**
+ * Shared helper: map a `claude -p` process exit code + output to the
+ * GSD-T headless exit-code contract.
+ *
+ * Lives in its own file so non-entry modules (e.g. gsd-t-unattended.cjs)
+ * can require it without pulling in the full CLI at bin/gsd-t.js. That
+ * decoupling lets PROJECT_BIN_TOOLS ship the supervisor without also
+ * vendoring the CLI itself — projects resolve `gsd-t` from the global
+ * install, not from a project-local copy.
+ *
+ * Exit codes (contract):
+ *   0 — success
+ *   1 — verification/test failure
+ *   2 — context budget exceeded
+ *   3 — non-zero process exit (other)
+ *   4 — blocked / needs human
+ *   5 — unknown slash command (claude -p exited 0 but rejected the prompt)
+ */
+
+"use strict";
+
+function mapHeadlessExitCode(processExitCode, output) {
+  if (processExitCode !== 0 && processExitCode !== null) return 3;
+  const raw = output || "";
+  const lower = raw.toLowerCase();
+  if (/^unknown command:/im.test(raw)) return 5;
+  if (
+    lower.includes("context budget exceeded") ||
+    lower.includes("context window exceeded") ||
+    lower.includes("budget exceeded") ||
+    lower.includes("token limit")
+  ) return 2;
+  if (
+    lower.includes("blocked") &&
+    (lower.includes("needs human") ||
+      lower.includes("need human") ||
+      lower.includes("human input") ||
+      lower.includes("human approval"))
+  ) return 4;
+  if (
+    lower.includes("verification failed") ||
+    lower.includes("verify failed") ||
+    lower.includes("quality gate failed") ||
+    lower.includes("tests failed")
+  ) return 1;
+  return 0;
+}
+
+module.exports = { mapHeadlessExitCode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.13.12",
+  "version": "3.13.14",
   "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",