@tekyzinc/gsd-t 4.7.11 → 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
 
@@ -66,6 +82,7 @@ These documents MUST be maintained and referenced throughout development:
 | **README** | `README.md` | Project overview, setup, features |
 | **Progress** | `.gsd-t/progress.md` | Current milestone/phase state + version |
 | **Contracts** | `.gsd-t/contracts/` | Interfaces between domains |
+| **PseudoCode** | `.gsd-t/pseudocode/PseudoCode-[Title].md` | Intention-first behavior map — the milestone source-of-truth (authored before the build; rippled when code/contract/schema changes) |
 | **Tech Debt** | `.gsd-t/techdebt.md` | Debt register from scans |
 
 ## The "No Re-Research" Rule
@@ -278,6 +295,7 @@ NEVER commit without this checklist. For each trigger that fired, do the action
 - **UI component interface changed** → `.gsd-t/contracts/component-contract.md`.
 - **New files/dirs** → owning domain's `scope.md`.
 - **Requirement implemented/changed** → `docs/requirements.md`.
+- **Behavior/intention changed vs. the signed-off pseudocode** → update the owning `PseudoCode-[Title].md` (the milestone source-of-truth) in the same pass; a supersede writes a `⚠ Divergence` flag.
 - **Component or data-flow changed** → `docs/architecture.md`.
 - **ANY document/script/code file modified** → timestamped `.gsd-t/progress.md` Decision Log entry (`- YYYY-MM-DD HH:MM: {what} — {result}`); covers every workflow command AND manual edits. Architectural decision → include rationale in that entry.
 - **Tech debt found/fixed** → `.gsd-t/techdebt.md`.

package/templates/PseudoCode-spec.md

@@ -0,0 +1,194 @@
+# {Title} — {one-line subject of this behavior map}
+
+**Pseudocode + intention for how {the subject} behaves, end to end.**
+Covers WHERE the system makes each decision, WHEN it refuses to, and how the
+result reaches every consumer. **{Scope line — what this is, and the one thing
+it deliberately does NOT do.}**
+
+> **⚠ {THE LOAD-BEARING DIRECTIVE} ({Author}, {date}).** {The single sentence a
+> reader must not miss — the WHY behind the whole map, stated as the user's
+> intention. Prose here is the USER's directive, never agent reasoning.}
+
+_Forward-looking behavior map for **{milestone / scope id}**. Not yet built —
+grounds itself in the EXISTING contracts it must respect:
+`{existing-contract-a}.md`, `{existing-contract-b}.md`, and the frozen
+`{Schema}` (`{field}` / `{field}` / `{field}`). Companion to
+`PseudoCode-{Other}.md`. See `{roadmap ref}` for the milestone scope._
+
+<!--
+  ─────────────────────────────────────────────────────────────────────────────
+  HOW TO USE THIS MOLD  (delete this comment block in the real instance)
+  ─────────────────────────────────────────────────────────────────────────────
+  • Name the instance PseudoCode-[Title].md where [Title] is the SUBJECT
+    (PseudoCode-PayPal.md), never a milestone id. Only THIS blank mold keeps the
+    `-spec` suffix.
+  • Author the TWO ALTITUDES in order:
+      1. HIGH-LEVEL APPROACH  — what / why / when, the actors, a one-breath
+         summary table. NO field-level detail. SIGN THIS OFF FIRST.
+      2. DETAILED             — the full numbered `##` section set below, at
+         exemplar granularity (one section per decision boundary).
+  • Every section carries the FIVE SECTION ELEMENTS (see the contract §1):
+      Intention prose · Mechanism pseudocode · one-breath summary ·
+      [RULE] guard map · ⚠ Divergence flags · Appendix.
+  • Each `> **Intention.**` prose block sits ABOVE its fenced pseudocode and is
+    dated + attributed; the prose is the USER's WHY, never agent reasoning.
+  • The Mechanism block grounds in EXISTING contracts/schema and DEFERS concrete
+    identifiers to plan-time-against-the-real-schema.
+  • Guard map: render EVERY invariant as a one-line `[RULE] <invariant>` (or the
+    tagged `<invariant> [RULE — <tag>]` form). One marker = one rule.
+  • Divergence: wherever a NEW intention supersedes shipped code, write an
+    explicit `⚠ Divergence:` flag. Keep = no flag.
+  • Cite each implementing plan task back with:
+        **PseudoCode-Section**: {Title}#<github-slug-of-the-## heading>
+  Grammars are owned by the contract:
+  `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`
+  (§2 guard-map, §3 section-citation, §4 divergence). Do NOT re-derive them here.
+  ─────────────────────────────────────────────────────────────────────────────
+-->
+
+---
+
+<!-- ═══════════════ ALTITUDE 1 — HIGH-LEVEL APPROACH (sign off FIRST) ═══════════════ -->
+
+## The one {call / decision}, in one breath
+
+> **High-Level Approach ({Author}, {date}).** {What this does, why, and when —
+> the actors and the single decision, in plain language. No field-level detail.
+> This altitude is signed off BEFORE the Detailed sections below are written.}
+
+| {Call / decision} | Lives in | Decides | Runs only when… |
+|-------------------|----------|---------|-----------------|
+| **{The call}** | **{realm — Server / Extension / …}** | {what it turns the input into} | {the precondition that triggers it} |
+| **{The read / fallback}** | **{realm}** | {the question it answers} | {seller- / event-initiated trigger} |
+
+> **SCOPE ({Author}, {date}).** {The deliberate OUT-of-scope boundary — what this
+> map does NOT do. State the one status / call / surface it touches and the ones
+> it refuses to touch. This keeps the Detailed sections honest.}
+
+---
+
+<!-- ═══════════════ ALTITUDE 2 — DETAILED (exemplar granularity) ═══════════════ -->
+
+## 0. Where this picks up — {precondition / what exists before}
+
+> **Intention ({Author}, {date}).** {What state the system is in when this map
+> begins — the precondition. If this SUPERSEDES a shipped model, say so here and
+> add the ⚠ Divergence flag below.}
+
+```text
+PRECONDITION:
+  {The exact starting state — what is loaded / grouped / present, and what is
+   deliberately NOT persisted yet.}
+```
+
+> ⚠ **Divergence from shipped {what} (plan-time reconcile):** {what the shipped
+> code does today} vs. {what THIS intention does instead}. {What becomes dead
+> code / what is reused.} Flag for the {milestone} plan.
+> *(Keep = delete this flag. Supersede = keep it, per contract §4.)*
+
+---
+
+## 1. {First boundary} — {the trigger → the actor that owns it}
+
+> **Intention.** {WHY this step exists and what the user wants it to do — the
+> directive. One short paragraph, the user's voice.}
+
+```text
+{ACTOR}  on {trigger}:
+    {step}
+    {the call / the guard}
+    on {outcome}:  {what happens}
+    on {failure}:  {the safe fallback — never a crash}
+```
+
+---
+
+## 2. {Second boundary} — `{the operation}`  (★ {why this one is load-bearing})
+
+> **Intention.** {The WHY. Name the one invariant this section exists to protect
+> — e.g. "every guard makes a double-click HARMLESS".}
+
+```text
+{operationName}({inputs}):
+
+    # ── GATE 1 — {what it validates} (RULE) ────────────────────────────────
+    # Intention: {why this gate exists, in the user's voice}.
+    {load / lock}
+    if {precondition fails}:   → {status / error}   # {what it protects}
+
+    # ── GATE 2 — {backstop} (RULE, backstop) ───────────────────────────────
+    # Intention: {why — name it a backstop if upstream already blocks it}.
+    if {impossible condition}:   → {status}
+
+    # ── STEP 3 — {the side-effecting call} ─────────────────────  ★ {marker}
+    # Intention: {what crosses the boundary and what is deferred to real schema}.
+    {the call}                                   # defer concrete ids to plan-time
+
+    # ── STEP 4 — PERSIST + {atomic effect} (RULE, one tx) ──────────────────
+    # Intention: {the record is born / the state flips — atomically}.
+    in ONE tx:
+        {write}
+        {flip state}
+    return {success shape}
+
+    # ── FAILURE — never half-{do the thing} (RULE) ─────────────────────────
+    # Intention: a failed {op} persists NOTHING — safe retry.
+    on {failure} (any point):  nothing persisted ; → {status}
+```
+
+---
+
+## 3. {Further boundaries as needed} — {one `##` section per decision}
+
+> **Intention.** {Add as many numbered `##` sections as the subject has distinct
+> decision boundaries — match the exemplars' granularity, one section per real
+> decision, not one giant section.}
+
+```text
+{the mechanism for this boundary}
+```
+
+---
+
+## {N}. {Subject}-safety map — every guard, as a one-line [RULE]
+
+```text
+GATE: {condition} → {status}                     [RULE] {the invariant in one line}
+GATE: {lock / serialize}                          [RULE] {what it prevents}
+{deterministic guard}                             [RULE — {tag}] {invariant, tagged form}
+{never-do-this}                                   [RULE] {the prohibition}
+{born / set at this exact point}                  [RULE] {the lifecycle invariant}
+on {failure}: persist NOTHING                     [RULE] {the safe-failure invariant}
+```
+
+**{One paragraph restating the whole safety story in prose: the record is born
+WHEN, the lock means WHAT, the one thing that can never happen, and why every
+retry / double-action is harmless.}**
+
+---
+
+## {Optional} — {ONE STORE / shared-state / known-gaps notes}
+
+> {Optional sections the exemplars carry: a shared-store note, a "Known gaps /
+> status (as of {version})" list. Include only if the subject has them.}
+
+---
+
+## Appendix — Raw pseudocode (no intention comments)
+
+```text
+# ════════════════════════════════════════════════════════════════════════════
+# {REALM A} — {what it covers}
+# ════════════════════════════════════════════════════════════════════════════
+{the §1–§N mechanism, intention prose STRIPPED — the build's quick-reference}
+
+# ════════════════════════════════════════════════════════════════════════════
+# {REALM B} — {what it covers}
+# ════════════════════════════════════════════════════════════════════════════
+{operationName}({inputs}):
+    {guard}                                       # {one-line reason}
+    {the call}                                    # ★ {the load-bearing call}
+    tx: {write} ; {flip state}
+    return {success}
+    on fail: persist NOTHING ; → {status}         # safe retry
+```

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/keep-or-supersede-subagent.md

@@ -0,0 +1,61 @@
+# Keep-or-Supersede Subagent Prompt — Inherited Shipped-Code Forcing Protocol
+
+<!-- M87 D3 — the forcing keep-or-supersede protocol. PROSE PROTOCOL: its reliability
+     is bounded by how FORCING this prompt is, NOT by a deterministic gate. The
+     deterministic parseDivergence()/formatDivergence() grammar round-trip is M88.
+     Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §4. -->
+
+You are the **keep-or-supersede** agent. Your sole job: for **every model inherited from shipped code** that the milestone is about to encode into its intention-first `PseudoCode-[Title].md`, FORCE an explicit **keep-or-supersede** decision from the user — and on every supersede, WRITE a `⚠ Divergence` flag into the doc. You write ZERO feature code.
+
+## Why this exists (the real failure this prevents)
+
+A real incident: a PayPal-first web app inherited a **stored-draft over-trust** model from shipped code — it assumed a draft already persisted on the PayPal server was still valid, and re-confirmed deletion against that stale draft instead of re-checking the live state. The shipped model was silently carried forward as if it were intention, and the bug shipped with it. The rescue was to STOP at each inherited model and ask the user, out loud: *"do we keep this behavior, or does a new intention supersede it?"* — and to RECORD every supersede so the divergence from shipped code is never silent.
+
+This protocol bakes that rescue into the methodology. Inherited code is a HYPOTHESIS about intent, never a proven intent. Encoding it without asking is the deadly pattern.
+
+## The Forcing Rule (non-negotiable)
+
+**Never encode an inherited shipped-code model without an explicit keep-or-supersede decision.** "It already works this way" is NOT a keep decision — it is the un-asked assumption this protocol exists to break. For each inherited model:
+
+1. **Surface it plainly.** State the inherited behavior in one jargon-free sentence: what the shipped code currently does, where it lives (the file/realm), and the model it embeds. Lead with a short concrete example of when that behavior bites, then map it to the code in one line — so the user can decide with understanding, not rubber-stamp.
+2. **ASK, do not assume.** Present exactly two choices and require a decision:
+   - **KEEP** — the shipped behavior IS the intended behavior. The doc encodes it as-is. **No flag is written.**
+   - **SUPERSEDE** — a new intention replaces the shipped behavior. The doc encodes the NEW intention, and a `⚠ Divergence` flag is WRITTEN (see below).
+3. **The doc prose is the USER'S intention, never your reasoning.** When you write the superseding intention, write what the USER decided and why, in their framing — not your justification for it.
+4. **Default is NOT silent keep.** If the user has not decided, you do NOT proceed by silently keeping. You ASK. An un-asked inherited model is an open question, never a default-on behavior (`feedback_no_silent_degradation`, `feedback_unproven_assumption_stop_and_research`).
+
+## On SUPERSEDE — write the Divergence flag (mandatory)
+
+Every **supersede** WRITES a `⚠ Divergence` flag into `PseudoCode-[Title].md`, using the §4 grammar shape exactly:
+
+```
+⚠ Divergence: <RULE-ID or section> — supersedes shipped <what>. Reason: <user intention>.
+```
+
+- `<RULE-ID or section>` — the guard-map RULE-ID or the doc section the divergence attaches to.
+- `<what>` — the shipped behavior being superseded, in one phrase.
+- `<user intention>` — WHY, in the user's framing (the new intention that replaces it).
+
+**KEEP writes no flag.** One supersede → exactly one flag. The flag is captured IN the doc so the divergence from shipped code is an explicit, visible artifact — never silent.
+
+> **M87/M88 split.** In M87 this flag is WRITTEN by this prose protocol (the ASK + the write). The DETERMINISTIC `parseDivergence()` / `formatDivergence()` round-trip — making the divergence COUNT a code-checkable, byte-stable artifact that can feed the guard-map rule set — is **M88** (backlog #35). The §4 grammar is the spec for both; only the round-trip IMPLEMENTATION is deferred. Here, your obligation is: ask, and on supersede, write a well-formed flag.
+
+## What to do (step by step)
+
+1. **Enumerate inherited models.** From the brief / requirements / the shipped code being carried forward, list every behavioral model the milestone would inherit. If `$BRIEF_PATH` is set, read it first (the ≤2,500-token snapshot) before re-walking the repo.
+2. **For each inherited model, run the Forcing Rule above** — surface it, ASK keep-or-supersede, get the decision.
+3. **On KEEP:** encode the behavior as-is in the doc. No flag.
+4. **On SUPERSEDE:** encode the NEW intention (in the user's framing) and WRITE the `⚠ Divergence` flag in §4 grammar.
+5. **Report** the full keep/supersede ledger: every inherited model, the decision, and for each supersede the exact flag written.
+
+## Report Format
+
+```
+Inherited models reviewed: N
+- <model>: KEEP — encoded as-is.
+- <model>: SUPERSEDE — flag written: "⚠ Divergence: <ref> — supersedes shipped <what>. Reason: <intention>."
+...
+Divergence flags written: M  (= number of supersedes)
+```
+
+If ANY inherited model was encoded WITHOUT an explicit keep-or-supersede decision, that is a protocol FAILURE — report it as such; do not mark the work complete.

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.