@tekyzinc/gsd-t 5.6.10 → 5.7.10

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 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)
+
+A partition and plan phase halted four separate times with `graph BROKEN` while the graph was fine — exit 0, `ok:true`, compiler-accurate. Four distinct bugs, all producing the identical message, each sitting downstream of the last, so every fix only revealed the next.
+
+- `templates/workflows/gsd-t-phase.workflow.js`:
+  - **The verb map pointed five phases at graph queries that require a target.** `plan`, `impact`, `feature`, `populate` and `promote-debt` mapped to `who-imports` / `blast-radius`, which return `{"ok":false,"reason":"missing-target"}` when called without one. A comment above the map asserted these "return the full graph slice" without a target — that was never true, and nobody checked it against the CLI. **These five phases never once completed their graph query in any project since the map shipped.** All now use `cluster`, which answers target-free.
+  - **The verb travelled in the wrong argument.** `runCli` builds the local-bin command from `argv` alone, so with the verb in the subcommand string and `argv` empty, any project carrying its own `bin/gsd-t-graph-query-cli.cjs` ran it with no verb at all → `{"ok":false,"reason":"no-verb"}`. This failed only in projects with a local copy, which is why it stayed invisible elsewhere.
+- `gsd-t-phase`, `-integrate`, `-debug`, `-execute`, `-quick`, `-verify`: the CLI-result envelope was typed as `{}` — a schema accepting anything. A helper agent that returned the raw JSON *text*, or omitted the field and left the JSON in `stdout`, validated as cleanly as a correct parse; callers then read `ok` on a string or on nothing, got `undefined`, and failed closed on a healthy command. The field is now typed `object|null`, and `_coerceCliResult` normalizes both shapes at the single point every caller passes through. A genuinely failing command still fails; non-JSON output is left alone.
+- `test/m104-phase-graph-verb-map.test.js`: 24 tests. Every mapped verb must answer target-free; the false comment cannot return; the verb must travel in `argv`; all six workflows must type their envelope and actually *call* the normalizer (defined-but-unwired fails).
+- `test/m94-d10-reader-wiring.test.js`: rewritten. It previously hardcoded the broken pairs (`plan → who-imports`, `impact → blast-radius`) and asserted they were present — passing on every run while those phases were dead. Restating a buggy value in a test is what let the bug live; it now asserts coverage and leaves verb correctness to the M104 tests, which check the CLI's real behaviour.
+
+Five other workflows carried the same permissive schema and could have failed identically — the phase workflow simply makes the largest graph query and hit it first. Suite 3107/0/13-skip.
+
 ## [5.6.10] - 2026-08-02
 
 ### Changed — the Environment Registry now fires (M103)

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.6.10** - 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.10",
+  "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.

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

@@ -61,8 +61,34 @@ const _args = (typeof args === "string") ? (() => { try { return JSON.parse(args
 const overrides = (_args.overrides && typeof _args.overrides === "object") ? _args.overrides : {};
 const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
-  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
+  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" }, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
 };
+// ─── Normalize a helper-agent CLI result (M104) ──────────────────────────────
+//
+// runCli asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A model doing that job is not perfectly reliable, and two broken
+// shapes both read `env.ok === undefined` — which every caller treats as failure,
+// so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed live 2026-08-02: a partition/plan halted four times on "graph BROKEN"
+// while the graph was fine (exit 0, ok:true).
+//
+// NOT a fallback: it continues past no failure and substitutes no guess — it reads
+// the result the CLI actually returned. A failing CLI still returns ok:false and
+// still fails; non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON */ }
+  }
+  return x;
+}
+
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseName) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -75,7 +101,7 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   const opts = { label, schema: _CLI_ENVELOPE_SCHEMA, model: "haiku" };
   if (phaseName) opts.phase = phaseName;
   const r = await agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
+  return _coerceCliResult(r) || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
 async function generateBrief(projectDir, { kind = "execute", milestone, domain, id, label = "brief", phaseName } = {}) {

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

@@ -190,8 +190,34 @@ const INTEGRATE_RESULT_SCHEMA = {
 const _args = (typeof args === "string") ? (() => { try { return JSON.parse(args); } catch { return {}; } })() : (args || {});
 const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
-  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
+  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" }, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
 };
+// ─── Normalize a helper-agent CLI result (M104) ──────────────────────────────
+//
+// runCli asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A model doing that job is not perfectly reliable, and two broken
+// shapes both read `env.ok === undefined` — which every caller treats as failure,
+// so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed live 2026-08-02: a partition/plan halted four times on "graph BROKEN"
+// while the graph was fine (exit 0, ok:true).
+//
+// NOT a fallback: it continues past no failure and substitutes no guess — it reads
+// the result the CLI actually returned. A failing CLI still returns ok:false and
+// still fails; non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON */ }
+  }
+  return x;
+}
+
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseName) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -204,7 +230,7 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   const opts = { label, schema: _CLI_ENVELOPE_SCHEMA, model: "haiku" };
   if (phaseName) opts.phase = phaseName;
   const r = await agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
+  return _coerceCliResult(r) || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
 async function runVerifyGate(projectDir, label = "verify-gate", phaseName) { return runCli(projectDir, "verify-gate", ["--json"], "gsd-t-verify-gate.cjs", label, true, phaseName); }

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

@@ -22,8 +22,34 @@ export const meta = {
 const _args = (typeof args === "string") ? (() => { try { return JSON.parse(args); } catch { return {}; } })() : (args || {});
 const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
-  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
+  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" }, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
 };
+// ─── Normalize a helper-agent CLI result (M104) ──────────────────────────────
+//
+// runCli asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A model doing that job is not perfectly reliable, and two broken
+// shapes both read `env.ok === undefined` — which every caller treats as failure,
+// so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed live 2026-08-02: a partition/plan halted four times on "graph BROKEN"
+// while the graph was fine (exit 0, ok:true).
+//
+// NOT a fallback: it continues past no failure and substitutes no guess — it reads
+// the result the CLI actually returned. A failing CLI still returns ok:false and
+// still fails; non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON */ }
+  }
+  return x;
+}
+
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseName) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -36,7 +62,7 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   const opts = { label, schema: _CLI_ENVELOPE_SCHEMA, model: "haiku" };
   if (phaseName) opts.phase = phaseName;
   const r = await agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
+  return _coerceCliResult(r) || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
 // Broken-Graph-Halts (EXEMPT carve-out): integrate is additive/announced — it does not

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

@@ -85,12 +85,57 @@ const _args = (typeof args === "string") ? (() => { try { return JSON.parse(args
 // are tier ALIASES. The sandbox runtime accepts BOTH forms in model: — proven live for
 // the tier alias resolves to claude-opus-5 (Fable removed 2026-07-24).
 const overrides = (_args.overrides && typeof _args.overrides === "object") ? _args.overrides : {};
+// `envelope` is typed as an OBJECT (or null), not "any".
+//
+// It used to be `envelope: {}` — a schema that accepts everything. A helper that
+// returned the raw JSON *text*, or omitted the field entirely, passed validation
+// just as cleanly as a correct parse; every caller then read `env.ok` on a string
+// or on undefined, got undefined, and failed closed on a HEALTHY CLI. Three
+// separate live halts traced back to this one permissive field.
+//
+// Typing it means the model is told the shape and a wrong shape is visible rather
+// than silently equivalent. `_coerceCliResult` still normalizes the two shapes
+// seen in the wild — the type is the specification, the coercion is the repair.
 const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
-  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
+  properties: {
+    ok: { type: "boolean" },
+    exitCode: { type: "integer" },
+    envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" },
+    stdout: { type: "string" },
+    stderr: { type: "string" },
+    via: { type: "string" },
+  },
 };
 // Single-quote a value for safe shell interpolation (Red Team MED-5).
 function _shq(s) { return `'${String(s).replace(/'/g, "'\\''")}'`; }
+// ─── Normalize a helper-agent CLI result ─────────────────────────────────────
+//
+// `runCli` asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A language model doing that job is not perfectly reliable, and the
+// schema types `envelope` as "any" — so THREE different shapes all validate and
+// only one is usable. Both broken shapes read `env.ok === undefined`, which every
+// caller treats as failure, so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed in the wild 2026-08-02: a binvoice partition halted three times on
+// "graph BROKEN" while the graph was fine (exit 0, ok:true).
+//
+// This normalizes both shapes at the ONE place every caller passes through. It is
+// NOT a fallback: it does not continue past a failure or substitute a guess — it
+// reads the result the CLI actually returned. A genuinely failing CLI still
+// returns `ok:false` and still fails; a non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON — leave it */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON — leave envelope absent */ }
+  }
+  return x;
+}
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseNameOpt) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -108,14 +153,14 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   // while a transient helper miss is recovered. Only retry when JSON was expected (parseJson)
   // and the parsed result is absent; never retry on a clean exit that simply returned no JSON.
   const runOnce = () => agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  let r = await runOnce();
+  let r = _coerceCliResult(await runOnce());
   // Retry once when JSON was expected but no parsed result came back — covers both the
   // throw path (via="error") and a malformed return the loose schema let through (ok=false
   // with the result absent). A real CLI failure that returned valid JSON (envelope present,
   // ok=false) is NOT retried — that is a true result, not a transient miss.
   const missingResult = (x) => !x || (parseJson && (x.envelope === undefined || x.envelope === null) && x.ok !== true);
   if (missingResult(r)) {
-    r = await runOnce();
+    r = _coerceCliResult(await runOnce());
   }
   return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
@@ -175,15 +220,28 @@ async function generateBrief(projectDir, { kind = "execute", milestone, domain,
 //   promote-debt → blast-radius (scope a debt item's reach)
 //   prd      → cluster        (structure-aware decomposition)
 //   milestone/discuss/design-decompose/doc-ripple → no structural verb (no-op)
+// A PHASE-level query takes NO target — it wants the whole structural picture, not
+// one file's neighbourhood. Only `cluster` and `dead-code` answer target-free;
+// `who-imports` / `blast-radius` / `who-calls` / `body` REQUIRE a target and return
+// {"ok":false,"reason":"missing-target"} without one.
+//
+// The original map used who-imports/blast-radius for five phases, under a comment
+// asserting they "return the full graph slice" without a target. That was never
+// true — verified against the live CLI. So plan / impact / feature / populate /
+// promote-debt failed their graph query on EVERY run in EVERY project since the map
+// shipped, each one halting with "graph BROKEN" on a perfectly healthy graph.
+// Fixed 2026-08-02 (binvoice S2-M14 plan halted on reason=missing-target).
+//
+// A mapped verb MUST answer target-free. Enforced by test/m104-phase-graph-verb-map.test.js.
 const PHASE_GRAPH_VERB_MAP = {
-  impact:         "blast-radius",
-  plan:           "who-imports",
+  impact:         "cluster",
+  plan:           "cluster",
   partition:      "cluster",
-  feature:        "blast-radius",
+  feature:        "cluster",
   "gap-analysis": "dead-code",
   project:        "cluster",
-  populate:       "who-imports",
-  "promote-debt": "blast-radius",
+  populate:       "cluster",
+  "promote-debt": "cluster",
   prd:            "cluster",
 };
 
@@ -203,11 +261,18 @@ async function queryStructuralSlice(projectDir, phaseName, phaseNameOpt, _rebuil
     // Phase has no mapped structural verb (milestone/discuss/design-decompose/doc-ripple) — no-op.
     return { ok: true, verb: null, slice: null, graphUnavailable: false, graphBroken: false, loudMessage: null };
   }
-  // The graph query uses gsd-t-graph-query-cli.cjs (local) or `gsd-t graph <verb>` (global).
-  // argv: only the verb (no target) for phase-level queries that return a global set
-  // (cluster/dead-code/who-imports/blast-radius without a target returns the full graph slice).
+  // The graph query runs bin/gsd-t-graph-query-cli.cjs (local) or `gsd-t graph …` (global).
+  //
+  // The verb MUST travel in `argv`, not in the subcmd string: runCli builds the LOCAL-bin
+  // command from `argv` ALONE (the subcmd text is only used for the global `gsd-t …` form).
+  // With the verb in subcmd and argv empty, any project carrying a local graph CLI ran it
+  // with NO verb at all → {"ok":false,"reason":"no-verb"} → fail-closed to BROKEN. That is
+  // why this failed in a project with a local bin/ copy and worked everywhere else.
+  // Fixed 2026-08-02 (binvoice S2-M14 partition halted twice on this).
+  //
+  // No target is passed — every mapped verb answers target-free (see PHASE_GRAPH_VERB_MAP).
   const r = await runCli(
-    projectDir, `graph ${verb}`, [], "gsd-t-graph-query-cli.cjs",
+    projectDir, "graph", [verb], "gsd-t-graph-query-cli.cjs",
     `graph:${verb}`, true, phaseNameOpt
   );
   const env = r.envelope || {};

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

@@ -44,11 +44,37 @@ const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
   properties: {
     ok: { type: "boolean" }, exitCode: { type: "integer" },
-    envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" },
+    envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" }, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" },
   },
 };
 // Run a `gsd-t <subcmd>` CLI (or project-local bin/<localBin>) via an agent's Bash and
 // return { ok, exitCode, envelope, stderr, via }. parseJson=true parses stdout as the envelope.
+// ─── Normalize a helper-agent CLI result (M104) ──────────────────────────────
+//
+// runCli asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A model doing that job is not perfectly reliable, and two broken
+// shapes both read `env.ok === undefined` — which every caller treats as failure,
+// so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed live 2026-08-02: a partition/plan halted four times on "graph BROKEN"
+// while the graph was fine (exit 0, ok:true).
+//
+// NOT a fallback: it continues past no failure and substitutes no guess — it reads
+// the result the CLI actually returned. A failing CLI still returns ok:false and
+// still fails; non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON */ }
+  }
+  return x;
+}
+
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseName) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -66,7 +92,7 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   if (phaseName) opts.phase = phaseName; // opts.phase MUST be a string, never the phase() fn
   const r = await agent(prompt, opts)
     .catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
+  return _coerceCliResult(r) || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) {
   return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName);

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

@@ -60,8 +60,34 @@ const _args = (typeof args === "string") ? (() => { try { return JSON.parse(args
 const overrides = (_args.overrides && typeof _args.overrides === "object") ? _args.overrides : {};
 const _CLI_ENVELOPE_SCHEMA = {
   type: "object", required: ["ok", "exitCode"], additionalProperties: true,
-  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: {}, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
+  properties: { ok: { type: "boolean" }, exitCode: { type: "integer" }, envelope: { type: ["object", "null"], description: "stdout PARSED as JSON — an object, never the raw text" }, stdout: { type: "string" }, stderr: { type: "string" }, via: { type: "string" } },
 };
+// ─── Normalize a helper-agent CLI result (M104) ──────────────────────────────
+//
+// runCli asks a haiku helper to run a command and hand back the parsed JSON in
+// `envelope`. A model doing that job is not perfectly reliable, and two broken
+// shapes both read `env.ok === undefined` — which every caller treats as failure,
+// so a HEALTHY CLI reports as broken:
+//   (a) `envelope` holds the raw JSON TEXT rather than the parsed object
+//   (b) `envelope` is absent and the JSON only reached `stdout`
+// Observed live 2026-08-02: a partition/plan halted four times on "graph BROKEN"
+// while the graph was fine (exit 0, ok:true).
+//
+// NOT a fallback: it continues past no failure and substitutes no guess — it reads
+// the result the CLI actually returned. A failing CLI still returns ok:false and
+// still fails; non-JSON stdout is left alone.
+function _coerceCliResult(x) {
+  if (!x) return x;
+  if (typeof x.envelope === "string") {
+    try { x.envelope = JSON.parse(x.envelope); } catch (_) { /* genuinely not JSON */ }
+  }
+  if ((x.envelope === undefined || x.envelope === null) &&
+      typeof x.stdout === "string" && x.stdout.trim().startsWith("{")) {
+    try { x.envelope = JSON.parse(x.stdout); } catch (_) { /* not JSON */ }
+  }
+  return x;
+}
+
 async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = true, phaseName) {
   const argStr = (argv || []).map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
   const prompt = [
@@ -74,7 +100,7 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   const opts = { label, schema: _CLI_ENVELOPE_SCHEMA, model: "haiku" };
   if (phaseName) opts.phase = phaseName;
   const r = await agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
-  return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
+  return _coerceCliResult(r) || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseName) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseName); }
 // Broken-Graph-Halts (EXEMPT carve-out): verify's graph slice is additive/announced — it