@tekyzinc/gsd-t 3.13.13 → 3.13.15

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.13.15] - 2026-04-17
+
+### Fixed — Self-protection guard now uses package-name identity + narrow `bin/*.cjs` gitignore rule
+
+Two bugs in v3.13.14 surfaced when `gsd-t update-all` ran against GSD-T's own source repo from the globally-installed CLI:
+
+**Bug 1 — Self-protection guard bypassed**: The v3.13.14 guard compared `realpathSync(projectBinDir)` against `realpathSync(PKG_ROOT/bin)`. When `update-all` runs from the globally-installed CLI (`/usr/local/lib/node_modules/@tekyzinc/gsd-t`), `PKG_ROOT` points there — NOT to the local GSD-T source at `/Users/…/projects/GSD-T`. The paths never match in the typical dogfood setup, so the guard returned `false` and the sweep ate the source `bin/gsd-t.js`.
+
+**Fix**: identity is now by `package.json` name. The sweep reads `projectDir/package.json` and skips if `name === "@tekyzinc/gsd-t"`. Works regardless of whether `update-all` runs from the local source tree or the global install.
+
+**Bug 2 — Gitignore rule overly broad**: `UNATTENDED_GITIGNORE_ENTRIES` included `bin/*.cjs`, which ignored every `.cjs` under `bin/` — contradicting the adjacent comment ("legitimate `.cjs` source files under `bin/` ARE tracked"). With the broad rule active, new source `.cjs` files (e.g., `bin/headless-exit-codes.cjs`) couldn't be committed without `--force`.
+
+**Fix**: the gitignore entry narrows to exactly `bin/context-meter-state.cjs` — the single session-state artifact that was the original intent.
+
+**Files**:
+- `bin/gsd-t.js` — `isSourcePackage` now reads `package.json.name`; `UNATTENDED_GITIGNORE_ENTRIES` narrowed.
+- `test/bin-gsd-t-resilience.test.js` — self-protection test reshaped: seeds a tmp `package.json` with `name: "@tekyzinc/gsd-t"` + a signature-matching stray, asserts the stray survives the sweep.
+- `.gitignore` — deduped and restored to the narrow form.
+
+**Tests**: 1240/1240 pass (unchanged count; existing self-protection test reshaped). E2E: N/A.
+
+**Impact**: `gsd-t update-all` is now safe to run with GSD-T itself registered as a project, regardless of where the CLI is installed from. Legitimate `.cjs` source files in `bin/` are no longer blanket-ignored in downstream projects' `.gitignore`. bee-poc's supervisor, which started loading cleanly on v3.13.14, continues to load on v3.13.15 (this release is purely dogfood-protection + gitignore repair; no supervisor-behavior change).
+
+## [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

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,27 +2161,46 @@ function copyBinToolsToProject(projectDir, projectName) {
       }
     }
   }
-  let cleaned = 0;
-  for (const stray of DEPRECATED_BIN_STRAYS) {
-    const strayPath = path.join(projectBinDir, stray);
-    if (!fs.existsSync(strayPath)) continue;
+  // Self-protection: NEVER sweep GSD-T's own source repo. 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.
+  // Identity is by package.json name, NOT by path — when update-all runs from
+  // the globally-installed package, PKG_ROOT points to the global install and
+  // realpath comparison against the local source always fails.
+  const isSourcePackage = (() => {
     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++;
-      }
+      const pkgPath = path.join(projectDir, "package.json");
+      if (!fs.existsSync(pkgPath)) return false;
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      return pkg && pkg.name === "@tekyzinc/gsd-t";
     } catch {
-      // leave the file alone on any read error
+      return false;
+    }
+  })();
+  let cleaned = 0;
+  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
+      }
     }
   }
   if (cleaned > 0) {
@@ -2303,7 +2329,7 @@ function ensureUnattendedConfig(projectDir, projectName) {
 }
 
 const UNATTENDED_GITIGNORE_ENTRIES = [
-  "bin/*.cjs",
+  "bin/context-meter-state.cjs",
   ".gsd-t/.archive-migration-v1",
   ".gsd-t/.task-counter-retired-v1",
 ];
@@ -2852,22 +2878,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.13",
+  "version": "3.13.15",
   "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",