@tekyzinc/gsd-t 5.10.12 → 5.11.10

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.11.10] - 2026-08-09
+
+### Fixed — four safety gates were passing without checking anything
+
+A branch warning turned into an audit. Every fault below is the same shape: a
+check that verifies nothing and reports a pass.
+
+- The branch check was dead in every scaffolded project. It matched only the
+  phrase `Expected branch:`, while the project template wrote a table row
+  labelled `Branch`. Nothing fills that row mechanically, so both sides
+  changed: the row is renamed and the reader accepts either shape.
+- The same check blocked the workflow the house rules mandate — a worktree on a
+  feature branch is correct by design, yet was flagged. In a worktree a named
+  branch now passes and says why; a detached HEAD fails, because commits made
+  with no branch attached are easily lost.
+- An unreadable `CLAUDE.md` passed as "no rules". It halts now.
+- The entire preflight gate was decorative in every installed project:
+  `cli-preflight.cjs` shipped without its six checks, found an empty directory,
+  and returned `ok:true`. Measured live: `checks run: 0`. Directories under
+  `bin/` now ship, and an empty registry fails instead of passing.
+- Install-repair overwrote in-progress edits in GSD-T's own repo, where `bin/`
+  is the source rather than a copy of the published build. It now refuses that
+  repo, identified by its package name.
+
+### Fixed — the reply shortener never ran once, then hung when it did
+
+Two faults stacked, so neither was visible. The hook read only the last record
+of a turn; a turn almost always ends with a tool call, so it found no prose and
+gave up. Underneath that, the rewrite itself hung: given a reply full of file
+paths and commands, the spawned Claude read them as work to do and went off
+running them — 45 seconds, killed on timeout, empty output and empty stderr,
+every turn. Shortening prose needs no tools, so they are now forbidden.
+Measured end to end: 41s and nothing, to 10.9s and a correct rewrite. A timeout
+now writes to stderr; silence is what let it hide.
+
+### Added — a new worktree arrives runnable
+
+`git worktree add` brings only tracked files, so `.env`, local settings and
+installed dependencies stayed behind and the folder was born unable to run.
+Provisioning carries local config (permissions preserved, so a 600 secret does
+not become world-readable), skips per-session `.gsd-t` state, and reinstalls
+dependencies from the worktree's own lockfile.
+
+- `bin/cli-preflight-checks/branch-guard.cjs`: reads both rule shapes, worktree-aware, halts on an unreadable file
+- `bin/cli-preflight.cjs`: an empty check registry fails instead of passing
+- `bin/gsd-t-worktree-detect.cjs`: shared worktree test using git's own answer
+- `bin/gsd-t-worktree-provision.cjs`: carry config, skip state, install deps
+- `bin/gsd-t-install-check.cjs`: refuses to "repair" the GSD-T source repo
+- `bin/gsd-t-concise-rewrite.cjs`: no tools, and a loud timeout
+- `scripts/gsd-t-concise-hook.js`: finds the turn's prose past its tool calls
+- `bin/gsd-t.js`: directories under `bin/` now propagate
+- `templates/CLAUDE-project.md`: the branch row the reader can actually find
+- `test/m112-worktree-provision.test.js`, `test/m107-concise-rewrite.test.js`: 24 new tests
+
+Known limitation: `contracts-stable` has never fired once (its pattern expects
+emphasis after `Status`, every real file writes it before) and `ports-free`
+reads a config key nothing writes. Both are recorded and left for a separate
+pass.
+
 ## [5.10.10] - 2026-08-07
 
 ### Added — a project's CLAUDE.md is written from what actually happened in it

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.10.12** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.11.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/cli-preflight-checks/branch-guard.cjs

@@ -3,40 +3,67 @@
 /**
  * branch-guard — verify current git branch matches CLAUDE.md "Expected branch" rule.
  *
- * Severity: error (blocks). If CLAUDE.md has no "Expected branch:" line, the check
- * passes with `msg: "no expected-branch rule set"` (info-grade pass).
+ * Severity: error (blocks). If CLAUDE.md declares no expected-branch rule, the
+ * check passes with a message that NAMES the gap ("NOT CHECKED — …") rather than
+ * one that reads like approval: a pass that compared nothing must say so.
  *
- * Pure inspection — runs `git branch --show-current` (read-only) and reads CLAUDE.md.
+ * The rule governs the MAIN checkout. Inside a linked worktree (a side copy of
+ * the repo) the house rules require a feature branch, so being off the declared
+ * branch there is correct, not a violation — the check passes and says why. The
+ * one genuinely dangerous state in a side copy is a detached HEAD, where commits
+ * belong to no branch and are easily lost; that still fails.
+ *
+ * An unreadable CLAUDE.md HALTS. Treating a permissions or corruption failure as
+ * "no rules to enforce" is a real failure wearing a pass.
+ *
+ * Pure inspection — runs read-only git commands and reads CLAUDE.md.
  */
 
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { isLinkedWorktree } = require('../gsd-t-worktree-detect.cjs');
 
 const ID = 'branch-guard';
 
+// Distinguishes "the file is not there" (ordinary) from "the file is there and
+// could not be read" (a failure). Collapsing both to null is what let a real
+// error pass as a clean run.
+const NO_FILE = Symbol('no-claude-md');
+
 function _readClaudeMd(projectDir) {
   const file = path.join(projectDir, 'CLAUDE.md');
-  if (!fs.existsSync(file)) return null;
-  try {
-    return fs.readFileSync(file, 'utf8');
-  } catch (_) {
-    return null;
-  }
+  if (!fs.existsSync(file)) return NO_FILE;
+  // Deliberately no try/catch: an unreadable rules file is a real failure and
+  // must reach the caller.
+  return fs.readFileSync(file, 'utf8');
 }
 
+/**
+ * Pull the expected branch out of CLAUDE.md, in either shape a project writes it.
+ *
+ * Nothing fills this in mechanically — /gsd-t-setup is a prose command, so a
+ * person or an assistant types the line by hand. Accepting only one shape is how
+ * the guard came to sit dead in every scaffolded project: the template wrote a
+ * table row and the reader looked for a sentence.
+ *
+ *   Sentence:  "Expected branch: main"   "**Expected branch**: `develop`"
+ *   Table row: "| Expected branch | `main` |"
+ *
+ * Returns the branch name, or an empty string when the project states no rule.
+ */
 function _extractExpectedBranch(text) {
-  if (!text) return null;
-  // Match `Expected branch:` (case-insensitive), allowing markdown emphasis like `**Expected branch**`,
-  // backticks around the value, optional surrounding whitespace.
-  // Examples that must match:
-  //   "Expected branch: main"
-  //   "Expected branch: `main`"
-  //   "**Expected branch**: `develop`"
-  //   "_Expected branch_: feature/foo"
-  const re = /\*{0,2}\s*expected\s+branch\s*\*{0,2}\s*:\s*\**\s*`?([^\s`*\n]+)`?/i;
-  const m = text.match(re);
-  return m ? m[1].trim() : null;
+  if (!text || typeof text !== 'string') return '';
+
+  const row = text.match(
+    /^\s*\|\s*\**\s*expected\s+branch\s*\**\s*\|\s*`?([^\s`|*]+)`?\s*\|/im
+  );
+  if (row) return row[1].trim();
+
+  const line = text.match(/\*{0,2}\s*expected\s+branch\s*\*{0,2}\s*:\s*\**\s*`?([^\s`*\n|]+)`?/i);
+  if (line) return line[1].trim();
+
+  return '';
 }
 
 function _currentBranch(projectDir) {
@@ -50,18 +77,36 @@ function _currentBranch(projectDir) {
 }
 
 function run({ projectDir }) {
-  const md = _readClaudeMd(projectDir);
-  if (md == null) {
+  let md;
+  try {
+    md = _readClaudeMd(projectDir);
+  } catch (err) {
+    return {
+      ok: false,
+      msg:
+        'CLAUDE.md exists but could not be read (' +
+        ((err && err.message) || err) +
+        ') — the branch rule cannot be checked; fix the file or its permissions',
+    };
+  }
+
+  if (md === NO_FILE) {
     return {
       ok: true,
-      msg: 'no CLAUDE.md found, skipping',
+      msg: 'NOT CHECKED — no CLAUDE.md in this project',
     };
   }
+
+  // A project stating no rule is a fact about the project, and the verdict below
+  // reports exactly that. Nothing was looked up and lost, and no value stands in
+  // for a missing one.
   const expected = _extractExpectedBranch(md);
-  if (!expected) {
+  const declaresARule = expected.length > 0;
+
+  if (declaresARule === false) {
     return {
       ok: true,
-      msg: 'no expected-branch rule set',
+      msg: 'NOT CHECKED — this project declares no expected branch',
     };
   }
 
@@ -71,16 +116,49 @@ function run({ projectDir }) {
   } catch (err) {
     return {
       ok: false,
-      msg: 'git branch --show-current failed: ' + (err && err.message || err),
+      msg: 'git branch --show-current failed: ' + ((err && err.message) || err),
       details: { expected },
     };
   }
 
-  if (!actual) {
+  // A side copy of the repo is MEANT to be on its own branch — the house rules
+  // require it. Only the main checkout is held to the declared branch.
+  let inWorktree;
+  try {
+    inWorktree = isLinkedWorktree(projectDir);
+  } catch (err) {
+    return {
+      ok: false,
+      msg: 'could not tell whether this is a worktree: ' + ((err && err.message) || err),
+      details: { expected, actual },
+    };
+  }
+
+  if (inWorktree === true) {
+    if (actual === '') {
+      return {
+        ok: false,
+        msg: 'not on a branch in this worktree — commits made here would be lost',
+        details: { expected, actual: '', worktree: true },
+      };
+    }
+    return {
+      ok: true,
+      msg:
+        'worktree on ' +
+        actual +
+        ' — the expected-branch rule (' +
+        expected +
+        ') governs the main checkout only',
+      details: { expected, actual, worktree: true },
+    };
+  }
+
+  if (actual === '') {
     return {
       ok: false,
       msg: 'detached HEAD or empty branch (expected ' + expected + ')',
-      details: { expected, actual: '' },
+      details: { expected, actual: '', worktree: false },
     };
   }
 
@@ -88,14 +166,14 @@ function run({ projectDir }) {
     return {
       ok: true,
       msg: 'on expected branch ' + expected,
-      details: { expected, actual },
+      details: { expected, actual, worktree: false },
     };
   }
 
   return {
     ok: false,
     msg: 'on ' + actual + ', expected ' + expected,
-    details: { expected, actual },
+    details: { expected, actual, worktree: false },
   };
 }
 
@@ -107,4 +185,5 @@ module.exports = {
   _extractExpectedBranch,
   _readClaudeMd,
   _currentBranch,
+  NO_FILE,
 };

package/bin/cli-preflight.cjs

@@ -57,6 +57,26 @@ function runPreflight(opts) {
   checkResults.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   notes.sort();
 
+  // A run that loaded no checks verified nothing, and must never report a clean
+  // pass. The global install shipped this runner without its checks directory
+  // for months: it recorded "checks dir unreadable" in a note and returned
+  // ok:true anyway, so every preflight in every installed project passed
+  // without looking at anything. A note nobody reads is not a report.
+  const nothingRan = registry.length === 0;
+  if (nothingRan) {
+    notes.push(
+      'NOT CHECKED — no preflight checks were loaded, so nothing was verified. ' +
+      'The checks directory is missing from this install; reinstall GSD-T.'
+    );
+    notes.sort();
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      ok: false,
+      checks: checkResults,
+      notes,
+    };
+  }
+
   const ok = !checkResults.some((c) => c.ok === false && c.severity === 'error');
 
   return {

package/bin/gsd-t-concise-rewrite.cjs

@@ -136,14 +136,39 @@ function checkInvariants(original, rewritten) {
   return lost;
 }
 
+// Shortening prose needs no tools. Left able to use them, the rewriter read the
+// file paths and commands INSIDE the reply as work to do and went off running
+// them — 41 seconds, killed on timeout, empty output and empty stderr, on every
+// turn for two days. Forbidding tools returns the same rewrite in about 7
+// seconds. The list is explicit rather than a mode flag so a newly added tool
+// cannot quietly re-open the same hole.
+const NO_TOOLS = [
+  "Bash", "Read", "Write", "Edit", "NotebookEdit", "Glob", "Grep",
+  "Task", "Agent", "WebFetch", "WebSearch", "TodoWrite",
+].join(",");
+
 /** Ask a fresh Claude to do the rewrite. */
 function rewrite(text, cfg) {
   const prompt = `${RULES}\n\n--- REPLY TO REWRITE ---\n${text}`;
   const run = spawnSync("claude",
-    ["-p", prompt, "--model", cfg.model, "--dangerously-skip-permissions"],
+    ["-p", prompt, "--model", cfg.model, "--dangerously-skip-permissions",
+     "--disallowed-tools", NO_TOOLS],
     { encoding: "utf8", timeout: cfg.timeoutMs, maxBuffer: 8 * 1024 * 1024 });
 
-  if (run.error) return { ok: false, error: run.error.message };
+  if (run.error) {
+    // A timeout is the failure that hid for two days: every turn paid the full
+    // wait, produced nothing, and said nothing. Write it to stderr so the cost
+    // is visible even though the reply still goes through untouched.
+    const timedOut = run.error.code === "ETIMEDOUT";
+    if (timedOut) {
+      process.stderr.write(
+        `[gsd-t] the concise rewriter timed out after ${Math.round(cfg.timeoutMs / 1000)}s ` +
+        `and produced nothing — every turn is paying that wait. Switch it off with ` +
+        `.gsd-t/concise.json {"enabled": false} until it is fixed.\n`
+      );
+    }
+    return { ok: false, error: run.error.message, timedOut };
+  }
   if (run.status !== 0) return { ok: false, error: `claude exited ${run.status}: ${(run.stderr || "").slice(0, 200)}` };
   const out = (run.stdout || "").trim();
   if (!out) return { ok: false, error: "the rewriter returned nothing" };

package/bin/gsd-t-fallback-detect.cjs

@@ -375,7 +375,11 @@ function scanStructural(clean, file, findings) {
   }
 
   // retry loop that gives up and proceeds
-  const retryRe = /\b(?:for|while)\s*\([^)]*(?:attempt|retry|retries|tries)\b[^)]*\)\s*\{/gi;
+  // `\b` before the alternation is not enough: "entries" ends in "tries", so
+  // `for (const e of entries)` matched — a plain iteration read as a retry loop.
+  // Requiring a word boundary on BOTH sides keeps the real shapes (attempt,
+  // retry, retries, tries) and drops words that merely end in one.
+  const retryRe = /\b(?:for|while)\s*\([^)]*\b(?:attempt|retry|retries|tries)\b[^)]*\)\s*\{/gi;
   while ((m = retryRe.exec(clean)) !== null) {
     const braceIdx = clean.indexOf("{", m.index);
     if (braceIdx === -1) continue;

package/bin/gsd-t-install-check.cjs

@@ -116,6 +116,28 @@ function packageVersion(pkgRoot) {
  * Returns { missing, stale, present } — stale means the file exists but its
  * content differs from the package's copy.
  */
+/**
+ * Is this directory GSD-T's own source repo (or a worktree of it)?
+ *
+ * Identified by the package name in its own package.json — the one fact that
+ * cannot drift, since it IS what npm publishes. A path check would miss a
+ * worktree under ~/Worktrees, and a marker file would need maintaining.
+ *
+ * An unreadable or absent package.json means "not the source repo": an ordinary
+ * project that happens to have no manifest still deserves its repair.
+ */
+function isOwnSourceRepo(dir) {
+  const manifest = path.join(dir, "package.json");
+  if (!fs.existsSync(manifest)) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifest, "utf8"));
+  } catch (_) {
+    return false;
+  }
+  return parsed && parsed.name === "@tekyzinc/gsd-t";
+}
+
 function inspect(projectDir, pkgRoot, tools) {
   const binDir = path.join(projectDir, "bin");
   const missing = [];
@@ -245,6 +267,24 @@ function main() {
     process.exit(EXIT_OK);
   }
 
+  // In a project, bin/ holds COPIES of the package's tools, so restoring one
+  // from the package is a repair. In GSD-T's own repo those same files are the
+  // SOURCE, and "repairing" them overwrites work in progress with the last
+  // published build. That happened: on 2026-08-09 a test run triggered a repair
+  // here and silently reverted two edited files mid-session, with the change
+  // discoverable only by reading the diff before committing.
+  if (isOwnSourceRepo(projectDir)) {
+    const msg =
+      `${projectDir} is the GSD-T source repo — bin/ here is the source, not a ` +
+      `copy of it. Repairing would overwrite your work with the published build.`;
+    if (args.json) {
+      process.stdout.write(JSON.stringify({ ok: true, exitCode: EXIT_OK, skipped: msg }, null, 2) + "\n");
+    } else {
+      process.stderr.write(`[gsd-t] ${msg}\n`);
+    }
+    process.exit(EXIT_OK);
+  }
+
   let pkgRoot;
   try {
     pkgRoot = findPackageRoot();
@@ -339,4 +379,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { inspect, expectedTools, findPackageRoot, readLog, installerSuspects, LOG_PATH };
+module.exports = { inspect, expectedTools, findPackageRoot, readLog, installerSuspects, isOwnSourceRepo, LOG_PATH };