@tekyzinc/gsd-t 4.9.11 → 4.9.13

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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
+
+Live use surfaced two gaps in the M93 brevity-guard Stop hook (it missed a real verbose reply, then would have false-blocked a clean one):
+
+- **Interleaved preamble detection** — the guard previously only caught process-narration *stacked at the very front*. It now also catches narration/meta-commentary *scattered through the opening* (ack → narrate → a little content → narrate again → over-explain), which is the real exhausting shape. Conservative: scans only the first 6 sentences, needs ≥2 hits.
+- **Narrowed live-reply jargon scope** — the hook no longer forces a gloss on a bare milestone code like `M92` (established conversational shorthand once context exists — it was false-blocking clean answers). It still forces glosses on the genuinely opaque IDs (`HC-003`, `S2-M7`). The stricter rule stays in the document lint (`gsd-t-jargon-lint.cjs`), where a reader has no conversation for context.
+
 ## [4.9.11] - 2026-06-23 (M93 — Brevity Guard: enforce concise, answer-first output — patch)
 
 ### Added — conciseness is now enforced, not just requested

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.9.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.9.13** - 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.11",
+  "version": "4.9.13",
   "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/scripts/gsd-t-brevity-guard.js

@@ -63,15 +63,28 @@ const ALLOWLIST = new Set([
 ]);
 
 // High-signal code-token patterns (bare, unglossed → block on first use).
+// LIVE-REPLY scope only: limited to the genuinely opaque IDs the user can't decode
+// (contract / hard-constraint / stage-milestone codes). A bare `M92` milestone ref
+// is established conversational shorthand once context exists — forcing a gloss on
+// it every turn is over-strict and false-blocks clean answers. The stricter
+// `M\d+-D\d+`-and-bare-`M\d+` rule stays in the DOC lint (bin/gsd-t-jargon-lint.cjs),
+// where a reader has no conversational context. (M93 live-tuning, 2026-06-23.)
 const JARGON_PATTERNS = [
-  /\bS2-M\d+\b/,            // S2-M7
-  /\bHC-\d+\b/,            // HC-003
-  /\bM\d+(?:-D\d+(?:-T\d+)?)?\b/, // M92, M92-D1, M92-D1-T3
+  /\bS2-M\d+\b/,            // S2-M7  (stage-milestone code)
+  /\bHC-\d+\b/,            // HC-003 (hard-constraint / contract id)
 ];
 
 // Narration openers: first-person "about to" framing — intent without content.
 const NARRATION_OPENER =
-  /^(let me|before i\b|i'?ll\b|i'?m going to|i am going to|first,?\s+let me|i want to|i need to|let's|let us|going to)\b/i;
+  /^(let me|before i\b|i'?ll\b|i'?m going to|i am going to|first,?\s+let me|i want to|i need to|let's|let us|going to|i need to be|i have to|i should|i want to be|let me untangle|i'?m going to verify)\b/i;
+
+// Meta-commentary / hedge openers — sentences that talk ABOUT the answer instead
+// of giving it ("the honest correction:", "here's the real picture", "good catch —
+// and I…", "where does that leave you"). These don't match NARRATION_OPENER but are
+// the same preamble disease — over-explaining around the answer. Counted in the
+// interleaved scan, NOT the leading scan (they appear mid-reply).
+const META_OPENER =
+  /^(good (catch|question|point|instinct)|fair (challenge|point)|the honest|here'?s (the|what)|so,? (where|to|that|let)|that'?s (a |the )?(real|fair|honest)|the (real |accurate )?(picture|version|correction|nuance)|to (untangle|be (clear|precise|careful|honest))|i (conflated|misspoke|need to be|want to be))\b/i;
 
 // ── Transcript tail-scan (REUSED from gsd-t-conversation-capture.js) ─────────
 // Pull the most recent assistant turn from a Claude Code transcript JSONL by
@@ -223,6 +236,21 @@ function _leadingNarrationCount(prose) {
   return count;
 }
 
+// Count narration + meta-commentary sentences INTERLEAVED in the opening region
+// (the first WINDOW sentences), regardless of contiguity. Catches the real failure
+// shape the leading-only scan misses: an ack, then narration, then a content
+// sentence, then MORE narration ("Good catch… Let me untangle… What I said was X…
+// Let me verify…"). Conservative: only scans the opening window, needs >=2 hits.
+const INTERLEAVED_WINDOW = 6;
+function _interleavedPreambleCount(prose) {
+  const sentences = _sentences(prose).slice(0, INTERLEAVED_WINDOW);
+  let count = 0;
+  for (const s of sentences) {
+    if (NARRATION_OPENER.test(s) || META_OPENER.test(s)) count++;
+  }
+  return count;
+}
+
 // Find a bare unglossed high-signal jargon token (first occurrence, no gloss).
 // A gloss = parenthetical or quote in the SAME sentence containing the token.
 function _findBareJargon(prose) {
@@ -268,6 +296,18 @@ function detect(text, mode) {
     };
   }
 
+  // Interleaved preamble: narration/meta-commentary scattered through the opening
+  // (not just stacked at the front). The real exhausting shape: ack → narrate →
+  // a bit of content → narrate again → over-explain.
+  const interleaved = _interleavedPreambleCount(prose);
+  if (interleaved >= 2) {
+    return {
+      block: true,
+      reason: "Answer-first: the opening has " + interleaved +
+        " preamble/meta sentences (narration or 'here's the real picture'-style framing) around the answer. Lead with the answer; cut the meta-commentary.",
+    };
+  }
+
   const jargon = _findBareJargon(prose);
   if (jargon) {
     return {

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