@tekyzinc/gsd-t 4.9.12 → 4.9.14

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.9.14] - 2026-06-25 (workflow runCli retry — reliability patch)
+
+### Fixed — transient helper-call flakes no longer false-block workflows
+
+`runCli` (the inline helper every `*.workflow.js` uses to run a GSD-T CLI command) delegates the call to a haiku helper agent, not a subprocess — so a return can transiently come back missing its parsed result, surfacing later as a cryptic `classify failed: no envelope` or a fail-closed gate block even though the CLI itself succeeded. Caught live during the M94 plan phase: the traceability gate passed when run directly (exit 0) but the workflow's confirm-call came back unparsed and failed closed.
+
+- `runCli` now **retries once** when JSON was expected but no parsed result returned (covers both the throw path and a malformed return the loose schema let through). A real CLI failure that returned valid JSON (`ok:false` with a present envelope) is **not** retried — a true result, not a transient miss.
+- Hardens every phase/wave/integrate/debug workflow's CLI calls (preflight, verify-gate, traceability, brief, build-coverage, test-data).
+
+## [4.9.13] - 2026-06-25 (M93 — Reader Contract every turn, retire the selective gate — patch)
+
+### Changed — concise output is now enforced on EVERY reply, not by pattern-matching
+
+The deterministic brevity-guard Stop hook kept missing verbose replies: a gate that matches a hardcoded list of known-bad opener phrases can only ever be **selective** — every new phrasing slips through (whack-a-mole). Per the user, the fix is to stop detecting and always apply the standard.
+
+- **Retired the brevity-guard Stop hook.** `gsd-t update-all` now *removes* it from any install that still has it.
+- **Reader Contract injected every turn** by the `UserPromptSubmit` hook (`scripts/gsd-t-auto-route.js`) — applies to ALL reader-facing output in every project: assume the first draft is wordy and rewrite it tight; answer first (intent-first only when about to change code); gloss jargon; bullets over paragraphs. Includes generic before→after examples that teach the shape.
+- This is wording-independent (no enumeration of bad phrasings) and universal (the standard is in front of the model each turn, not a backstop guessing which replies are bad).
+
 ## [4.9.12] - 2026-06-23 (M93 brevity-guard live-tuning — patch)
 
 ### Changed — brevity guard catches more, false-blocks less

package/README.md

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

@@ -395,48 +395,39 @@ function addHeartbeatHook(hooks, event, cmd) {
   return true;
 }
 
-// ─── Brevity Guard (M93) ────────────────────────────────────────────────────
-// A BLOCKING Stop hook (not async — it must run synchronously to block a verbose
-// answer-mode reply). Enforces the Reader Contract: answer-first, no preamble,
-// jargon glossed. Fail-open by design (the script never blocks on error).
+// ─── Reader Contract (M93) ──────────────────────────────────────────────────
+// RETIRED the deterministic brevity-guard Stop hook: a pattern-matching gate can
+// only ever be SELECTIVE (it catches the phrasings it enumerates and misses every
+// new one — the whack-a-mole the user hit). Replaced by the every-turn Reader
+// Contract injected by scripts/gsd-t-auto-route.js (the UserPromptSubmit hook):
+// the standard is put in front of the model each turn, applied to ALL replies,
+// instead of a backstop guessing which ones are bad. This function now REMOVES
+// the old Stop hook from any install that still has it.
 
 const BREVITY_GUARD_SCRIPT = "gsd-t-brevity-guard.js";
 
-function installBrevityGuard() {
-  ensureDir(SCRIPTS_DIR);
-  const src = path.join(PKG_SCRIPTS, BREVITY_GUARD_SCRIPT);
-  const dest = path.join(SCRIPTS_DIR, BREVITY_GUARD_SCRIPT);
-  if (!fs.existsSync(src)) { warn("Brevity-guard script not found in package — skipping"); return; }
-
-  const srcContent = fs.readFileSync(src, "utf8");
-  const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
-  if (normalizeEol(srcContent) !== normalizeEol(destContent)) {
-    copyFile(src, dest, BREVITY_GUARD_SCRIPT);
-  } else {
-    info("Brevity-guard script unchanged");
-  }
-
+function uninstallBrevityGuardHook() {
   const parsed = readSettingsJson();
   if (parsed === null && fs.existsSync(SETTINGS_JSON)) {
-    warn("settings.json has invalid JSON — cannot configure brevity-guard hook");
+    warn("settings.json has invalid JSON — cannot remove brevity-guard hook");
     return;
   }
   const settings = parsed || {};
-  if (!settings.hooks) settings.hooks = {};
-  if (!settings.hooks.Stop) settings.hooks.Stop = [];
-
-  const already = settings.hooks.Stop.some((entry) =>
-    entry.hooks && entry.hooks.some((h) => h.command && h.command.includes(BREVITY_GUARD_SCRIPT))
+  if (!settings.hooks || !Array.isArray(settings.hooks.Stop)) {
+    info("Reader Contract active every turn (no legacy brevity-guard hook to remove)");
+    return;
+  }
+  const before = settings.hooks.Stop.length;
+  settings.hooks.Stop = settings.hooks.Stop.filter((entry) =>
+    !(entry.hooks && entry.hooks.some((h) => h.command && h.command.includes(BREVITY_GUARD_SCRIPT)))
   );
-  if (already) { info("Brevity-guard hook already configured"); return; }
-
-  // Blocking (no async) so the Stop-hook block decision is honored.
-  const cmd = `node "${dest.replace(/\\/g, "\\\\")}"`;
-  settings.hooks.Stop.push({ matcher: "", hooks: [{ type: "command", command: cmd }] });
-
+  if (settings.hooks.Stop.length === before) {
+    info("Reader Contract active every turn (no legacy brevity-guard hook present)");
+    return;
+  }
   if (!isSymlink(SETTINGS_JSON)) {
     fs.writeFileSync(SETTINGS_JSON, JSON.stringify(settings, null, 2));
-    success("Brevity-guard Stop hook configured in settings.json");
+    success("Removed legacy brevity-guard Stop hook — Reader Contract now applies every turn");
   } else {
     warn("Skipping settings.json write — target is a symlink");
   }
@@ -1660,8 +1651,8 @@ async function doInstall(opts = {}) {
   heading("Heartbeat (Real-time Events)");
   installHeartbeat();
 
-  heading("Brevity Guard (M93 — concise replies)");
-  installBrevityGuard();
+  heading("Reader Contract (M93 — concise replies, every turn)");
+  uninstallBrevityGuardHook();
 
   heading("Update Check (Session Start)");
   installUpdateCheck();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.9.12",
+  "version": "4.9.14",
   "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-auto-route.js

@@ -26,6 +26,21 @@
 const fs = require("fs");
 const path = require("path");
 
+// Reader Contract — emitted every turn so the standard is in front of the model
+// each response (not a selective after-the-fact gate). Concise + jargon-free by
+// its own rule. Generic before/after examples teach the shape.
+const READER_CONTRACT = [
+  "[GSD-T READER CONTRACT] Before sending ANY reply, assume your first draft is too wordy and rewrite it tight. Rules:",
+  "• Answer FIRST. No preamble, no restating the question, no narrating what you're about to do (\"let me check…\"). Do the work silently, then give the result.",
+  "• Exception — when you're about to CHANGE code/files: state intent in one line first, so the user can stop a wrong direction.",
+  "• Gloss every code/jargon term in plain words on first use. No bare IDs or acronyms the reader must decode.",
+  "• Bullets/tables over paragraphs. Cut hedging and meta-commentary. Expand only if asked.",
+  "EXAMPLES (before → after):",
+  "• \"That's a great question, and it touches on something subtle. Let me look into how the cache works before I answer…\" → \"The cache lives in memory, cleared on restart.\"",
+  "• \"There are a few moving parts here. First, I want to make sure I understand the goal, because X has a gotcha…\" → \"Set X in .env. Gotcha: also add the localhost redirect URI or it rejects.\"",
+  "• \"Good catch — I conflated two things. Here's the honest correction: the files actually stack rather than overwrite…\" → \"You're right — files stack, they don't overwrite.\"",
+].join("\n");
+
 /**
  * Resolve the active model profile from .gsd-t/model-profile.json.
  *
@@ -123,6 +138,12 @@ process.stdin.on("end", () => {
   // [GSD-T NOW] format is date-guard-invariant: NEVER alter it.
   process.stdout.write(`[GSD-T NOW] ${liveTimestamp()}\n`);
 
+  // Reader Contract — injected EVERY turn, EVERY project (M93). The deterministic
+  // brevity gate was retired (it could only ever be selective); this puts the
+  // standard in front of the model each turn instead. Assume the first draft is
+  // wordy; rewrite it tight before sending.
+  process.stdout.write(READER_CONTRACT + "\n");
+
   // Parse stdin ONCE; both the profile token and auto-route reuse it.
   let data = null;
   try { data = JSON.parse(input); } catch (_) { /* tolerated — gates below skip */ }

package/templates/CLAUDE-global.md

@@ -44,7 +44,7 @@ Two reply shapes, picked by what the user wants. **Discriminator: are you modify
 - **Gloss jargon.** Never a bare code/acronym (e.g. `S2-M7` = section 2, milestone 7; `HC-003` = a rule ID) — say what it means in plain words on first use.
 - **Format.** Bullets/tables over paragraphs; expand only on request; the dated banner stays (first line, always).
 
-**ENFORCED, not advised:** the `gsd-t-brevity-guard` Stop hook (a gate that runs when a reply finishes) is the backstop — a verbose/narrating reply is caught there. This block makes the gate rarely need to fire.
+**Applied to EVERY reply, not selectively.** Assume your first draft is too wordy and rewrite it tight before sending — do not wait to be told. The `[GSD-T READER CONTRACT]` block (injected every turn by the UserPromptSubmit hook) restates this each response. (The old pattern-matching brevity Stop hook was retired: a gate that matches known-bad phrasings can only ever be selective and misses every new wording. The fix is to hold the standard for ALL output, every turn.)
 
 
 # GSD-T: Contract-Driven Development

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

@@ -102,7 +102,21 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
   ].join("\n");
   const opts = { label, schema: _CLI_ENVELOPE_SCHEMA, model: "haiku" };
   if (phaseNameOpt) opts.phase = phaseNameOpt;
-  const r = await agent(prompt, opts).catch((e) => ({ ok: false, exitCode: -1, envelope: null, stderr: String(e && e.message), via: "error" }));
+  // The CLI is run by a haiku helper agent, not a subprocess, so a return can transiently
+  // come back missing its parsed result. Retry ONCE on a missing/unparsed result before
+  // giving up — a genuine CLI failure fails both attempts (real error survives the retry),
+  // 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();
+  // 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();
+  }
   return r || { ok: false, exitCode: -1, envelope: null, via: "error" };
 }
 async function runPreflight(projectDir, label = "preflight", phaseNameOpt) { return runCli(projectDir, "preflight", ["--json"], "cli-preflight.cjs", label, true, phaseNameOpt); }