@tekyzinc/gsd-t 5.11.32 → 5.12.10

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.12.10] - 2026-08-19
+
+### Added — naming an existing worktree walks you into it
+
+Naming a worktree that already existed used to be refused outright. That
+refused the ordinary case — your own worktree, from yesterday, with nobody in
+it — and left no way back except quitting the session and starting one by
+hand, which is the exact chore the picker exists to spare you.
+
+`--name` now ENTERS a worktree when git confirms it as this repo's, on that
+branch, with no interactive session in it. Two cases still STOP, because each
+is a way of landing on somebody's uncommitted work: a directory git does not
+know as that branch's worktree (a stray folder, or another branch's), and one
+an interactive session already occupies (the M105 collision). The occupancy
+check already existed on the reuse path and was simply never asked on the
+naming path — no new mechanism was added.
+
+A path bug surfaced while testing and is fixed: git reports symlink-resolved
+paths while ours were used as typed, so on macOS `/var` vs `/private/var` made
+one folder compare as two. Any repo under a symlinked path would have been
+wrongly refused. An unresolvable path now HALTS rather than answering "not a
+match".
+
+- `bin/gsd-t-pick-worktree.cjs`: `create()` becomes `enterOrCreate()`; new
+  `isWorktreeOf()` asks the repo's own worktree register (not the directory,
+  which a foreign checkout would answer for); new `realPath()` compares
+  symlink-resolved paths and halts when one cannot be resolved; new `--list`
+  prints `free|busy<TAB><path>` per worktree.
+- `bin/gsd-t.js`: flags pass through unchanged; comment notes `--list`.
+- `templates/CLAUDE-global.md`: states the enter-vs-stop rule.
+- `.gsd-t/pseudocode/PseudoCode-EnterExistingWorktree.md`: source-of-truth
+  behaviour map, style gate clean.
+- `test/m111-pick-worktree.test.js`: the old "refuses a directory that already
+  exists" test narrows to the two cases that still refuse; adds coverage for
+  entering a free worktree, a stray directory, a worktree on another branch,
+  and both `--list` shapes.
+
+The launcher (`cc()` in `~/.zshrc`) shows the worktree list above the name
+prompt, so an existing one is picked by sight rather than recalled.
+
 ## [5.11.32] - 2026-08-14
 
 ### Fixed — a missing graph is now BUILT, and a "wired" claim has to prove itself

package/README.md

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

@@ -12,12 +12,23 @@
  *     d=$(gsd-t-pick-worktree) && [ -n "$d" ] && cd "$d"
  *     claude
  *
- * Three modes:
+ * Four modes:
  *
  *     (no flags)        pick a worktree, creating one if none is free
  *     --suggest         say what WOULD happen, create nothing. Prints
  *                       "reuse:<path>", "create", or nothing at all.
- *     --name <name>     create a worktree on a branch called <name>
+ *     --name <name>     go to the worktree on a branch called <name>, creating
+ *                       it if it isn't there yet
+ *     --list            list this project's worktrees, one per line, as
+ *                       "<free|busy>\t<path>". Creates nothing.
+ *
+ * --name naming a worktree that already exists ENTERS it. Refusing that was the
+ * old behaviour and it refused the ordinary case — your own worktree, from
+ * yesterday, with nobody in it — leaving no way back in except quitting and
+ * starting a session by hand, which is the thing this script exists to spare
+ * you. What the refusal genuinely protected is narrower: another live session
+ * sitting in that folder, or a directory git does not know as this branch's
+ * worktree. Both still stop.
  *
  * --suggest exists so the shell can ask for a name BEFORE anything is created.
  * A branch named at session start, before the work is known, can only be a
@@ -64,6 +75,7 @@ function fail(message) {    // could not decide — say why, change nothing
 function main() {
   const argv = process.argv.slice(2);
   const suggest = argv.includes("--suggest");
+  const wantsList = argv.includes("--list");
   const nameAt = argv.indexOf("--name");
   const wanted = nameAt >= 0 ? argv[nameAt + 1] : null;
 
@@ -78,6 +90,17 @@ function main() {
 
   const home = path.join(process.env.HOME, "Worktrees", path.basename(cwd));
 
+  // Report what is there so the prompt can show it before a name is typed.
+  // Nothing here is a path for the shell to cd into, so each line is labelled;
+  // the caller reads this one deliberately rather than as a bare directory.
+  if (wantsList) {
+    const busy = interactiveClaudeDirs();
+    for (const w of worktreesNewestFirst(home)) {
+      process.stdout.write(`${busy.has(w.path) ? "busy" : "free"}\t${w.path}\n`);
+    }
+    return;
+  }
+
   if (wanted) {
     // Asking for the repo's own default branch means "work here, in the main
     // checkout" — not "make a worktree called main", which git refuses anyway
@@ -94,7 +117,7 @@ function main() {
       );
       stay();
     }
-    process.stdout.write(create(cwd, home, branchNameFrom(wanted)).path + "\n");
+    process.stdout.write(enterOrCreate(cwd, home, branchNameFrom(wanted)).path + "\n");
     return;
   }
 
@@ -202,16 +225,30 @@ function worktreesNewestFirst(home) {
 // timestamp, and a timestamp describes nothing — which is how this repo
 // collected twenty `session-2026-08-08T23-10-16` branches. Callers with no name
 // get "create" from --suggest and must come back with --name.
-function create(repo, home, branch) {
+function enterOrCreate(repo, home, branch) {
   if (!branch) {
     fail("A worktree needs a branch name — run with --name <name>.");
   }
   const dest = path.join(home, branch);
 
-  // Reusing a directory that already holds a different branch's work would put
-  // this session on top of it. Say so instead.
+  // Already there: go in, provided it is genuinely this branch's worktree and
+  // nobody is working in it. Both conditions are checked before entering, since
+  // each is a way of landing on top of somebody's uncommitted work.
   if (fs.existsSync(dest)) {
-    fail(`${dest} already exists. Pick a different name, or start there directly.`);
+    if (!isWorktreeOf(repo, dest, branch)) {
+      fail(
+        `${dest} exists but git does not know it as this repo's worktree for ` +
+        `"${branch}". Working there would sit on top of whatever is in it — ` +
+        `move it aside, or pick a different name.`
+      );
+    }
+    if (interactiveClaudeDirs().has(dest)) {
+      fail(
+        `Another session is working in ${dest} right now. Two sessions in one ` +
+        `folder interleave each other's uncommitted work — pick a different name.`
+      );
+    }
+    return { path: dest };
   }
 
   fs.mkdirSync(home, { recursive: true });
@@ -235,6 +272,60 @@ function create(repo, home, branch) {
   return { path: dest };
 }
 
+/**
+ * Does THIS repo know `dest` as its worktree for `branch`?
+ *
+ * Asked of the main repo rather than of the directory: a folder can be a
+ * perfectly valid git checkout of something else entirely, and it would answer
+ * "yes, I am a worktree on that branch" while belonging to another project.
+ * The repo's own register is the only place that settles ownership.
+ *
+ * A git that cannot answer is a stop, not a "probably fine" — the unanswered
+ * question is precisely whether somebody's work is already there.
+ */
+function isWorktreeOf(repo, dest, branch) {
+  const r = spawnSync("git", ["worktree", "list", "--porcelain"], {
+    cwd: repo, encoding: "utf8", timeout: 10000,
+  });
+  if (r.status !== 0) {
+    fail(
+      `Cannot read this repo's worktree list ` +
+      `(${String(r.stderr).trim() || "git failed"}), so it can't be confirmed ` +
+      `that ${dest} is yours to work in.`
+    );
+  }
+
+  // Entries are blank-line separated; the lines that matter are "worktree
+  // <path>" and "branch refs/heads/<name>".
+  const target = realPath(dest);
+  for (const block of String(r.stdout).split(/\n\s*\n/)) {
+    const at = block.match(/^worktree (.+)$/m);
+    if (!at) continue;
+    if (realPath(at[1].trim()) !== target) continue;
+    const on = block.match(/^branch refs\/heads\/(.+)$/m);
+    return Boolean(on) && on[1].trim() === branch;
+  }
+  return false;
+}
+
+/**
+ * The path with every symlink followed, so two spellings of one directory
+ * compare equal. git reports resolved paths; ours are as typed, and on macOS
+ * /var is a symlink to /private/var — so the same folder arrives under two
+ * names and a plain string compare calls them different places.
+ *
+ * A path that cannot be resolved stops the run. The comparison it feeds decides
+ * whether a directory is safe to work in, and an unresolvable path leaves that
+ * unanswered rather than answered "no".
+ */
+function realPath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch (e) {
+    fail(`Cannot resolve ${p} (${e.message}), so it can't be told apart from another directory.`);
+  }
+}
+
 /**
  * A worktree holds only what git tracks, so the secrets and the installed
  * dependencies stay behind and the new folder is born unable to run. Carry the

package/bin/gsd-t.js

@@ -5658,7 +5658,7 @@ if (require.main === module) {
     case "pick-worktree": {
       const picker = path.join(PKG_ROOT, "bin", "gsd-t-pick-worktree.cjs");
       try {
-        // Pass the flags through — --suggest and --name live on the picker.
+        // Pass the flags through — --suggest, --name and --list live on the picker.
         execFileSync(process.execPath, [picker, ...args.slice(1)], { stdio: "inherit" });
       } catch (e) {
         // The picker prints its own reason on stderr and exits non-zero when it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.11.32",
+  "version": "5.12.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/templates/CLAUDE-global.md

@@ -154,6 +154,9 @@ WHEN creating a worktree directly (git worktree add, isolation: "worktree", etc.
 
 **A worktree is NOT usable until it is provisioned (M112).** `git worktree add` brings only what git TRACKS, so every ignored file stays behind — `.env` and its secrets, local settings, and the installed dependencies. The new folder looks complete and is not: tests fail on a missing module and the app cannot reach its database, both reading as broken code rather than a setup gap. `bin/gsd-t-worktree-provision.cjs` runs automatically inside `gsd-t-pick-worktree` and treats the three kinds of ignored file differently — **CARRY** local config and secrets (`.env*`, `.npmrc`, credentials; permissions preserved, so a 600 secret does not become world-readable), **SKIP** per-session `.gsd-t` state, build output and OS junk (copying another session's briefs/heartbeats is how two sessions come to believe they own the same work), and **INSTALL** dependencies from the worktree's own lockfile rather than copying or symlinking (a symlink makes a lockfile change in one tree silently alter the other). Anything it cannot read or copy is REPORTED, and a failed install HALTS — a worktree that came up short says so instead of looking ready. Creating a worktree by hand skips all of this, so prefer `gsd-t-pick-worktree --name <branch>`.
 
+**Naming an existing worktree WALKS YOU INTO IT (M113).** `gsd-t pick-worktree --name <branch>` used to refuse whenever the folder was already there, which refused the ordinary case — your own worktree, from yesterday, nobody in it — and left no way back except quitting the session and starting one by hand. It now ENTERS a worktree git confirms as this repo's, on that branch, with no interactive session in it. Two cases still STOP, because each is a way of landing on somebody's uncommitted work: a directory git does not know as that branch's worktree (a stray folder, or another branch's), and a worktree an interactive session already occupies (the M105 collision). `gsd-t pick-worktree --list` prints one line per worktree as `free|busy<TAB><path>`, so the launcher can show what exists before asking for a name.
+
+
 **The expected-branch rule governs the MAIN checkout only (M112).** A worktree exists precisely to be on its own branch, so `branch-guard` passes there and names the skip; a **detached HEAD in a worktree FAILS**, because commits made with no branch attached are easily lost. The rule is read from the project CLAUDE.md in either shape — a sentence (`Expected branch: main`) or a table row (`| Expected branch | main |`) — and when no rule is declared the check says `NOT CHECKED` rather than returning a bare pass.
 
 # Destructive Action Guard (MANDATORY)