@tekyzinc/gsd-t 4.8.10 → 4.9.11

package/scripts/gsd-t-brevity-guard.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+/**
+ * GSD-T Stop hook — blocks exhausting ANSWER-mode replies before the user reads them.
+ *
+ * The deterministic enforcement the prose "be concise" rule never had: when the
+ * assistant answers a question with stacked process-narration (intent-without-content)
+ * preamble, or drops a bare unglossed high-signal jargon token, this hook BLOCKS the
+ * stop and forces a rewrite (answer-first, glossed). Tuned CONSERVATIVE: catch only the
+ * egregious cases (≥2 stacked narration sentences, or a bare high-signal token) — never
+ * police word count, tone, or every acronym.
+ *
+ * ─── Stdin (Claude Code Stop hook payload) ───────────────────────────────────
+ *   { "transcript_path": "...", "stop_hook_active": true|false,
+ *     "session_id": "...", "hook_event_name": "Stop", "cwd": "..." }
+ *
+ * ─── Block contract (confirmed via Claude Code hooks docs) ────────────────────
+ *   https://code.claude.com/docs/en/hooks.md
+ *   A Stop hook blocks by writing `{"decision":"block","reason":"<why>"}` to stdout
+ *   and exiting 0. `reason` is fed back to Claude as the instruction for what to fix
+ *   (here: rewrite answer-first / gloss the term). We use THIS structured form (not
+ *   exit-2-stderr) so the reason is delivered cleanly. Exit 0 with no JSON = allow.
+ *
+ * ─── Loop-guard ──────────────────────────────────────────────────────────────
+ *   If `stop_hook_active === true` (this Stop is already a re-entry from a prior
+ *   block), EXIT 0 immediately — never block twice on the same turn (no infinite
+ *   rewrite loop).
+ *
+ * ─── Mode discriminator ──────────────────────────────────────────────────────
+ *   ACTION-mode (about to change code: latest assistant turn carried a mutating
+ *   tool_use — Write/Edit/NotebookEdit, or a Bash mutation — OR is a tool_use-only
+ *   turn with empty text) → intent-first is WANTED → ALLOW.
+ *   ANSWER-mode (a pure-text reply to a question) → enforce answer-first.
+ *
+ * ─── FAIL-OPEN (non-negotiable) ──────────────────────────────────────────────
+ *   ANY internal error / unreadable transcript / malformed payload / no assistant
+ *   message → EXIT 0 (allow). A broken guard must NEVER gag a legitimate reply.
+ *
+ * ─── CLI (unit-testable without a transcript) ────────────────────────────────
+ *   node gsd-t-brevity-guard.js --text "<reply>" --mode answer|action
+ *     → prints `{"decision":"block","reason":...}` + exit 1 on BLOCK,
+ *       exit 0 (no output) on ALLOW. (CLI exit 1 ≠ hook exit; hook always exits 0.)
+ *
+ * ─── INTEGRATE-SEAM (do NOT wire here) ───────────────────────────────────────
+ *   Add to ~/.claude/settings.json (and the installer settings template):
+ *     "hooks": { "Stop": [ { "hooks": [ {
+ *       "type": "command",
+ *       "command": "node ~/.claude/scripts/hooks/gsd-t-brevity-guard.js"
+ *     } ] } ] }
+ *
+ * Zero deps. Pure text analysis. Zero LLM. Never throws.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ── Jargon allowlist (exempt acronyms — extend conservatively) ──────────────
+const ALLOWLIST = new Set([
+  "GSD-T", "QA", "CLI", "API", "URL", "DB", "JSON", "HTML", "CSS", "HTTP",
+  "NDJSON", "DTO", "PDT", "EST", "UTC", "AND", "OR", "NOT",
+]);
+
+// High-signal code-token patterns (bare, unglossed → block on first use).
+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
+];
+
+// 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;
+
+// ── Transcript tail-scan (REUSED from gsd-t-conversation-capture.js) ─────────
+// Pull the most recent assistant turn from a Claude Code transcript JSONL by
+// scanning from the tail. Returns { text, hasMutatingTool, toolOnly } or null.
+// Distinguishes text blocks (the answer) from tool_use blocks (the action signal).
+function _safeTranscriptPath(p) {
+  if (typeof p !== "string" || p.length === 0) return null;
+  if (!path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const allowedRoot = path.resolve(home, ".claude", "projects") + path.sep;
+  const resolved = path.resolve(p);
+  if (!resolved.startsWith(allowedRoot)) return null;
+  return resolved;
+}
+
+function _readFileTail(filePath, bytes) {
+  let fd = -1;
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) return "";
+    const size = st.size;
+    if (size === 0) return "";
+    const want = Math.min(bytes, size);
+    const start = size - want;
+    fd = fs.openSync(filePath, "r");
+    const buf = Buffer.alloc(want);
+    fs.readSync(fd, buf, 0, want, start);
+    let str = buf.toString("utf8");
+    if (start > 0) {
+      const nl = str.indexOf("\n");
+      if (nl >= 0) str = str.slice(nl + 1);
+    }
+    return str;
+  } catch (_) {
+    return "";
+  } finally {
+    if (fd >= 0) { try { fs.closeSync(fd); } catch (_) { /* noop */ } }
+  }
+}
+
+const MUTATING_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+// Bash command is a mutation if it invokes a write-ish verb (heuristic, conservative).
+const BASH_MUTATION =
+  /\b(rm|mv|cp|mkdir|touch|tee|chmod|chown|git\s+(commit|add|push|rm|mv|checkout|reset|merge|rebase)|npm\s+(install|i|publish|run)|node\s|>>?|sed\s+-i)\b/;
+
+function _isMutatingToolBlock(b) {
+  if (!b || b.type !== "tool_use") return false;
+  if (MUTATING_TOOLS.has(b.name)) return true;
+  if (b.name === "Bash") {
+    const cmd = b.input && typeof b.input.command === "string" ? b.input.command : "";
+    return BASH_MUTATION.test(cmd);
+  }
+  return false;
+}
+
+function _readAssistantFromTranscript(transcriptPath) {
+  const safe = _safeTranscriptPath(transcriptPath);
+  if (!safe) return null;
+  const tail = _readFileTail(safe, 64 * 1024);
+  if (!tail) return null;
+  const lines = tail.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line) continue;
+    let row;
+    try { row = JSON.parse(line); } catch (_) { continue; }
+    if (!row || row.type !== "assistant") continue;
+    if (row.isSidechain === true) continue;
+    const msg = row.message;
+    if (!msg) continue;
+    const blocks = msg.content;
+    if (typeof blocks === "string") {
+      return { text: blocks, hasMutatingTool: false, toolOnly: false };
+    }
+    if (!Array.isArray(blocks)) continue;
+    const texts = [];
+    let hasMutatingTool = false;
+    let hasToolUse = false;
+    for (const b of blocks) {
+      if (b && b.type === "text" && typeof b.text === "string") texts.push(b.text);
+      if (b && b.type === "tool_use") {
+        hasToolUse = true;
+        if (_isMutatingToolBlock(b)) hasMutatingTool = true;
+      }
+    }
+    const text = texts.join("");
+    if (text.length === 0 && !hasToolUse) continue; // empty, keep scanning
+    return { text, hasMutatingTool, toolOnly: text.trim().length === 0 && hasToolUse };
+  }
+  return null;
+}
+
+// ── Detection (pure) ─────────────────────────────────────────────────────────
+
+// Strip the dated status banner (first line, "Day: Mon DD, YYYY ... — GSD-T ...").
+function _stripBanner(text) {
+  const nl = text.indexOf("\n");
+  const first = nl >= 0 ? text.slice(0, nl) : text;
+  if (/^[A-Z][a-z]{2,8}:\s+\w{3}\s+\d{1,2},\s+\d{4}/.test(first.trim())) {
+    return nl >= 0 ? text.slice(nl + 1) : "";
+  }
+  return text;
+}
+
+// Remove fenced code blocks and table rows (content, never preamble).
+function _stripStructured(text) {
+  const out = [];
+  let inFence = false;
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (/^```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (/^\|.*\|/.test(line)) continue; // table row
+    out.push(raw);
+  }
+  return out.join("\n");
+}
+
+// Split prose into sentences (coarse — period/!/? or newline boundary).
+function _sentences(text) {
+  return text
+    .replace(/\s+/g, " ")
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// Count narration sentences in the LEADING region (before substantive content).
+// A reply may open with ONE short acknowledgement/framing sentence (e.g. "Important
+// question." / "Fair challenge.") — that's wanted, not preamble. But narration that
+// STACKS after such an ack ("Let me find the record. Before I answer, I should check…")
+// is the egregious case the user flagged. So: tolerate a single short non-narration
+// lead sentence, then count narration; stop at the first substantive (non-narration,
+// non-short-ack) sentence. Block fires at >=2 narration in that leading region.
+function _leadingNarrationCount(prose) {
+  const sentences = _sentences(prose);
+  let count = 0;
+  let ackUsed = false;
+  for (const s of sentences) {
+    if (NARRATION_OPENER.test(s)) { count++; continue; }
+    // A short non-narration sentence (<= ~12 words) is treated as an allowed
+    // acknowledgement/framing line ONCE; a second one, or any longer sentence,
+    // is real content → the leading region ends.
+    const words = s.trim().split(/\s+/).length;
+    if (!ackUsed && words <= 12) { ackUsed = true; continue; }
+    break;
+  }
+  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) {
+  const sentences = _sentences(prose);
+  const seen = new Set();
+  for (const s of sentences) {
+    for (const re of JARGON_PATTERNS) {
+      const m = s.match(re);
+      if (!m) continue;
+      const token = m[0];
+      if (seen.has(token)) continue;
+      // skip allowlisted ALL-CAPS lookalikes (none of these patterns are, but defensive)
+      if (ALLOWLIST.has(token)) continue;
+      seen.add(token);
+      // Glossed if a parenthetical or quoted phrase appears in the same sentence.
+      const hasGloss = /\([^)]*\)/.test(s) || /["“'][^"”']{4,}["”']/.test(s);
+      if (!hasGloss) return token;
+    }
+  }
+  return null;
+}
+
+// NOTE: bare ALL-CAPS acronyms (TTL, TLS, CDN, …) are intentionally NOT policed.
+// The spec lists them but caps it "extend conservatively / do NOT police every
+// acronym" — generic ALL-CAPS is a false-positive engine on common tech terms.
+// Only the high-signal code-token patterns above (S2-M\d, HC-\d, M\d[-D\d][-T\d])
+// are unambiguous jargon worth a forced gloss. The ALLOWLIST is retained for any
+// future, deliberate extension of JARGON_PATTERNS into acronym territory.
+
+// Core detector. mode: "answer" | "action". Returns { block, reason }.
+function detect(text, mode) {
+  if (mode === "action") return { block: false };
+  if (typeof text !== "string" || text.trim().length === 0) return { block: false };
+
+  const prose = _stripStructured(_stripBanner(text));
+
+  const narration = _leadingNarrationCount(prose);
+  if (narration >= 2) {
+    return {
+      block: true,
+      reason: "Answer-first: lead with the answer, not " + narration +
+        " stacked 'about-to' narration sentences. Cut the preamble; state the answer, then detail.",
+    };
+  }
+
+  const jargon = _findBareJargon(prose);
+  if (jargon) {
+    return {
+      block: true,
+      reason: "Gloss '" + jargon + "' on first use (one plain-language clause in parens). Bare code-token, no gloss.",
+    };
+  }
+
+  return { block: false };
+}
+
+// ── Mode classification from a transcript turn ───────────────────────────────
+function classifyMode(turn) {
+  if (turn && (turn.hasMutatingTool || turn.toolOnly)) return "action";
+  return "answer";
+}
+
+// ── Entry: process a Stop-hook payload → { block, reason } ───────────────────
+function processPayload(payload) {
+  if (!payload || typeof payload !== "object") return { block: false }; // fail-open
+  if (payload.stop_hook_active) return { block: false };                // loop-guard (truthy — never re-block a re-entry, even if the flag arrives non-boolean)
+  const turn = _readAssistantFromTranscript(payload.transcript_path);
+  if (!turn) return { block: false }; // no message → fail-open
+  return detect(turn.text, classifyMode(turn));
+}
+
+// ── CLI / hook driver ────────────────────────────────────────────────────────
+function _emitBlock(reason) {
+  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
+}
+
+function runCli(argv) {
+  // --text "<reply>" --mode answer|action
+  let text = null, mode = "answer";
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--text") { text = argv[i + 1]; i++; }
+    else if (argv[i] === "--mode") { mode = argv[i + 1]; i++; }
+  }
+  const res = detect(typeof text === "string" ? text : "", mode === "action" ? "action" : "answer");
+  if (res.block) { _emitBlock(res.reason); process.exit(1); }
+  process.exit(0);
+}
+
+function main() {
+  try {
+    const argv = process.argv.slice(2);
+    if (argv.includes("--text")) { runCli(argv); return; }
+
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => { input += c; });
+    process.stdin.on("end", () => {
+      try {
+        let payload;
+        try { payload = JSON.parse(input); } catch { process.exit(0); } // fail-open
+        const res = processPayload(payload);
+        if (res.block) { _emitBlock(res.reason); process.exit(0); } // block via JSON, exit 0
+        process.exit(0); // allow
+      } catch { process.exit(0); } // fail-open
+    });
+    process.stdin.on("error", () => process.exit(0)); // fail-open
+  } catch { process.exit(0); } // fail-open
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  detect, classifyMode, processPayload, _findBareJargon,
+  _leadingNarrationCount, _readAssistantFromTranscript, ALLOWLIST,
+};

package/templates/CLAUDE-global.md

@@ -30,6 +30,22 @@ The litmus test: if a sentence would survive being deleted without the user losi
 
 Verbose mode (opt-in, `Output Style: verbose`): full narrative prose, inline rationale, the longer style. Don't apply verbose unless a project requests it.
 
+## Reader Contract (the question-vs-action split)
+
+Two reply shapes, picked by what the user wants. **Discriminator: are you modifying something, or just telling?**
+
+| Situation | Lead with | Why |
+|-----------|-----------|-----|
+| **Question** (wants an answer) | **answer first** | They want the conclusion, not the path to it |
+| **Action** (about to change code) | **intent first** | Lets them short-circuit a wrong direction before you spend the edit |
+
+- **Question → answer first.** No process-narration — drop "let me find/check/verify before I answer". One direction-ack sentence is fine; stacking 2+ "about to do X" lines before the answer is the banned pattern. (Do the checking silently, then state the verified result.)
+- **Action → intent first.** This is the ONLY place leading-with-intent is correct.
+- **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.
+
 
 # GSD-T: Contract-Driven Development
 

package/templates/prompts/blind-adversary-subagent.md

@@ -1,5 +1,9 @@
 # Blind-Adversary Subagent Prompt — Architectural Premise Challenge
 
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term (e.g. `M93-D2` = milestone 93, domain 2) in plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
 **Model:** `fable` (M85 tier policy — highest-leverage judgment; separate context from the proposing agent)
 
 **Framing:** You are reviewing someone ELSE's architectural design — you did NOT propose it and have no attachment to it. Your goal is to find the **fatal flaw** in the premise being challenged, before a single line of code is committed to that premise. This framing (independent reviewer, not the author) is essential for escaping self-preference bias: the proposing agent's prior context makes it systematically less able to see its own premise's failures (source: https://arxiv.org/abs/2310.08118 — LLM self-evaluation is biased toward confirming prior outputs; https://arxiv.org/abs/2404.13076 — blind adversarial framing surfaces failures that self-critique misses).

package/templates/prompts/pre-mortem-subagent.md

@@ -1,5 +1,9 @@
 # Pre-Mortem Subagent Prompt — Adversarial Plan Review (pre-execute)
 
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term (e.g. `M93-D2` = milestone 93, domain 2) in plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
 You are an adversarial Pre-Mortem reviewer. You attack the PLAN, not the code — because the code does not exist yet. Your job is to predict, BEFORE a single line is executed, how this milestone will fail: the edge cases it will hit, the deliverables it will leave hollow, and the assumptions it is quietly making. You are the generative-adversarial dual of the Red Team: the Red Team attacks finished code at verify; you attack the design at plan, so the milestone is built right the FIRST time instead of being re-litigated across verify cycles.
 
 **Inverted incentives.** Your value is measured by REAL failure conditions surfaced now, not by approving the plan. A plan you bless that later burns verify cycles is YOUR failure. Assume the plan is flawed and find where.

package/templates/prompts/qa-subagent.md

@@ -1,5 +1,9 @@
 # QA Subagent Prompt — Per-Task Validation
 
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term (e.g. `M93-D2` = milestone 93, domain 2) in plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
 You are the QA agent. Your sole job is test generation, execution, and gap reporting. You write ZERO feature code. You never modify implementation files — only test files and reports.
 
 <!-- M61 D7-T3: Workflow-stage invocation -->

package/templates/prompts/red-team-subagent.md

@@ -1,5 +1,9 @@
 # Red Team Subagent Prompt — Adversarial QA (per-domain)
 
+<!-- reader-contract -->
+**Report concisely:** verdict/answer first, no preamble. Gloss every code/jargon term (e.g. `M93-D2` = milestone 93, domain 2) in plain words on first use. Bullets over paragraphs. Expand only if asked.
+<!-- /reader-contract -->
+
 You are a Red Team QA adversary. Your job is to BREAK the code that was just written for this domain. You operate with inverted incentives — your value is measured by REAL bugs found, not tests passed.
 
 <!-- M61 D7-T3: Workflow-stage invocation -->

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

@@ -548,9 +548,15 @@ for (const dr of domainResults.filter(Boolean)) {
     reason: triggerEnv.reason || null,
     provenByAdversaryOnly: triggerEnv.provenByAdversaryOnly || false,
     stopDirective: triggerEnv.stopDirective || false,
+    // M92 — surface the cheaper-first response rung + its directive (look→smallest→spike→defer)
+    // so the "look at what exists / smallest change" guidance reaches the worker.
+    mode: triggerEnv.mode || null,
+    responseDirective: triggerEnv.lookDirective || triggerEnv.smallestDirective || triggerEnv.deferDirective || null,
   });
 }
-log(`M90 arch-trigger: ${domainArchTriggerResults.length} domain(s) fired extend-existing-code signal`);
+log(`M90 arch-trigger: ${domainArchTriggerResults.length} domain(s) fired extend-existing-code signal` +
+  (domainArchTriggerResults.some((r) => r.mode === "look")
+    ? ` — M92 default response: LOOK (grep/read existing before scoping)` : ""));
 
 phase("Integrate");
 const integratePrompt = [

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

@@ -182,8 +182,17 @@ const result = await agent(
     `Quick task: ${task}`,
     `**Brief:** ${brief.briefPath || "(no brief)"}`,
     ``,
+    `**CRUX-FIRST — START HERE (smallest change is the default, ceremony is opt-in):**`,
+    `1. CRUX: state the crux of this ask in ONE line — the single thing that must become true.`,
+    `2. WHAT EXISTS: grep/read what ALREADY exists for this before choosing any scope.`,
+    `   Do not build outward until you know what is already here to edit.`,
+    `3. SMALLEST CHANGE: propose the SMALLEST change that hits the crux — edit INWARD at the`,
+    `   source (the one place the behavior is defined), not OUTWARD at the N consumers.`,
+    `   The recommendation is "do it directly / one-file change," not a partition or plan.`,
+    `4. ESCALATE ONLY IF NEEDED: reach for ceremony (plan→execute, partition, competition) ONLY`,
+    `   when the crux genuinely needs cross-domain coordination or real uncertainty — and say WHY.`,
+    ``,
     `Constraints from CLAUDE.md:`,
-    `- SIMPLICITY ABOVE ALL — minimal change`,
     `- Check downstream effects before changing existing code`,
     `- Run affected tests before reporting done`,
     `- Update relevant docs in the same commit`,
@@ -372,13 +381,18 @@ if (Array.isArray(result.filesEdited) && result.filesEdited.length > 0) {
       "Research"
     );
     const triggerEnv = triggerResult.envelope || {};
-    log(`M90 arch-trigger quick: fired=${triggerEnv.fired} reason=${triggerEnv.reason || "?"} provenByAdversaryOnly=${triggerEnv.provenByAdversaryOnly || false}`);
+    const m92Directive = triggerEnv.lookDirective || triggerEnv.smallestDirective || triggerEnv.deferDirective || null;
+    log(`M90 arch-trigger quick: fired=${triggerEnv.fired} reason=${triggerEnv.reason || "?"} provenByAdversaryOnly=${triggerEnv.provenByAdversaryOnly || false}` +
+      (triggerEnv.mode ? ` — M92 response: ${triggerEnv.mode}${triggerEnv.mode === "look" ? " (grep/read existing before scoping)" : ""}` : ""));
     quickArchTriggerResult = {
       existingFiles,
       fired: triggerEnv.fired || false,
       reason: triggerEnv.reason || null,
       provenByAdversaryOnly: triggerEnv.provenByAdversaryOnly || false,
       stopDirective: triggerEnv.stopDirective || false,
+      // M92 — cheaper-first response rung + its directive surfaced to the quick worker.
+      mode: triggerEnv.mode || null,
+      responseDirective: m92Directive,
     };
   }
 }

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

@@ -78,6 +78,13 @@ async function runCli(projectDir, subcmd, argv, localBin, label, parseJson = tru
 }
 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); }
+// M92 D2 (keystone) — the deterministic shrink-metric. Computes the milestone diff's
+// net size from `git diff --numstat <range>` via the shared runCli helper (M71-clean:
+// the git call runs in the agent's Bash, NOT via require/fs/child_process here). model:
+// "haiku" (mechanical), like the other deterministic-gate CLI calls.
+async function runShrinkMetric(projectDir, range, label = "m92:shrink-metric", phaseName) {
+  return runCli(projectDir, "shrink-metric", ["--range", range, "--project-dir", projectDir, "--json"], "gsd-t-shrink-metric.cjs", label, true, phaseName);
+}
 async function generateBrief(projectDir, { kind = "verify", milestone, domain, id, label = "brief", phaseName } = {}) {
   const argv = ["--kind", kind, "--spawn-id", id, "--out", `${projectDir}/.gsd-t/briefs/${id}.json`];
   if (milestone) argv.push("--milestone", milestone);
@@ -206,6 +213,20 @@ const VERDICT_SCHEMA = {
     overallVerdict: { type: "string", enum: ["VERIFIED", "VERIFIED-WITH-WARNINGS", "VERIFY-FAILED"] },
     summary:        { type: "string" },
     blockingFindings: { type: "array", items: { type: "string" } },
+    // M92 D2 (keystone) — ADDITIVE, ORTHOGONAL "did it get leaner" readout. The
+    // 3-enum stays the pure correctness gate (AND-of-gates); `shrink` is a SEPARATE
+    // success dimension surfaced ALONGSIDE it (never folded into pass/fail). MEASURED
+    // by bin/gsd-t-shrink-metric.cjs from `git diff --numstat`, never LLM-attested.
+    // Optional: omitted when the diff base is unavailable (logged skip-with-reason).
+    shrink: {
+      type: "object",
+      required: ["netLoc", "leaner"],
+      additionalProperties: true,
+      properties: {
+        netLoc: { type: "number" },
+        leaner: { type: "boolean" },
+      },
+    },
   },
 };
 
@@ -693,6 +714,55 @@ const stages = [
 
 const triadResults = await parallel(stages);
 
+// ─── M92 D2 Shrink-Metric (keystone — ADDITIVE leanness dimension) ─────────
+// Before synthesis, MEASURE the milestone diff's net size so the verdict can SAY
+// "we made it smaller" — a first-class, ORTHOGONAL success dimension surfaced
+// ALONGSIDE the overallVerdict enum (never folded into pass/fail). MEASURED, never
+// LLM-attested ([[feedback_measure_dont_claim]]): the metric is computed by
+// bin/gsd-t-shrink-metric.cjs from `git diff --numstat <base>..HEAD`.
+//
+// The diff base = the milestone branch-point (merge-base of HEAD against the default
+// branch). M71-clean: BOTH the merge-base resolution AND the numstat run go through an
+// agent's Bash, never require/fs/child_process in this orchestrator. If the base can't
+// be resolved (detached HEAD, shallow clone, no default branch), the metric is SKIPPED
+// with a logged reason — NEVER fabricated ([[feedback_no_silent_degradation]]).
+const SHRINK_BASE_SCHEMA = {
+  type: "object",
+  required: ["resolved"],
+  additionalProperties: true,
+  properties: { resolved: { type: "boolean" }, base: { type: "string" }, reason: { type: "string" } },
+};
+const shrinkBase = await agent(
+  [
+    `Resolve the milestone diff BASE for the git repo at "${projectDir}" (the branch-point of the current work). Run ONLY git, report JSON. Steps:`,
+    `1. Find the default branch tip. Try in order, using the first that resolves to a commit (cwd "${projectDir}"):`,
+    `   a. \`git -C "${projectDir}" rev-parse --verify --quiet origin/HEAD\` (then its symbolic target), else`,
+    `   b. \`git -C "${projectDir}" rev-parse --verify --quiet main\`, else`,
+    `   c. \`git -C "${projectDir}" rev-parse --verify --quiet master\`.`,
+    `2. Compute the merge-base of HEAD and that default tip: \`git -C "${projectDir}" merge-base HEAD <defaultTip>\`.`,
+    `3. If a merge-base commit is produced AND it differs from HEAD's own sha (there IS a diff to measure), return { "resolved": true, "base": "<merge-base-sha>" }.`,
+    `4. If NO default branch resolves, OR merge-base fails, OR merge-base === HEAD (nothing to measure), return { "resolved": false, "reason": "<short reason, e.g. no default branch / detached / merge-base===HEAD>" }.`,
+    `Do NOT do any other work. ONLY run git and report.`,
+  ].join("\n"),
+  { label: "m92:shrink-base", phase: "Synthesis", schema: SHRINK_BASE_SCHEMA, model: "haiku" }
+).catch((e) => ({ resolved: false, reason: `shrink-base agent error: ${e && e.message}` }));
+
+let shrink = null;
+let shrinkSkipReason = null;
+if (shrinkBase && shrinkBase.resolved && shrinkBase.base) {
+  const sm = await runShrinkMetric(projectDir, `${shrinkBase.base}..HEAD`, "m92:shrink-metric", "Synthesis");
+  if (sm.ok && sm.envelope && typeof sm.envelope.netLoc === "number" && typeof sm.envelope.leaner === "boolean") {
+    shrink = { netLoc: sm.envelope.netLoc, leaner: sm.envelope.leaner, insertions: sm.envelope.insertions, deletions: sm.envelope.deletions, filesAdded: sm.envelope.filesAdded, filesRemoved: sm.envelope.filesRemoved, filesModified: sm.envelope.filesModified };
+    log(`M92 shrink-metric: netLoc=${shrink.netLoc} leaner=${shrink.leaner} (+${shrink.insertions}/-${shrink.deletions}) — surfacing as the orthogonal leanness dimension`);
+  } else {
+    shrinkSkipReason = `shrink-metric CLI did not return a usable metric (exitCode=${sm.exitCode}) — SKIPPED, not fabricated`;
+    log(`M92 shrink-metric: SKIP — ${shrinkSkipReason}`);
+  }
+} else {
+  shrinkSkipReason = `diff base unavailable (${(shrinkBase && shrinkBase.reason) || "unknown"}) — shrink-metric SKIPPED, never fabricated`;
+  log(`M92 shrink-metric: SKIP — ${shrinkSkipReason}`);
+}
+
 phase("Synthesis");
 const synthesisPrompt = [
   `You are the synthesis agent. Three orthogonal validators have run.`,
@@ -710,7 +780,15 @@ const synthesisPrompt = [
   `- VERIFIED-WITH-WARNINGS if: Red Team GRUDGING-PASS, QA suite green, contracts compliant, AND any of: code-review ultra has "important" findings, OR skipUltra=true (reason: ${skipUltraReason || "(none — would have failed above)"}), OR QA shallowTests.length === 1 (single non-core).`,
   `- VERIFY-FAILED otherwise (Red Team FAIL, QA fail>0, contract violations>0, shallowTests ≥ 2 or in core paths).`,
   ``,
-  `Return JSON per VERDICT_SCHEMA with blockingFindings listing concrete things that must fix.`,
+  `**M92 SHRINK DIMENSION (ORTHOGONAL — do NOT fold into pass/fail):** a deterministic shrink-metric measured the milestone diff:`,
+  shrink
+    ? `    shrink = ${JSON.stringify({ netLoc: shrink.netLoc, leaner: shrink.leaner })}  (full: +${shrink.insertions}/-${shrink.deletions}, files +${shrink.filesAdded}/-${shrink.filesRemoved}/~${shrink.filesModified})`
+    : `    shrink = (SKIPPED — ${shrinkSkipReason}; report it as not-measured, NEVER fabricate a value)`,
+  shrink
+    ? `  Copy this measured shrink object VERBATIM into the "shrink" field of your output ({ "netLoc": ${shrink.netLoc}, "leaner": ${shrink.leaner} }). It is MEASURED — do not recompute or alter it. If leaner=true, explicitly ACKNOWLEDGE in the summary that the milestone made the codebase smaller (net-negative LOC) as a SUCCESS dimension, ORTHOGONAL to the correctness verdict — a VERIFIED-or-not correctness result and a leaner:true result are independent and BOTH reported.`
+    : `  OMIT the "shrink" field (the metric was skipped — say so in the summary; do NOT invent a netLoc/leaner).`,
+  ``,
+  `Return JSON per VERDICT_SCHEMA. Include blockingFindings listing concrete things that must fix${shrink ? ", and the measured shrink object" : ""}.`,
 ].join("\n");
 
 const verdict = await agent(synthesisPrompt, {
@@ -730,5 +808,8 @@ return {
   testDataPurge: td.envelope,
   guardMap: { discovery: guardMapDiscovery, results: guardMapResults },
   triad: triadResults,
+  // M92 D2 (keystone) — the measured leanness dimension, surfaced ALONGSIDE the
+  // overallVerdict enum (orthogonal; null + a reason when the diff base was unavailable).
+  shrink: shrink || { skipped: true, reason: shrinkSkipReason },
   verdict,
 };