@tekyzinc/gsd-t 5.6.10 → 5.6.11

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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.6.11** - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.6.10",
+  "version": "5.6.11",
   "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/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