@tekyzinc/gsd-t 5.11.31 → 5.12.10

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 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
+
+A TimeTracking scan finished, reported success, and had done its whole deep
+analysis with grep. The graph was healthy, current, and the run even logged
+`graphWiringMode: WIRED` — but of 666 ledger events, every single one carried
+`consumer: "cli"`. Not one came from an analyst agent. The reports say it
+plainly in their own words: *"a repo-wide grep shows no caller anywhere."*
+Nothing failed, because nothing was watching for this.
+
+Three defects, one theme — **a check that cannot fail is not a check**:
+
+- **An absent graph left consumers blind instead of building it.** Every
+  FAIL-LOUD clause said: don't fall back to grep, then *proceed without the
+  structural slice*. That is a third bad outcome sitting between the two the
+  doctrine names — the agent answers "what calls this?" with no structural
+  knowledge at all. The clauses in `/quick`, `/debug`, `/design-build` and
+  `/test-sync` now BUILD the index and re-run the query; only a failed build
+  halts. This was already the contract's own rule (§FAIL-LOUD line 64,
+  "REPAIR IT, do not merely halt") — the command docs had been contradicting
+  it. `[RULE] graph-absent-builds-not-degrades`
+- **`/integrate` had a licensed exemption.** It printed `⚠ graph ABSENT —
+  structural wiring-check skipped (announced carve-out)`. A fresh worktree
+  carries no graph (it is gitignored), so the check did nothing on exactly the
+  runs it was written for. Announcing a skip does not stop it being a skip. It
+  now builds. The verify/integrate exception covers the HARD-FAIL only; it
+  never covered the build.
+- **The anti-grep lint aimed at the wrong target.** Being static, its only
+  failure mode is a code shape (`try graph → catch → grep`). A consumer that
+  never calls the graph has no catch block, so the lint reports clean while the
+  entire run uses text search.
+
+### Added — `gsd-t graph-use-gate` (runtime, `[RULE] wired-claim-requires-query-evidence`)
+
+`bin/gsd-t-graph-use-gate.cjs` reads the append-only ledger and fails any
+consumer that logged `WIRED` with zero `kind:"query"` events. It detects the
+**absence of use**, not the presence of a fallback — the thing a static lint
+structurally cannot see. `kind:"read"` (the Read-intercept hook) is never
+accepted as evidence, or it would mask the very failure being detected.
+
+Run against the two projects that prompted this, it flags both — confirming the
+defect is systemic, not a one-off. Wired into `gsd-t-verify-gate.cjs` as the
+FAIL-CLOSED `graph-use` check, propagated via `PROJECT_BIN_TOOLS` (it reads each
+project's own ledger), and covered by `test/m113-graph-use-gate.test.js` — whose
+leading test is the negative one, because a gate nobody has watched fail is a
+gate nobody knows works. Exit `0` clean · `4` violations · `64` bad input; a
+missing ledger is a *documented* no-op PASS under `--verify-mode`, tagged
+`noOpPass:true` so it stays distinguishable from wired-and-clean.
+
+**Still open:** none of this covers ordinary conversational code-reading, which
+is where the original complaint arose — an agent asked "what calls this?" in a
+worktree with no graph and grepped, with nothing objecting. That needs a
+PreToolUse hook on structural Grep/Read, and is deliberately left for its own
+milestone rather than bolted on here.
+
 ## [5.11.31] - 2026-08-11
 
 ### Added — the scanner now ranks its own findings before it numbers them

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.11.31** - 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-graph-use-gate.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-graph-use-gate.cjs
+ *
+ * Graph USE gate — proves a consumer that declared itself WIRED actually
+ * QUERIED the graph.
+ *
+ * [RULE] wired-claim-requires-query-evidence
+ * [RULE] use-gate-detects-absence-of-use-not-presence-of-fallback
+ *
+ * WHY THIS EXISTS (the gap it closes):
+ *   `gsd-t-graph-anti-grep-lint.cjs` is STATIC. It reads source files and looks
+ *   for a `try graph-query -> catch -> structural grep` fallback. That shape is
+ *   the only way it can fail.
+ *
+ *   A real scan failed a different way. Every analyst agent simply NEVER CALLED
+ *   the graph — so there was no catch block, no fallback branch, nothing for a
+ *   static scan to find. The lint passed, the run logged
+ *   `{"kind":"wiring","graphWiringMode":"WIRED"}`, and the whole scan ran on
+ *   text search anyway. A check whose only failure mode is a code shape cannot
+ *   see a consumer that never tried.
+ *
+ *   This gate reads the RUNTIME ledger instead. A consumer that stamped WIRED
+ *   and issued zero graph queries in that run is a violation, because "wired"
+ *   is a claim about behaviour and the ledger is the only record of behaviour.
+ *
+ * INPUT  : .gsd-t/graphDB/logs/graph-events-*.jsonl (append-only, JSONL)
+ * OUTPUT : {ok, violations:[{consumer, wiringMode, queryCount, firstWiringTs}], ...}
+ * EXIT   : 0 clean | 4 violations | 64 bad input (no ledger / unreadable)
+ *
+ * Unreadable input THROWS (LedgerUnavailable) rather than returning a value —
+ * a gate that hands back a result when it could not read its own evidence is
+ * the exact failure mode this file exists to remove.
+ *
+ * Node built-ins only (zero-dep invariant).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// A `kind:"read"` event is the Read-intercept hook, NOT a structural query — it
+// fires on ordinary file reads and would mask the exact failure this gate exists
+// to catch. Only `kind:"query"` counts as evidence that the graph was consulted.
+const EVIDENCE_KIND = 'query';
+const WIRING_KIND = 'wiring';
+
+// `cli` is the operator at a terminal, not a workflow consumer; it has no WIRED
+// claim to honour. Consumers are exempt ONLY by explicit name here.
+const NON_CONSUMER_IDS = new Set(['cli']);
+
+/** Thrown when the ledger cannot be located or read. Never swallowed internally. */
+class LedgerUnavailable extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LedgerUnavailable';
+  }
+}
+
+function ledgerDir(projectDir) {
+  return path.join(projectDir, '.gsd-t', 'graphDB', 'logs');
+}
+
+/** Resolve every graph-events-*.jsonl file, oldest first. Throws if none. */
+function ledgerFiles(projectDir) {
+  const dir = ledgerDir(projectDir);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    throw new LedgerUnavailable(`graph event ledger not readable: ${dir} (${err.code || err.message})`);
+  }
+  const files = names
+    .filter((n) => /^graph-events-\d+\.jsonl$/.test(n))
+    .sort()
+    .map((n) => path.join(dir, n));
+  if (files.length === 0) {
+    throw new LedgerUnavailable(`no graph-events-*.jsonl in ${dir}`);
+  }
+  return files;
+}
+
+/**
+ * Parse the ledger into per-consumer counters.
+ * A malformed line is SKIPPED and COUNTED — it is never treated as a query,
+ * because counting an unparseable line as evidence would let a corrupt ledger
+ * satisfy the gate.
+ */
+function readLedger(files, sinceTs) {
+  const consumers = Object.create(null); // prototype-less: consumer ids come from a file
+  let malformed = 0;
+  let total = 0;
+
+  const ensure = (id) => {
+    if (!consumers[id]) {
+      consumers[id] = { consumer: id, queryCount: 0, wiringModes: [], firstWiringTs: null };
+    }
+    return consumers[id];
+  };
+
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      throw new LedgerUnavailable(`cannot read ${file}: ${err.code || err.message}`);
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      total++;
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch (err) {
+        malformed++;
+        continue;
+      }
+      if (sinceTs && typeof ev.ts === 'string' && ev.ts < sinceTs) continue;
+
+      const id = typeof ev.consumer === 'string' && ev.consumer ? ev.consumer : 'unknown';
+      const kind = String(ev.kind || '');
+
+      if (kind === EVIDENCE_KIND) {
+        ensure(id).queryCount++;
+      } else if (kind === WIRING_KIND) {
+        const c = ensure(id);
+        c.wiringModes.push(String(ev.graphWiringMode || ''));
+        if (!c.firstWiringTs && typeof ev.ts === 'string') c.firstWiringTs = ev.ts;
+      }
+    }
+  }
+  return { consumers, malformed, total };
+}
+
+/**
+ * A consumer violates the gate when it CLAIMED wired and issued ZERO queries.
+ * Claiming `fallback-announced` or `disabled` is not a violation here — those
+ * are honest declarations, and the anti-grep lint governs whether the fallback
+ * itself is permitted.
+ */
+function evaluate(consumers) {
+  const violations = [];
+  const checked = [];
+
+  for (const id of Object.keys(consumers)) {
+    if (NON_CONSUMER_IDS.has(id)) continue;
+    const c = consumers[id];
+    if (c.wiringModes.length === 0) continue; // never declared; nothing claimed, nothing to prove
+
+    const claimedWired = c.wiringModes.some((m) => m.toLowerCase() === 'wired');
+    checked.push({ consumer: id, wiringModes: c.wiringModes, queryCount: c.queryCount });
+
+    if (claimedWired && c.queryCount === 0) {
+      violations.push({
+        consumer: id,
+        wiringMode: 'WIRED',
+        queryCount: 0,
+        firstWiringTs: c.firstWiringTs,
+        evidence:
+          `consumer "${id}" logged graphWiringMode=WIRED but issued 0 graph queries ` +
+          `(kind:"query") in this window — a WIRED claim with no query evidence means ` +
+          `the structural question was answered some other way.`,
+      });
+    }
+  }
+  return { violations, checked };
+}
+
+/** Throws LedgerUnavailable when the evidence cannot be read. */
+function runGate(opts = {}) {
+  const projectDir = opts.projectDir || process.cwd();
+
+  // Test override: callers may inject parsed consumers directly.
+  if (opts.consumers) {
+    const { violations, checked } = evaluate(opts.consumers);
+    return { ok: violations.length === 0, violations, checked, malformed: 0, ledgerFiles: [] };
+  }
+
+  const files = ledgerFiles(projectDir);
+  const { consumers, malformed } = readLedger(files, opts.since || null);
+  const { violations, checked } = evaluate(consumers);
+  return { ok: violations.length === 0, violations, checked, malformed, ledgerFiles: files };
+}
+
+// ─── CLI entry point ─────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const opts = { projectDir: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--project' || argv[i] === '--repo') opts.projectDir = argv[++i];
+    else if (argv[i] === '--since') opts.since = argv[++i];
+    else if (argv[i] === '--verify-mode') opts.verifyMode = true;
+    else if (!argv[i].startsWith('-')) opts.projectDir = argv[i];
+  }
+
+  let result;
+  try {
+    result = runGate(opts);
+  } catch (err) {
+    if (err instanceof LedgerUnavailable) {
+      // No ledger means NO CONSUMER HAS RUN YET — nothing has been claimed, so
+      // there is nothing to disprove. That is a documented no-op PASS in
+      // --verify-mode, distinguishable in the JSON (`noOpPass:true`) from a
+      // wired-but-broken run. Invoked directly it is BAD INPUT (exit 64): an
+      // operator asking about evidence that does not exist deserves to be told,
+      // not handed a clean bill.
+      if (opts.verifyMode) {
+        process.stdout.write(JSON.stringify(
+          { ok: true, noOpPass: true, reason: 'no-graph-event-ledger', violations: [], checked: [] }, null, 2) + '\n');
+        process.stderr.write('[graph-use-gate] PASS (no-op): no graph event ledger — no consumer has claimed WIRED yet.\n');
+        process.exit(0);
+      }
+      process.stderr.write(`[graph-use-gate] ERROR: ${err.message}\n`);
+      process.stdout.write(JSON.stringify({ ok: false, violations: [], error: err.message }, null, 2) + '\n');
+      process.exit(64);
+    }
+    throw err;
+  }
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+
+  if (!result.ok) {
+    process.stderr.write(
+      `[graph-use-gate] FAIL: ${result.violations.length} consumer(s) claimed WIRED with zero graph queries.\n`
+    );
+    for (const v of result.violations) {
+      process.stderr.write(`  ${v.consumer}: ${v.evidence}\n`);
+    }
+    process.exit(4);
+  }
+  process.stderr.write(
+    `[graph-use-gate] PASS: ${result.checked.length} declaring consumer(s), all WIRED claims backed by queries.\n`
+  );
+  process.exit(0);
+}
+
+module.exports = { runGate, readLedger, evaluate, ledgerFiles, LedgerUnavailable, EVIDENCE_KIND, NON_CONSUMER_IDS };

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-verify-gate.cjs

@@ -313,6 +313,8 @@ function _detectDefaultTrack2(projectDir, notes) {
 
   plan.push({ id: 'fallbacks', cmd: 'node', args: [path.join(__dirname, 'gsd-t-fallback-detect.cjs'), '--scan', '--project', projectDir, '--json'], timeoutMs: 120000 }); // M106: no unapproved continue-after-failure branch, FAIL-CLOSED (pre-existing ones excluded via .gsd-t/fallbacks-baseline.json)
 
+  plan.push({ id: 'graph-use', cmd: 'node', args: [path.join(__dirname, 'gsd-t-graph-use-gate.cjs'), '--project', projectDir, '--verify-mode'], timeoutMs: 30000 }); // M113: a consumer that logged graphWiringMode=WIRED must have issued >=1 graph query, FAIL-CLOSED (documented no-op PASS when no ledger exists yet). Catches what the STATIC anti-grep lint structurally cannot: a consumer that never queried at all.
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({

package/bin/gsd-t.js

@@ -3487,6 +3487,10 @@ const PROJECT_BIN_TOOLS = [
   // every Write/Edit is DENIED (the guard halts rather than allowing unchecked),
   // so this entry is load-bearing — [[project_global_bin_propagation_gap]].
   "gsd-t-fallback-detect.cjs",
+  // M113 — Graph USE gate. The verify gate dispatches to it by absolute path,
+  // and it reads the project's OWN .gsd-t/graphDB/logs ledger, so it must live
+  // in the project — [[project_global_bin_propagation_gap]].
+  "gsd-t-graph-use-gate.cjs",
   // M107 — Concise rewriter, invoked by the Stop hook.
   // M108 — Install self-check. Every project carries its own copy so it can
   // verify and repair itself even when the global install is what broke.
@@ -5654,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/commands/gsd-t-debug.md

@@ -98,7 +98,7 @@ Debug applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
 
 **WRITER half (re-index after fix):** After the fix lands, the workflow triggers a re-index of the edited files so downstream graph queries see fresh edges (`graph-freshness-contract.md` D4 surface — `freshness_check_on_query` over the touched set). `[RULE] debug-reader-and-writer-both`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the debug workflow surfaces `"graph unavailable — fix it (gsd-t graph status)"` and halts the graph-query step. It does NOT fall back to grep for the structural question. The existing debug-loop logic (2-cycle cap, loop-ledger halt) is NOT disrupted — the graph query is additive, injected before the fix agent receives context.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the debug workflow **builds the index right then** (`gsd-t graph index`) and re-runs the localization query. It does NOT fall back to grep for the structural question, and it does NOT skip the query. Only a **failed build** halts the graph-query step, with the build's own stderr surfaced. The existing debug-loop logic (2-cycle cap, loop-ledger halt) is NOT disrupted — the graph query is additive, injected before the fix agent receives context. `[RULE] graph-absent-builds-not-degrades`.
 
 ## Contract-Boundary Debugging
 

package/commands/gsd-t-design-build.md

@@ -10,7 +10,7 @@ Design-build applies the **WRITER pattern** from `graph-consumer-wiring-contract
 
 **WRITER half:** After each tier (elements → widgets → pages) generates files, the pipeline triggers a re-index of the generated files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so the next tier's `who-imports` / `cluster` query sees the new edges from the generated components. `[RULE] design-build-writer-pattern`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the structural query surfaces `"graph unavailable — fix it (gsd-t graph status)"` — the pipeline does NOT fall back to grep for the structural question. `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the pipeline **builds the index right then** (`gsd-t graph index`) and re-runs the structural query. It does NOT fall back to grep, and it does NOT proceed without the structural answer. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1: Launch the Orchestrator
 

package/commands/gsd-t-quick.md

@@ -182,7 +182,7 @@ Quick applies the **WRITER pattern** from `graph-consumer-wiring-contract.md`:
 
 **WRITER half:** After edits land, the workflow triggers a re-index of the touched files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so downstream graph queries see fresh edges. `[RULE] quick-writer-pattern`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the structural-impact query surfaces `"graph unavailable — fix it (gsd-t graph status)"` and the agent proceeds without the structural slice — it does NOT fall back to grep for the structural question. `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the workflow **builds the index right then** (`gsd-t graph index`) and re-runs the query. It does NOT fall back to grep, and it does NOT proceed without the structural slice — proceeding blind is a third failure mode, not a safe default. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1.5: Graph-Enhanced Scope Check
 

package/commands/gsd-t-test-sync.md

@@ -40,7 +40,7 @@ Test-sync applies the **WRITER pattern** from `graph-consumer-wiring-contract.md
 
 **WRITER half:** After writing or updating tests, trigger a re-index of the edited test files (`freshness_check_on_query` from `graph-freshness-contract.md` D4 surface) so the next `test-impl` query sees the updated call-site edges from the new test code. `[RULE] test-sync-uses-test-impl-verb`.
 
-**FAIL-LOUD on graph-unavailable:** On `{ok:false, reason:"graph-unavailable"}`, the test-impl query surfaces `"graph unavailable — fix it (gsd-t graph status)"` and the agent proceeds with filesystem discovery as announced fallback — it does NOT silently treat a missing graph as "no coverage". `[RULE] consumer-structural-grep-removed`.
+**BUILD-THEN-QUERY on graph-absent:** On `{ok:false, reason:"graph-unavailable"}` the workflow **builds the index right then** (`gsd-t graph index`) and re-runs the `test-impl` / `untested-impl` queries. Filesystem discovery is NOT an acceptable substitute — announcing a fallback does not stop it being one, and "which test exercises which impl" answered by filename convention is exactly the wrong-answer class the graph exists to remove. Only a **failed build** halts, with the build's own stderr surfaced. `[RULE] consumer-structural-grep-removed`, `[RULE] graph-absent-builds-not-degrades`.
 
 ## Step 1.5: Graph-Enhanced Test Discovery
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.11.31",
-  "description": "GSD-T: Contract-Driven Development for Claude Code \u2014 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",
+  "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",
   "repository": {

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)

package/templates/workflows/gsd-t-integrate.workflow.js

@@ -79,6 +79,15 @@ async function classifyGraphFailure(projectDir, reason, detail, phaseName) {
   if (env && (env.state === "ABSENT" || env.state === "BROKEN")) return env.state;
   return "BROKEN";
 }
+// [RULE] absent-graph-auto-builds-once — build the index once via the existing
+// `gsd-t graph index` path (local bin: gsd-t-graph-index.cjs build --repo <dir>).
+async function buildGraphIndex(projectDir, phaseName) {
+  const r = await runCli(
+    projectDir, "graph index", ["build", "--repo", projectDir],
+    "gsd-t-graph-index.cjs", "graph-index", false, phaseName
+  ).catch(() => null);
+  return !!(r && r.ok);
+}
 async function runVerifyGate(projectDir, label = "verify-gate", phaseName) { return runCli(projectDir, "verify-gate", ["--json"], "gsd-t-verify-gate.cjs", label, true, phaseName); }
 async function generateBrief(projectDir, { kind = "execute", milestone, domain, id, label = "brief", phaseName } = {}) {
   const argv = ["--kind", kind, "--spawn-id", id, "--out", `${projectDir}/.gsd-t/briefs/${id}.json`];
@@ -133,32 +142,54 @@ await persistWiringMode("Preflight");
 
 // M94-D10-T6: Graph Structural Slice — who-imports + blast-radius (ADDITIVE, announced-degradation)
 // [RULE] integrate-uses-graph-for-wiring-verification
-// [RULE] verify-integrate-graph-additive-announced-not-hard-fail — bootstrap carve-out:
-//   integrate degrades ANNOUNCED on graph-unavailable, does NOT hard-fail.
+// [RULE] verify-integrate-graph-additive-announced-not-hard-fail — integrate does NOT
+//   hard-fail on a graph it cannot use. It DOES build an ABSENT index first
+//   ([RULE] graph-absent-builds-not-degrades); only a BROKEN graph, or a build that
+//   itself fails, degrades announced.
 let _graphWhoImportsSlice = null;
 let _graphBlastRadiusSlice = null;
 let _graphIntegrateWarning = null;
 
 {
-  const wiResult = await runCli(
+  // [RULE] graph-absent-builds-not-degrades — an ABSENT graph is BUILT here, not
+  // skipped. The former "announced carve-out" skipped the structural wiring-check
+  // whenever the index had never been built — which is exactly when integrate most
+  // needs it, because a fresh worktree carries no graph (it is gitignored). The
+  // check therefore did nothing on the very runs it was written for. Announcing a
+  // skip does not stop it being a skip.
+  let wiEnv = (await runCli(
     projectDir, "graph who-imports", [], "gsd-t-graph-query-cli.cjs",
     "graph:who-imports", true, "Integrate"
-  );
-  const wiEnv = wiResult.envelope || {};
-  if (wiEnv.ok === true) {
-    _graphWhoImportsSlice = wiEnv;
-    log(`M94 graph who-imports: ${(wiEnv.results || []).length} result(s) (tier: ${wiEnv.tier || "?"})`);
-  } else if (wiEnv.ok === false) {
-    // [RULE] one-availability-classifier — distinguish ABSENT (announced skip) from BROKEN (LOUD).
+  )).envelope || {};
+
+  if (wiEnv.ok === false) {
+    // [RULE] one-availability-classifier — ONE classify call, ONE state, no re-derivation.
     const _state = await classifyGraphFailure(projectDir, wiEnv.reason, wiEnv.detail, "Integrate");
-    if (_state === "BROKEN") {
-      _graphIntegrateWarning = `⚠ graph BROKEN (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. This is NOT merely un-indexed; FIX it (gsd-t graph status).`;
+    if (_state === "ABSENT") {
+      log("M94 graph who-imports: index ABSENT (never indexed) — building it now (gsd-t graph index)...");
+      if (await buildGraphIndex(projectDir, "Integrate")) {
+        wiEnv = (await runCli(
+          projectDir, "graph who-imports", [], "gsd-t-graph-query-cli.cjs",
+          "graph:who-imports", true, "Integrate"
+        )).envelope || {};
+        if (wiEnv.ok !== true) {
+          _graphIntegrateWarning = `⚠ graph built but who-imports still failed (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. FIX it (gsd-t graph status).`;
+        }
+      } else {
+        // A failed BUILD is loud, and distinct from a merely-missing index.
+        _graphIntegrateWarning = "⚠ graph ABSENT and `gsd-t graph index` FAILED — structural wiring-check cannot run. FIX it (gsd-t graph status).";
+      }
     } else {
-      _graphIntegrateWarning = "⚠ graph ABSENT (never indexed) — structural wiring-check skipped (announced carve-out; build with gsd-t graph index)";
+      _graphIntegrateWarning = `⚠ graph BROKEN (reason=${wiEnv.reason || "?"}) — structural wiring-check skipped. This is NOT merely un-indexed; FIX it (gsd-t graph status).`;
     }
-    log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
-  } else {
+  } else if (wiEnv.ok !== true) {
     _graphIntegrateWarning = `⚠ graph who-imports query unexpected envelope (reason: ${wiEnv.reason || "?"}); structural wiring-check skipped`;
+  }
+
+  if (wiEnv.ok === true) {
+    _graphWhoImportsSlice = wiEnv;
+    log(`M94 graph who-imports: ${(wiEnv.results || []).length} result(s) (tier: ${wiEnv.tier || "?"})`);
+  } else {
     log(`M94 graph who-imports: ${_graphIntegrateWarning}`);
   }
 

package/templates/workflows/gsd-t-scan.workflow.js

@@ -1309,12 +1309,16 @@ const ARCHITECT_SCHEMA = {
         additionalProperties: true,
         properties: {
           key:       { type: "string", description: "short id, e.g. R1" },
-          name:      { type: "string", description: "plain-English name of the shared cause" },
-          why:       { type: "string", description: "why these are one cause, with code evidence" },
-          fix:       { type: "string", description: "the single fix that closes them" },
+          // Short by contract, not by request. The first architect run produced
+          // headings like "Doors that check who you are but never which flight
+          // school you belong to" over 250-word explanations; a reader scanning
+          // 28 roots for the one to fix next cannot skim that.
+          name:      { type: "string", maxLength: 40, description: "2-5 word noun phrase, e.g. 'Missing tenant scoping'. NOT a sentence." },
+          why:       { type: "string", maxLength: 320, description: "ONE sentence naming the shared mistake, plus the file:line citations that prove it. Keep every citation; compress the prose around them." },
+          fix:       { type: "string", maxLength: 200, description: "ONE sentence: the single change that closes them all." },
           tier:      { type: "string", enum: ["EXTREME", "CRITICAL", "HIGH", "MEDIUM", "LOW", "extreme", "critical", "high", "medium", "low"] },
           rank:      { type: "integer", description: "rank among roots of the same tier, 1 = worst" },
-          rankReason:{ type: "string" },
+          rankReason:{ type: "string", maxLength: 220, description: "ONE sentence: why this root outranks the ones below it in its tier." },
         },
       },
     },
@@ -1413,7 +1417,8 @@ async function architectPass(findings) {
       `FINDINGS:`,
       listing,
       ``,
-      `GROUP BY ROOT CAUSE. A root is one underlying cause where ONE fix closes several findings — e.g. many routes missing the same tenant check. For each root give a plain-English name, why they are one cause (with code evidence), the single fix, and its members by index. A root with ONE member is not a group; leave it standalone. A root's tier is the tier of its WORST member.`,
+      `GROUP BY ROOT CAUSE. A root is one underlying cause where ONE fix closes several findings — e.g. many routes missing the same tenant check. A root with ONE member is not a group; leave it standalone. A root's tier is the tier of its WORST member.`,
+      `WRITE IT SHORT. The name is a 2-5 word noun phrase ("Missing tenant scoping", "Silent write failures"), never a sentence. \`why\` and \`fix\` and \`rankReason\` are ONE sentence each. Someone scanning 28 roots to pick what to fix next cannot read a paragraph per root — but KEEP every file:line citation inside \`why\`, because those are what make the grouping checkable. Compress the prose, never the evidence.`,
       `Rank roots within their tier by worst consequence, and members within a root by consequence. RISK order, never the order the findings arrived.`,
       ``,
       `Return JSON per the schema. Every one of the ${chunk.length} findings must appear exactly once in \`placements\` — a finding you drop is a defect nobody will see again.`,
@@ -1506,6 +1511,8 @@ if (architect) {
         f._rootKey = p.rootKey;
         f._rootName = (root && root.name) || p.rootKey;
         f._rootFix = root && root.fix;
+        f._rootWhy = root && root.why;
+        f._rootRankReason = root && root.rankReason;
         f._rootRank = (root && Number.isInteger(root.rank)) ? root.rank : 99;
         f._rankInRoot = Number.isInteger(p.rankInRoot) ? p.rankInRoot : 99;
       }
@@ -1610,17 +1617,34 @@ function fmtChunks(today) {
 
   const CHUNK_MAX = 30000;
   const chunks = [head.join("\n")];
-  let buf = "", n = tdStart, lastSev = null, lastType = null;
+  let buf = "", n = tdStart, lastSev = null, lastType = null, lastRoot = null;
   const flush = () => { if (buf) { chunks.push(buf); buf = ""; } };
   // Consume the shared `orderedFindings` (severity → type → original-index) so the
   // TD numbers assigned here are IDENTICAL to those the consolidation stage references.
   for (const { f, t } of orderedFindings) {
     let piece = "";
-    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; }
+    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; lastRoot = null; }
     // Type sub-heading uses a bold marker line (NOT `###`) so it never collides with
     // the `### TD-N` item headings that downstream tools grep for. ASCII hyphens only
     // (M76: no em/en-dashes in fmtChunks literals).
-    if (t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
+    // Root grouping is the fix unit. When the architect grouped the findings, the
+    // register shows the root and its one-line cause/fix/rank above its members,
+    // because scheduling the members separately produces separate half-fixes of
+    // one defect. Bullets sit in <sub> so the eye lands on the finding titles.
+    // Without an architect result there are no roots, and the old type marker
+    // still separates the sections.
+    if (f._rootKey && f._rootKey !== lastRoot) {
+      piece += `\n### ${f._rootKey} - ${ascii(f._rootName) || f._rootKey}\n\n<sub>\n\n`;
+      if (f._rootWhy) piece += `- **Cause:** ${ascii(f._rootWhy)}\n`;
+      if (f._rootFix) piece += `- **Fix:** ${ascii(f._rootFix)}\n`;
+      if (f._rootRankReason) piece += `- **Rank:** ${ascii(f._rootRankReason)}\n`;
+      piece += `\n</sub>\n\n`;
+      lastRoot = f._rootKey; lastType = null;
+    } else if (!f._rootKey && lastRoot) {
+      piece += `\n### Standalone\n\n`;
+      lastRoot = null; lastType = null;
+    }
+    if (!f._rootKey && t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
     piece += itemMd(f, n++);
     if (buf.length + piece.length > CHUNK_MAX) flush();
     buf += piece;