@tekyzinc/gsd-t 5.6.11 → 5.7.10

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.7.10] - 2026-08-03
+
+### Added — one session per working tree, enforced (M105)
+
+Several sessions ran against one project, each told to use its own git worktree. Three did. One worked directly in the main project folder, and its uncommitted work interleaved with another session's on the same branch — neither side able to commit or merge without dragging in or losing the other's half-finished milestone. The instruction was given; nothing enforced it.
+
+- `scripts/gsd-t-worktree-guard.js`: a PreToolUse hook on Write/Edit. Blocks an edit in the MAIN working tree when another GSD-T session is live there, and prints the exact `git worktree add` command — including the stash-and-carry form when the session already has uncommitted work. Silent when alone in main (working there solo is fine), silent inside a worktree, silent outside a git repo, and fail-open on any internal error: it detects a collision, it does not gate correctness.
+- Liveness reuses the per-session `.gsd-t/heartbeat-<id>.jsonl` file that the SessionStart/Stop/SessionEnd hooks already write INTO the tree the session works in. Its location is the claim; its modification time is the signal. No new bookkeeping.
+- **The liveness window is the load-bearing detail.** A first pass using two hours read three long-closed sessions as live and would have fired on a user working alone — the false positive that teaches someone to disable a guard. The window is five minutes: a working session writes constantly.
+- `bin/gsd-t.js`: the architect-hook registrar is generalized to take a marker + command, so registering a second Write|Edit hook needed no duplicated code. Registered on install, stripped on uninstall.
+- `test/m105-worktree-guard.test.js`: 13 tests. The fail-open case caught a real hole — unparseable hook input fell back to `process.cwd()`, so the guard judged whichever directory it happened to launch from rather than the one under edit. Unreadable input now means no decision.
+
+Opt out per project with `.gsd-t/worktree-guard-config.json` `{"enabled": false}`. An invalid config leaves the guard ON. Suite 3120/0/13-skip.
+
 ## [5.6.11] - 2026-08-02
 
 ### Fixed — four bugs that reported a healthy code graph as broken (M104)

package/README.md

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

@@ -494,6 +494,17 @@ 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\'';
 
+// M105 — worktree-collision PreToolUse hook on Write|Edit. Same global-package
+// pattern. Blocks an edit when ANOTHER GSD-T session is live in the SAME working
+// tree (detected from the per-session heartbeat files already written into
+// .gsd-t/), and tells the user the exact `git worktree add` command to run.
+// Silent when working alone, silent inside a worktree, silent outside a repo,
+// and fail-open on any internal error — it detects a collision, it does not gate
+// correctness.
+const WORKTREE_HOOK_MARKER = "gsd-t-worktree-guard";
+const WORKTREE_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-worktree-guard.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-worktree-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) {
@@ -942,6 +953,17 @@ function configureReadInterceptHook(settingsPath) {
 // 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) {
+  return configureWriteEditHook(settingsPath, ARCHITECT_HOOK_MARKER, ARCHITECT_HOOK_COMMAND, "architect");
+}
+
+// M105 — register the worktree-collision guard. Reuses the same registrar rather
+// than copying it (the function below was architect-specific; generalized to take
+// the marker + command, so a third Write|Edit hook needs no new code).
+function configureWorktreeGuardHook(settingsPath) {
+  return configureWriteEditHook(settingsPath, WORKTREE_HOOK_MARKER, WORKTREE_HOOK_COMMAND, "worktree guard");
+}
+
+function configureWriteEditHook(settingsPath, marker, command, label) {
   const targetPath = settingsPath || SETTINGS_JSON;
   let settings = {};
   if (fs.existsSync(targetPath)) {
@@ -949,21 +971,21 @@ function configureArchitectHook(settingsPath) {
       settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
       if (!settings || typeof settings !== "object") settings = {};
     } catch {
-      warn("settings.json has invalid JSON — cannot configure architect hook");
+      warn(`settings.json has invalid JSON — cannot configure ${label} 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;
+  const cmd = 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)) {
+      if (h.command === cmd || h.command.includes(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; }
@@ -1007,7 +1029,7 @@ function removeInterceptHooks(settingsPath) {
   if (!settings.hooks) return false;
 
   const postMarkers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
-  const preMarkers = [ARCHITECT_HOOK_MARKER];
+  const preMarkers = [ARCHITECT_HOOK_MARKER, WORKTREE_HOOK_MARKER];
   let removed = 0;
 
   const stripByMarkers = (arr, markers) => {
@@ -2006,6 +2028,13 @@ async function doInstall(opts = {}) {
     else info("Architect-oversight hook already configured");
   }
 
+  const wtHook = configureWorktreeGuardHook(SETTINGS_JSON);
+  if (wtHook.installed) {
+    if (wtHook.action === "added") success("Worktree-collision guard added (blocks a second session editing the same tree — M105)");
+    else if (wtHook.action === "updated") success("Worktree-collision guard refreshed");
+    else info("Worktree-collision guard already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.6.11",
+  "version": "5.7.10",
   "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-worktree-guard.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * gsd-t-worktree-guard.js — PreToolUse(Write|Edit)
+ *
+ * Stops two sessions from editing the SAME working tree at the same time.
+ *
+ * The problem it solves: a session opened in the main project folder edits files
+ * there; a second session opens in the same folder and does the same. Their
+ * uncommitted work interleaves in one tree, on one branch, and neither can commit
+ * or merge without dragging in the other's half-finished milestone. Telling each
+ * session "use a worktree" does not prevent it — nothing enforces the instruction.
+ *
+ * How it detects a live session, and why: every GSD-T session writes
+ * `.gsd-t/heartbeat-<session-id>.jsonl` INSIDE the tree it is working in, via the
+ * SessionStart/Stop/SessionEnd hooks. The file's location IS the claim (a session
+ * in a worktree writes into that worktree's own .gsd-t/), and its modification
+ * time is the liveness signal. No new bookkeeping — the file already exists.
+ *
+ * Liveness is a SHORT window (default 5 min). A working session writes constantly;
+ * one silent for longer is idle or closed. This matters more than it looks: a
+ * 2-hour window reads three closed sessions as live and fires on a user working
+ * alone, which trains them to disable the guard.
+ *
+ * Behaviour:
+ *   - alone in any tree               → silent, no guard (working in main alone is allowed)
+ *   - main tree, another session live → BLOCK with the exact worktree command to run
+ *   - inside a worktree               → silent (already isolated)
+ *
+ * Fail-open by design: a guard that cannot read its inputs must not block edits.
+ * It is a collision detector, not a correctness gate — a crash here would stop
+ * legitimate work for no safety benefit.
+ *
+ * Opt out per project: .gsd-t/worktree-guard-config.json {"enabled": false}
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const LIVE_WINDOW_MS = 5 * 60 * 1000;
+
+// Returns null when the hook payload cannot be read or parsed.
+//
+// This must NOT fall back to an empty object: `cwd` would then default to
+// process.cwd() and the guard would judge whatever directory it happened to be
+// launched from — deciding about the wrong repository entirely. Caught by the
+// fail-open test, which saw a deny emitted for garbage input.
+// Unreadable input means NO DECISION, never a decision about the wrong tree.
+function readHookInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (!raw || !raw.trim()) return null;
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function git(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// The MAIN working tree is the one whose .git is a directory. A linked worktree's
+// .git is a FILE containing a gitdir: pointer — that is the distinction git itself
+// uses, so it needs no parsing of `git worktree list` output.
+function isMainWorktree(root) {
+  try {
+    return fs.statSync(path.join(root, ".git")).isDirectory();
+  } catch (_) {
+    return false;
+  }
+}
+
+function guardEnabled(root) {
+  try {
+    const cfg = JSON.parse(
+      fs.readFileSync(path.join(root, ".gsd-t", "worktree-guard-config.json"), "utf8")
+    );
+    return cfg.enabled !== false;
+  } catch (_) {
+    return true; // absent/invalid config → guard on
+  }
+}
+
+// Sessions whose heartbeat is fresh, excluding this one.
+function liveSessions(root, selfSid, now) {
+  const dir = path.join(root, ".gsd-t");
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const live = [];
+  for (const f of names) {
+    if (!f.startsWith("heartbeat-") || !f.endsWith(".jsonl")) continue;
+    const sid = f.slice("heartbeat-".length, -".jsonl".length);
+    if (selfSid && sid === selfSid) continue;
+    try {
+      const age = now - fs.statSync(path.join(dir, f)).mtimeMs;
+      if (age < LIVE_WINDOW_MS) live.push({ sid, ageMs: age });
+    } catch (_) { /* unreadable → not evidence of a live session */ }
+  }
+  return live.sort((a, b) => a.ageMs - b.ageMs);
+}
+
+function suggestWorktreeName(branch) {
+  const base = (branch || "work").replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+  return base || "work";
+}
+
+function main() {
+  const hook = readHookInput();
+  if (!hook) return; // no readable payload → no decision (see readHookInput)
+  const cwd = hook.cwd;
+  if (!cwd || typeof cwd !== "string") return; // no stated directory → nothing to judge
+
+  const root = git(["rev-parse", "--show-toplevel"], cwd);
+  if (!root) return; // not a git repo → nothing to guard
+
+  if (!isMainWorktree(root)) return; // already isolated in a worktree
+  if (!guardEnabled(root)) return;
+
+  const selfSid = hook.session_id || hook.sessionId || null;
+  const others = liveSessions(root, selfSid, Date.now());
+  if (others.length === 0) return; // alone → working in main is allowed
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], root) || "HEAD";
+  const project = path.basename(root);
+  const name = suggestWorktreeName(branch);
+  const wt = `${process.env.HOME}/Worktrees/${project}/${name}`;
+  const mins = Math.max(1, Math.round(others[0].ageMs / 60000));
+  const plural = others.length === 1 ? "session" : "sessions";
+
+  const reason = [
+    `Another GSD-T ${plural} (${others.length}) is working in this same folder right now — the most recent wrote ${mins} minute(s) ago.`,
+    ``,
+    `Editing here means two sessions share one working tree and one branch. Their uncommitted changes interleave, and neither can commit or merge without dragging in the other's half-finished work.`,
+    ``,
+    `Move to your own worktree first:`,
+    ``,
+    `  mkdir -p ${process.env.HOME}/Worktrees/${project}`,
+    `  git worktree add ${wt} -b ${name}-$(date +%H%M)`,
+    `  cd ${wt}`,
+    ``,
+    `If you already have uncommitted work in this folder, carry it across:`,
+    ``,
+    `  git stash push -u -m "moving to a worktree"`,
+    `  git worktree add ${wt} -b ${name}-$(date +%H%M)`,
+    `  cd ${wt} && git stash pop`,
+    ``,
+    `Working alone in the main folder is fine — this only fires when a second session is live.`,
+    `To turn it off for this project: .gsd-t/worktree-guard-config.json {"enabled": false}`,
+  ].join("\n");
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }) + "\n"
+  );
+}
+
+try {
+  main();
+} catch (_) {
+  // Fail open — never block an edit because the guard itself broke.
+}

package/templates/CLAUDE-global.md

@@ -150,6 +150,8 @@ WHEN creating a worktree directly (git worktree add, isolation: "worktree", etc.
 - Clean up with `git worktree remove` when the branch/task is done — don't leave prunable stragglers.
 - **Exception**: harness-managed worktrees the Agent/Workflow runtime creates under the project's gitignored `.claude/worktrees/` path are the harness's own convention — leave those alone. This rule governs worktrees *you* create directly via Bash or the `isolation: "worktree"` option.
 
+**One session per working tree (M105 — enforced).** Two sessions editing the same folder interleave their uncommitted work on one branch: neither can commit or merge without dragging in or losing the other's half-finished milestone. A PreToolUse guard (`scripts/gsd-t-worktree-guard.js`) BLOCKS a Write/Edit in the main tree when another GSD-T session is live there, and prints the exact `git worktree add` command (including the stash-and-carry form when you already have uncommitted work). Liveness comes from the per-session `.gsd-t/heartbeat-<id>.jsonl` file — location is the claim, mtime is liveness, 5-minute window. It is SILENT when you are alone in the main tree (working there solo is fine), silent inside a worktree, and fails open. Opt out per project: `.gsd-t/worktree-guard-config.json` `{"enabled": false}`.
+
 # Destructive Action Guard (MANDATORY)
 
 **NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels, including Level 3.