@tekyzinc/gsd-t 5.4.11 → 5.5.11

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.5.11] - 2026-07-29
+
+### Fixed — the new style gate would have failed 27 untouched documents in three projects
+
+Caught by running the gate live in a downstream project immediately after propagation rather than trusting the "copied 1 bin tool(s)" report. v5.5.10 shipped the gate to all 33 registered projects, but the grandfather list that exempts pre-v1.2.0 documents existed only in the GSD-T repo. binvoice (19 documents), NiceNote (6) and IssueRecorder (2) had none — so the next `gsd-t-verify` run in those projects would have failed on documents nobody touched, written to a then-valid standard.
+
+The gate now establishes its own starting line: on the `--dir` path, when the list file is absent and the directory already holds documents, it writes the list once from the existing set and reports `seeded: { reason: "seeded-pre-existing", count, docs }`.
+
+This is **not a fallback** — it masks no failure and continues past none; it defines where the gate begins. Three properties keep it honest: written **once** (a self-re-seeding list would silently absolve every newly-drifted document, which is the banned behavior), keyed on the file being absent, and always surfaced naming every document covered. A document created after the seed is gated normally; a single `--doc` call never seeds; an un-writable directory returns exit 64 with the reason rather than a silent mass-pass or mass-fail.
+
+- `bin/gsd-t-pseudocode-style.cjs`: `seedGrandfatherList()` + envelope `seeded` field.
+- `test/pseudocode-style-gate.test.js`: 4 new tests (15 → 19) — seed happens, seed never re-runs, `--doc` never seeds, un-writable directory exits 64.
+- `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`: §1.1.5 documents the seed and why it is not a fallback.
+
+Verified live: binvoice's 19 documents now report `exitCode 0`, 19 seeded, 0 violations. Suite 3052/0/13-skip.
+
+## [5.5.10] - 2026-07-29
+
+### Added — PseudoCode style is governed: the flow IS the document
+
+A PseudoCode document exists for one job — letting the user approve **direction before code**. The corpus had drifted into transliterated source (`loadStore(storePath):`, `spawnSync`, `MODULE_NOT_FOUND`, `→ 409`) buried under paragraphs of preamble, which is a document the reader must translate line-by-line. Root cause: contract §1 governed what a doc *contains* (the five section elements) and nothing governed how it *reads*.
+
+New contract §1.1 fixes the readable half with two rules, not one:
+
+- **Shape** — the flow is a nested decision tree in plain English: 2-space indent per level, one thing per line, a question line ending `:` answered by indented `Yes:` / `No:` (or named outcomes) beneath it. Banned in the flow: function-call syntax, code keywords (`if`/`return`/`throw`/`catch`/`tx:`), bare status codes or SCREAMING_SNAKE constants, and any paragraph.
+- **Words** — the technical term is *kept* and rides **alongside** plain words rather than replacing them: plain first, term in parentheses, glossed once per `##` section — `Zoom's webhook (its automatic ping to us) arrives at /zoom/events`. Concrete real names (Zoom, the Save button, the invoices table) need no gloss; abstract category-nouns (webhook, payload, endpoint, token, cache) do.
+
+Document shape is now `# Title` → one sentence of purpose → the flow → `---` → everything else. The `[RULE]` guard map, divergence flags, Six-Stage answers, and every file/function pointer move below the divider; code identifiers never appear in the flow.
+
+- `bin/gsd-t-pseudocode-style.cjs`: NEW deterministic gate (exit 0 clean / 4 violations / 64 bad input). Checks the flow block only, so the §2 `[RULE]` grammar is never style-checked and the two gates cannot fight. Added to both `GLOBAL_BIN_TOOLS` and `PROJECT_BIN_TOOLS`.
+- `bin/gsd-t.js`: new `pseudocode-style` subcommand dispatch.
+- `templates/workflows/gsd-t-verify.workflow.js`: gate wired FAIL-blocking beside the guard-map gate — no discovery agent needed, it globs the §7 directory itself.
+- `test/pseudocode-style-gate.test.js`: NEW, 15 tests written as a discrimination bar — every banned form must fail individually (9 distinct violations fire on a doctored doc), the converted reference must pass, the below-divider guard map must be exempt, and a doc with no flow block fails rather than passing vacuously.
+- `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`: v1.1.5 → **v1.2.0** (additive; §2/§3/§4/§5/§7 grammars untouched).
+- `templates/PseudoCode-spec.md`: mold rewritten flow-first.
+- `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`: converted as the worked reference — same behavior, same six `[RULE]`s, only the reading changed.
+- Authoring instructions rippled to all five producing sites: `commands/gsd-t-architect.md`, `commands/gsd-t-milestone.md`, `commands/gsd-t-doc-ripple.md`, `templates/workflows/gsd-t-phase.workflow.js` (2 spots), `templates/prompts/keep-or-supersede-subagent.md`.
+- `templates/CLAUDE-global.md`: new § PseudoCode Style (mirrored to the live `~/.claude/CLAUDE.md`).
+- `.gsd-t/contracts/architects-oversight-contract.md`: A-FAIL-1 no longer describes the old CURRENT/PROPOSED style.
+- `.gsd-t/contracts/graph-metrics-contract.md`: `doMetrics` line citation 4915 → 4927 (the new dispatch case shifted `bin/gsd-t.js`; the existing M99 contract-line test caught it).
+
+The seven pre-v1.2.0 documents are grandfathered via `.gsd-t/pseudocode/.style-grandfathered` and reported as a logged skip **with a named reason**, never a silent pass. Removing a name is how a document opts into the gate. Suite 3048/0/13-skip.
+
 ## [5.4.11] - 2026-07-27
 
 ### Fixed — schema-id gate never reached projects (propagation gap)

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.4.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.5.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-pseudocode-style.cjs

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-pseudocode-style — the §1.1 flow-line style gate.
+ *
+ * Contract: .gsd-t/contracts/pseudocode-source-of-truth-contract.md §1.1
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * §1 governed what a PseudoCode doc CONTAINS; nothing governed how it READS.
+ * The corpus drifted into transliterated source code (`loadStore(storePath):`,
+ * `spawnSync`, `MODULE_NOT_FOUND`, `→ 409`) wrapped in paragraphs of preamble —
+ * a document the reader has to translate line-by-line, which defeats its only
+ * purpose (approving DIRECTION before code). This gate holds the readable half:
+ * the flow reads as a nested decision tree in plain English, and a technical
+ * term rides ALONGSIDE plain words in parentheses instead of replacing them.
+ *
+ * SCOPE — the flow block only (§1.1.5)
+ * ------------------------------------
+ * Checks fenced blocks ABOVE the first `---` divider, plus the flow blocks under
+ * `## What it does today` / `## What changes`. Everything below the divider is
+ * exempt: that is where the §2 `[RULE]` guard map, divergence flags, Six-Stage
+ * answers, and file/function pointers legitimately live. So this gate can never
+ * fight the §2 grammar.
+ *
+ * Deterministic code, zero LLM judgment (same split as §2: an LLM may PRODUCE a
+ * doc, code GATES it). Never throws — bad input returns exitCode 64.
+ *
+ * Input:  --doc <path> [--json]   |   --dir <pseudocode dir> [--json]
+ * Output: JSON envelope { ok, exitCode, violations: [...] }
+ * Exit:   0 clean · 4 style violations · 64 bad input
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/** Basename-per-line opt-out list for docs authored before contract v1.2.0. */
+const GRANDFATHER_FILE = ".style-grandfathered";
+
+/**
+ * Category-nouns that force a mental translation when they appear bare.
+ * A term here must carry a parenthetical gloss on FIRST use within its `##`
+ * section (§1.1.3). Concrete real names (Zoom, /zoom/events, the invoices
+ * table) are deliberately absent — they are specific, so nothing must be
+ * decoded.
+ */
+const JARGON_TERMS = [
+  "webhook", "payload", "endpoint", "handler", "middleware", "token",
+  "cache", "mutex", "idempotent", "serialize", "deserialize", "marshal",
+  "envelope", "socket", "daemon", "cron", "regex", "schema", "hash",
+];
+
+/** Code keywords that mean the author transliterated source instead of behavior. */
+const CODE_KEYWORDS = [
+  "return", "throw", "catch", "finally", "await", "async", "yield",
+  "const", "let", "var", "function", "class", "import", "export",
+  "elif", "endif", "null", "undefined", "void",
+];
+
+/**
+ * Split a doc into the region the gate checks and the exempt region.
+ * @param {string} text
+ * @returns {{ flowRegion: string, flowStartLine: number, extraRegions: Array<{text:string,startLine:number,section:string}> }}
+ */
+function splitRegions(text) {
+  const lines = text.split("\n");
+
+  // The header region ends at the first `---` divider that sits OUTSIDE a fence.
+  let inFence = false;
+  let dividerIdx = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*```/.test(l)) { inFence = !inFence; continue; }
+    if (!inFence && /^---\s*$/.test(l)) { dividerIdx = i; break; }
+  }
+
+  const flowRegion = lines.slice(0, dividerIdx).join("\n");
+
+  // Below the divider, only the two named before/after flow sections are checked.
+  const extraRegions = [];
+  const FLOW_SECTION = /^##\s+(What it does today|What changes)\s*$/i;
+  let cur = null;
+  inFence = false;
+  for (let i = dividerIdx; i < lines.length; i++) {
+    const l = lines[i];
+    if (/^\s*```/.test(l)) { inFence = !inFence; if (cur) cur.lines.push(l); continue; }
+    if (!inFence && /^##\s+/.test(l)) {
+      if (cur) extraRegions.push({ text: cur.lines.join("\n"), startLine: cur.startLine, section: cur.section });
+      const m = l.match(FLOW_SECTION);
+      cur = m ? { lines: [], startLine: i + 2, section: m[1] } : null;
+      continue;
+    }
+    if (cur) cur.lines.push(l);
+  }
+  if (cur) extraRegions.push({ text: cur.lines.join("\n"), startLine: cur.startLine, section: cur.section });
+
+  return { flowRegion, flowStartLine: 1, extraRegions };
+}
+
+/**
+ * Pull the fenced code blocks out of a region — the flow lines live inside them.
+ * @returns {Array<{lines: string[], startLine: number}>}
+ */
+function fencedBlocks(regionText, regionStartLine) {
+  const out = [];
+  const lines = regionText.split("\n");
+  let cur = null;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*```/.test(lines[i])) {
+      if (cur) { out.push(cur); cur = null; }
+      else cur = { lines: [], startLine: regionStartLine + i + 1 };
+      continue;
+    }
+    if (cur) cur.lines.push(lines[i]);
+  }
+  if (cur) out.push(cur); // unterminated fence — still check what we got
+  return out;
+}
+
+/** Strip parenthetical glosses and trailing `# comment` before keyword scanning. */
+function stripGlosses(line) {
+  return line.replace(/\([^)]*\)/g, " ").replace(/#.*$/, " ");
+}
+
+/**
+ * Check one flow line for the §1.1.2 banned forms.
+ * @returns {string[]} rule names broken
+ */
+function checkLine(rawLine, glossedTerms) {
+  const broken = [];
+  const line = rawLine.trimEnd();
+  if (!line.trim()) return broken;
+
+  const bare = stripGlosses(line);
+
+  // Function-call syntax: `name(...)` or `obj.method(...)`.
+  if (/[A-Za-z_][A-Za-z0-9_.]*\s*\([^)]*\)\s*:?/.test(line.replace(/\([^)]*\)/g, (m, off) => {
+    // A parenthetical gloss follows a space and starts with a lowercase word or
+    // "the"/"its" — that is prose, not a call. Keep call-shaped ones for the test.
+    const before = line.slice(0, off);
+    return /[A-Za-z0-9_.]$/.test(before) ? m : " ";
+  }))) {
+    broken.push("no-function-call-syntax");
+  }
+
+  // Code keywords as standalone words.
+  for (const kw of CODE_KEYWORDS) {
+    if (new RegExp(`(^|[^A-Za-z0-9_])${kw}([^A-Za-z0-9_]|$)`, "i").test(bare)) {
+      broken.push(`no-code-keyword:${kw}`);
+      break;
+    }
+  }
+  // `if`/`else` only count when they open a clause — "Is it valid:" is the form we want.
+  if (/(^|[^A-Za-z0-9_])(if|else)\s/i.test(bare)) broken.push("no-code-keyword:if/else");
+  if (/(^|\s)tx\s*:/i.test(bare)) broken.push("no-code-keyword:tx");
+
+  // Arrow-to-status and SCREAMING_SNAKE error constants, unless glossed.
+  if (/→\s*\d{3}\b/.test(bare) || /\b(?:HTTP\s*)?\b[45]\d\d\b(?=\s*$)/.test(bare.trim())) {
+    broken.push("no-bare-status-code");
+  }
+  if (/\b[A-Z][A-Z0-9]*_[A-Z0-9_]{2,}\b/.test(bare)) broken.push("no-bare-error-constant");
+
+  // Un-glossed category-noun on first use in this section.
+  for (const term of JARGON_TERMS) {
+    const re = new RegExp(`(^|[^A-Za-z])${term}s?([^A-Za-z]|$)`, "i");
+    if (!re.test(line)) continue;
+    const hasGloss = new RegExp(`${term}s?\\s*\\([^)]+\\)`, "i").test(line);
+    if (hasGloss) { glossedTerms.add(term); continue; }
+    if (!glossedTerms.has(term)) broken.push(`gloss-on-first-use:${term}`);
+  }
+
+  return broken;
+}
+
+/**
+ * Prose-paragraph detection: a flow line with no question colon, no outcome
+ * prefix, and sentence-length wording is a paragraph the user asked to remove.
+ */
+function looksLikeParagraph(line) {
+  const t = line.trim();
+  if (t.length < 90) return false;
+  if (/:\s*$/.test(t)) return false;                       // question line
+  if (/^(Yes|No|[A-Z][A-Za-z ]{0,20}):/.test(t)) return false; // outcome line
+  return /[.!?]\s+[A-Z]/.test(t);                          // 2+ sentences
+}
+
+/**
+ * Gate one doc.
+ * @returns {{ ok, exitCode, doc, violations, skipped?, reason? }}
+ */
+function gateDoc(docPath, grandfathered) {
+  let text;
+  try {
+    text = fs.readFileSync(docPath, "utf8");
+  } catch (e) {
+    return { ok: false, exitCode: 64, doc: docPath, reason: `cannot read doc: ${e && e.message}`, violations: [] };
+  }
+
+  const base = path.basename(docPath);
+  if (grandfathered.has(base)) {
+    // A logged skip WITH A REASON — never a silent pass (feedback_no_silent_degradation).
+    return { ok: true, exitCode: 0, doc: docPath, skipped: true, reason: "grandfathered", violations: [] };
+  }
+
+  const { flowRegion, flowStartLine, extraRegions } = splitRegions(text);
+  const violations = [];
+
+  const regions = [
+    { blocks: fencedBlocks(flowRegion, flowStartLine - 1), section: "(flow)" },
+    ...extraRegions.map((r) => ({ blocks: fencedBlocks(r.text, r.startLine - 1), section: r.section })),
+  ];
+
+  let sawAnyFlowLine = false;
+  for (const region of regions) {
+    // Gloss scope is the `##` section (§1.1.3) — reset per region.
+    const glossedTerms = new Set();
+    for (const block of region.blocks) {
+      for (let i = 0; i < block.lines.length; i++) {
+        const raw = block.lines[i];
+        const lineNo = block.startLine + i;
+        if (raw.trim()) sawAnyFlowLine = true;
+        for (const rule of checkLine(raw, glossedTerms)) {
+          violations.push({ doc: docPath, line: lineNo, section: region.section, rule, text: raw.trim().slice(0, 120) });
+        }
+        if (looksLikeParagraph(raw)) {
+          violations.push({ doc: docPath, line: lineNo, section: region.section, rule: "no-paragraph-in-flow", text: raw.trim().slice(0, 120) });
+        }
+      }
+    }
+  }
+
+  // Non-vacuity: a doc with no flow lines at all cannot pass by having nothing
+  // to check (the §2/§3 vacuous-pass class).
+  if (!sawAnyFlowLine) {
+    return {
+      ok: false, exitCode: 4, doc: docPath, violations: [
+        { doc: docPath, line: 1, section: "(flow)", rule: "no-flow-block", text: "no fenced flow block found above the first --- divider" },
+      ],
+    };
+  }
+
+  return { ok: violations.length === 0, exitCode: violations.length === 0 ? 0 : 4, doc: docPath, violations };
+}
+
+/** Read the grandfather list from the doc's own directory. */
+function loadGrandfathered(dir) {
+  const out = new Set();
+  try {
+    const raw = fs.readFileSync(path.join(dir, GRANDFATHER_FILE), "utf8");
+    for (const l of raw.split("\n")) {
+      const t = l.trim();
+      if (t && !t.startsWith("#")) out.add(t);
+    }
+  } catch { /* absent list = nothing grandfathered (see seedGrandfatherList) */ }
+  return out;
+}
+
+/**
+ * First-run seed for a project that already had PseudoCode docs before this gate
+ * existed.
+ *
+ * WHY THIS IS NOT A FALLBACK (No-Fallback-Ever doctrine):
+ * this does not continue past a failure or mask one. It establishes the gate's
+ * STARTING LINE. The gate governs docs authored under contract §1.1; docs that
+ * predate it were written to a different (then-valid) standard, and retroactively
+ * failing them would make an unrelated verify run fail in a downstream project for
+ * work nobody touched. That is a false failure, not a caught defect.
+ *
+ * The seed is: WRITTEN ONCE (never rewritten — a list that re-seeded itself would
+ * silently absolve every newly-drifted doc, which IS the banned behavior), keyed on
+ * the list file being ABSENT, and always SURFACED with reason "seeded-pre-existing"
+ * naming every doc it covers. A doc created AFTER the seed is gated normally.
+ *
+ * @returns {{ seeded: boolean, names: string[], error?: string }}
+ */
+function seedGrandfatherList(dir, docBasenames) {
+  const listPath = path.join(dir, GRANDFATHER_FILE);
+  if (fs.existsSync(listPath)) return { seeded: false, names: [] };
+  if (docBasenames.length === 0) return { seeded: false, names: [] };
+
+  const body = [
+    "# Docs that predate the §1.1 flow-line style gate (contract v1.2.0).",
+    "# Seeded automatically on this gate's FIRST run in this project, so pre-existing",
+    "# docs are not retroactively failed. Each is reported as a logged skip WITH A",
+    "# REASON — never a silent pass.",
+    "#",
+    "# This file is written ONCE and never re-seeded: a doc created after this point",
+    "# is gated normally. Removing a name here is how a doc opts INTO the gate —",
+    "# convert it to the §1.1 flow style in the same change.",
+    ...docBasenames,
+    "",
+  ].join("\n");
+
+  try {
+    fs.writeFileSync(listPath, body, "utf8");
+  } catch (e) {
+    // Cannot write (read-only checkout, permissions) — surface it, do NOT
+    // silently fail 20 docs and do NOT silently pass them either.
+    return { seeded: false, names: [], error: `cannot seed ${GRANDFATHER_FILE}: ${e && e.message}` };
+  }
+  return { seeded: true, names: docBasenames.slice() };
+}
+
+/**
+ * Run the gate over one doc or a whole directory (§7 discovery glob).
+ * Never throws.
+ */
+function run({ doc, dir }) {
+  if (!doc && !dir) {
+    return { ok: false, exitCode: 64, reason: "missing --doc and/or --dir", violations: [] };
+  }
+
+  const docs = [];
+  if (doc) docs.push(doc);
+  if (dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch (e) {
+      return { ok: false, exitCode: 64, reason: `cannot read dir: ${e && e.message}`, violations: [] };
+    }
+    for (const e of entries) {
+      if (/^PseudoCode-.*\.md$/.test(e) && e !== "PseudoCode-spec.md") docs.push(path.join(dir, e));
+    }
+    if (docs.length === 0) {
+      // Legitimately nothing to gate — surfaced, not silent (§7 pairing outcomes).
+      return { ok: true, exitCode: 0, docsChecked: 0, skips: [{ reason: "no-pseudocode-docs" }], violations: [] };
+    }
+  }
+
+  // First-run seed: a project whose docs predate this gate gets its starting line
+  // established once, surfaced with a reason. Only on the --dir path (the whole-set
+  // view); a single --doc call never seeds.
+  let seedInfo = null;
+  if (dir) {
+    seedInfo = seedGrandfatherList(dir, docs.map((d) => path.basename(d)).sort());
+    if (seedInfo.error) {
+      return { ok: false, exitCode: 64, reason: seedInfo.error, violations: [] };
+    }
+  }
+
+  const results = [];
+  const violations = [];
+  const skips = [];
+  let worstExit = 0;
+  for (const d of docs) {
+    const r = gateDoc(d, loadGrandfathered(path.dirname(d)));
+    results.push({ doc: d, ok: r.ok, exitCode: r.exitCode, skipped: !!r.skipped, reason: r.reason });
+    if (r.skipped) skips.push({ doc: d, reason: r.reason });
+    for (const v of r.violations) violations.push(v);
+    if (r.exitCode > worstExit) worstExit = r.exitCode;
+  }
+
+  const envelope = {
+    ok: worstExit === 0,
+    exitCode: worstExit,
+    docsChecked: docs.length,
+    results,
+    skips,
+    violations,
+  };
+  if (seedInfo && seedInfo.seeded) {
+    // Surfaced, never silent: name the migration and every doc it covers.
+    envelope.seeded = { reason: "seeded-pre-existing", count: seedInfo.names.length, docs: seedInfo.names };
+  }
+  return envelope;
+}
+
+function parseArgs(argv) {
+  const o = { doc: null, dir: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") o.help = true;
+    else if (a === "--doc") o.doc = argv[++i];
+    else if (a === "--dir") o.dir = argv[++i];
+    else if (a === "--json") { /* JSON is the only output */ }
+  }
+  return o;
+}
+
+const HELP = `Usage: gsd-t pseudocode-style (--doc <PseudoCode-[Title].md> | --dir <dir>) [--json]
+
+Gates the §1.1 flow-line style of a PseudoCode doc: the flow reads as a nested
+decision tree in plain English, technical terms ride alongside plain words in
+parentheses, and code identifiers stay below the first --- divider.
+
+  --doc PATH   gate one doc.
+  --dir PATH   gate every PseudoCode-*.md in a directory (§7 discovery).
+
+Exit: 0 clean · 4 style violations · 64 bad input.
+Pre-v1.2.0 docs listed in <dir>/${GRANDFATHER_FILE} are skipped WITH a reason.`;
+
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.help) { process.stdout.write(HELP + "\n"); process.exit(0); }
+  let res;
+  try {
+    res = run(o);
+  } catch (e) {
+    res = { ok: false, exitCode: 64, reason: `gate-error: ${e && e.message}`, violations: [] };
+  }
+  process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+  process.exit(res.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { run, gateDoc, checkLine, splitRegions, fencedBlocks, looksLikeParagraph, JARGON_TERMS, CODE_KEYWORDS };

package/bin/gsd-t.js

@@ -1563,6 +1563,12 @@ const GLOBAL_BIN_TOOLS = [
   // this by absolute path, so it MUST ship wherever the verify gate ships or the
   // schema-id check throws ENOENT. Same class as the M99 store-resolver omission below.
   "gsd-t-schema-id-check.cjs",
+  // v5.5.10 — PseudoCode §1.1 flow-line style gate (contract v1.2.0). The verify
+  // workflow fires it on the same doc set as the guard-map gate, so it must ship
+  // wherever verify ships. Also in PROJECT_BIN_TOOLS below — a tool wired into a
+  // caller but absent from BOTH lists is dead in every project
+  // ([[project_global_bin_propagation_gap]], 4 prior occurrences).
+  "gsd-t-pseudocode-style.cjs",
 ];
 
 function installGlobalBinTools() {
@@ -2979,6 +2985,12 @@ const PROJECT_BIN_TOOLS = [
   // divergence-grammar = §4 parse/format round-trip (G4).
   "gsd-t-guard-map.cjs", "gsd-t-guard-map-derive.cjs", "gsd-t-milestone-state.cjs",
   "gsd-t-rule-consume.cjs", "gsd-t-divergence-grammar.cjs",
+  // Contract v1.2.0 (2026-07-29) — the §1.1 flow-line STYLE gate, sibling of the
+  // guard-map gate above. guard-map holds what a PseudoCode doc CONTAINS; this
+  // holds how it READS (nested decision tree in plain English, technical terms
+  // glossed alongside, code identifiers below the divider). Propagated so the
+  // verify workflow's project-local runCli resolves it downstream.
+  "gsd-t-pseudocode-style.cjs",
   // M93 — jargon-gloss lint for written docs (the file surface the brevity-guard
   // Stop hook can't reach). Propagated so a project's doc checks can invoke it.
   "gsd-t-jargon-lint.cjs",
@@ -5328,6 +5340,21 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "pseudocode-style": {
+      // Contract v1.2.0 §1.1 — `gsd-t pseudocode-style (--doc <f> | --dir <d>)` thin
+      // dispatcher to the PseudoCode flow-line STYLE gate. Sibling of `guard-map`:
+      // that one gates what a doc CONTAINS, this one gates how it READS.
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-pseudocode-style.cjs");
+      if (!require("node:fs").existsSync(js)) {
+        error(`gsd-t-pseudocode-style.cjs not found at ${js} — reinstall GSD-T (contract v1.2.0 §1.1)`);
+        process.exit(1);
+      }
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "architectural-trigger": {
       // M90 D1 — `gsd-t architectural-trigger <subcommand>` thin dispatcher to
       // the architectural-assumption trigger (divergence-sampling + extend-signal; §2).

package/commands/gsd-t-architect.md

@@ -99,11 +99,38 @@ the user, do not paper over it with a guess.
 
 ## Step 3: The subagent produces the output
 
-**A — Plain-English pseudocode** (the artifact), in the house style — title + one-line purpose,
-`CURRENT` (what it does today) and `PROPOSED` (the simplest fix) blocks, `# plain comment` inline,
-a summary table, near-zero preamble. For each CURRENT block, say **why it does what it does now**
-— and flag explicitly if it's a "got complicated over time" accretion (mechanisms stacked by
-successive fixes). Unless `--chat-only`, write it to `.gsd-t/pseudocode/PseudoCode-<Target>.md`.
+**A — Plain-English pseudocode** (the artifact), in the house style defined by contract
+`.gsd-t/contracts/pseudocode-source-of-truth-contract.md` **§1.1** and the mold
+`templates/PseudoCode-spec.md`. **THE FLOW IS THE DOCUMENT:**
+
+```
+# Title
+One sentence of purpose (two max).
+The flow.
+---
+Everything else.
+```
+
+The flow is a **nested decision tree in plain English**, 2-space indent per level, one thing per
+line, questions ending in `:` answered by indented `Yes:` / `No:` (or named outcomes) beneath
+them. **No function-call syntax, no `if`/`return`/`throw`/`tx:`, no bare status codes or
+SCREAMING_SNAKE constants, no paragraphs inside the flow.** A technical term rides **alongside**
+plain words in parentheses rather than replacing them — plain first, glossed once per `##`
+section: `Zoom's webhook (its automatic ping to us) arrives at /zoom/events`. Concrete real names
+(Zoom, the Save button, the invoices table, `/zoom/events`) need no gloss; bare category-nouns
+(webhook, payload, endpoint, token, cache) do.
+
+Below the divider: `## What it does today` / `## What changes` (each its own flow in the same
+style), `## The rules` (the `[RULE]` guard map), `## ⚠ Divergence`, `## Why this shape` (the
+Six-Stage answers in plain sentences), `## Where it lives` (file pointers — these live HERE, never
+in the flow). For each "what it does today" flow, say **why it does what it does now** — and flag
+explicitly if it's a "got complicated over time" accretion (mechanisms stacked by successive
+fixes).
+
+Worked reference: `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`. Unless `--chat-only`, write
+the artifact to `.gsd-t/pseudocode/PseudoCode-<Target>.md`, then **self-check it** with
+`gsd-t pseudocode-style --doc <the file>` — a non-zero exit means the style is wrong; fix it
+before presenting. (The same gate is FAIL-blocking in verify.)
 
 **B — Session summary** (always printed, even under `--build`):
 - **Simply Stated** (REQUIRED FIRST LINE — the clarity gate) — the verdict + the single most

package/commands/gsd-t-doc-ripple.md

@@ -8,7 +8,7 @@ You are the doc-ripple agent. You identify and update all downstream documents a
 preflight → brief (kind=doc-ripple) → doc-ripple agent (opus, with phase protocol)
 ```
 
-The agent identifies the full blast radius of recent code changes and updates every affected document in one pass: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `.gsd-t/contracts/`, `PseudoCode-[Title].md` (the intention-first behavior map — when the implemented behavior diverges from its pseudocode, ripple the change or write a `⚠ Divergence` flag per the source-of-truth contract §4), owning `scope.md`, `README.md`, and (for this repo) the 4 command-reference files when a command interface changed.
+The agent identifies the full blast radius of recent code changes and updates every affected document in one pass: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `.gsd-t/contracts/`, `PseudoCode-[Title].md` (the intention-first behavior map — when the implemented behavior diverges from its pseudocode, ripple the change or write a `⚠ Divergence` flag per the source-of-truth contract §4; **any edit keeps the §1.1 flow style** — the flow stays a nested plain-English decision tree, technical terms glossed alongside plain words, code identifiers below the `---` divider; self-check with `gsd-t pseudocode-style --doc <the file>`), owning `scope.md`, `README.md`, and (for this repo) the 4 command-reference files when a command interface changed.
 
 ## Step 1: Determine the change set
 

package/commands/gsd-t-milestone.md

@@ -38,6 +38,8 @@ The agent then **presents this approach to the user for SIGN-OFF**. The user sig
 
 Only after the approach is signed off, the agent authors the detailed `PseudoCode-[Title].md` at exemplar granularity (the five section elements of contract §1: Intention, Mechanism, one-breath summary table, Guard map, Divergence flags, Appendix). `[Title]` is the SUBJECT the doc represents (e.g. `PseudoCode-PayPal.md`), never a milestone id; a milestone may produce several. Per-milestone docs live at `.gsd-t/pseudocode/PseudoCode-[Title].md` (contract §7).
 
+**STYLE IS GOVERNED — contract §1.1, mold `templates/PseudoCode-spec.md`, worked reference `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`.** The document is `# Title` → one sentence of purpose → **the flow** → `---` → everything else. The flow is a **nested decision tree in plain English** (2-space indent, one thing per line, questions ending `:` answered by indented `Yes:` / `No:` beneath). **No function-call syntax, no `if`/`return`/`throw`/`tx:`, no bare status codes or SCREAMING_SNAKE constants, no paragraphs inside the flow.** A technical term rides **alongside** plain words in parentheses rather than replacing them — plain first, glossed once per `##` section (`Zoom's webhook (its automatic ping to us) arrives at /zoom/events`); concrete real names need no gloss. The guard map, divergence flags, Six-Stage answers, and every file/function pointer sit **below the divider**. After writing, self-check with `gsd-t pseudocode-style --doc <the file>` — non-zero means fix it before presenting. The same gate is FAIL-blocking in verify.
+
 ### Default-ON; skip is a LOGGED decision
 
 The two-altitude flow is **default-ON**. Skipping the detailed-doc altitude is a **LOGGED decision** in `.gsd-t/progress.md` (Decision Log entry naming WHY it was skipped) — **never a silent default-off** (`feedback_no_silent_degradation`). A skip that is not logged is a process failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.4.11",
+  "version": "5.5.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -464,12 +464,57 @@ See memory pointer: `feedback_auto_research_external_gaps`.
 - **When a similar-but-not-reusable thing already exists:** (a) same WHAT (job) or same HOW (surface)? Same WHAT → generalize; merely similar → build new. (b) If generalize: **extract a shared core, do NOT mutate** the working original (old callers keep identical behavior). (c) If blast-radius/stability forbids touching it → build new, **but register a "reuse-candidate" link in the graph** pointing at the twin, so the duplication is visible and re-decided on next touch. **Never build a silent rogue twin** — sprawl disables Stage 3's reuse-check for everyone after you.
 - **A wrong forecast self-corrects:** the graph's similarity check surfaces a LOW-forecast function that got reused anyway at the next Stage 3. So the forecast need only be directionally right — the graph rescues the misses. That is what removes the paralysis.
 
-**§Plain-English proof (the artifact you can always review, never must):** the Six-Stage answers are written into the milestone's **PseudoCode document** in plain, jargon-free language (style: `.gsd-t/pseudocode/` — title + one-line purpose, `CURRENT`/`PROPOSED` blocks, `# plain comment` inline, a summary table; near-zero preamble). Jargon is where unexamined complexity hides — a layman-legible sentence has nowhere for a pointless operation to survive. The pseudocode IS the audit, and it lets the user approve *direction before code* as the senior reviewer, not a rubber-stamp.
+**§Plain-English proof (the artifact you can always review, never must):** the Six-Stage answers are written into the milestone's **PseudoCode document** in plain, jargon-free language. Jargon is where unexamined complexity hides — a layman-legible sentence has nowhere for a pointless operation to survive. The pseudocode IS the audit, and it lets the user approve *direction before code* as the senior reviewer, not a rubber-stamp. **Style is governed, not freestyled — see § PseudoCode Style below.**
 
 **§Jargonless output (co-equal with brevity, NOT a trade-off):** short and clear are different axes; jargon is short, so brevity rules alone reward it. Every reply, plan, options-prompt, and mid-work narration glosses jargon in plain words on first use. The crux: individual shorthand may be decodable, but **several mashed into one sentence become unintelligible** — never force the reader toward an "I don't understand" escape hatch; if that option would help, the sentence already failed. Enforced by the Reader Contract (injected every turn).
 
 **§Enforcement (three layers — same shape as Unproven-Assumption):** (1) this doctrine = the *definition* (reference, always available); (2) a **PreToolUse hook on Write/Edit** = the *trigger* — injects a one-line reminder pointing here at the build moment, so it can't be missed under load; (3) the **plan/milestone workflow gate** = the *execution* — the Six-Stage Pass runs as blocking `agent()` steps with graph/doc evidence, and pseudocode-completeness is a verify check. Injecting the doctrine ≠ executing it; the workflow does the doing.
 
+### PseudoCode Style — the flow IS the document (MANDATORY)
+
+**Contract:** `.gsd-t/contracts/pseudocode-source-of-truth-contract.md` §1.1 · **Mold:** `templates/PseudoCode-spec.md` · **Worked reference:** `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`
+
+A PseudoCode document exists for ONE job: letting the user approve **direction before code**. A doc the reader must translate line-by-line cannot do that job, so how it READS is governed, not a matter of taste.
+
+```
+# Title
+One sentence of purpose (two max).
+The flow.
+---
+Everything else.
+```
+
+**The flow — a nested decision tree in plain English.** Not prose. Not transliterated code.
+
+```text
+Settings screen
+  Enter a value in the Profile URL field — click Save
+  Is the URL the right shape:
+    Yes: Open the page it points at
+      Is that page a real profile page:
+        Yes: Save it, show the green check
+        No:  Show "that page isn't a profile"
+    No:  Show "that doesn't look like a profile URL"
+```
+
+- 2-space indent per level; **one thing per line**; a question line ends with `:` and is answered by indented `Yes:` / `No:` (or named outcomes — `Found:` / `Expired:` / `Never seen:`) directly beneath it.
+- **BANNED in the flow:** function-call syntax (`loadStore(path):`), code keywords (`if`/`return`/`throw`/`catch`/`tx:`), bare status codes (`→ 409`) or SCREAMING_SNAKE constants (`MODULE_NOT_FOUND`), and any paragraph. A line needing a paragraph means the flow is under-decomposed — split it.
+
+**Words — the technical term rides ALONGSIDE plain words, never replaces them.** Keep the term (it's load-bearing and greppable); put the plain meaning first and the term in parentheses:
+
+| Write this | Not this |
+|---|---|
+| `Zoom's webhook (its automatic ping to us) arrives at /zoom/events` | `A webhook fires` |
+| `Read the message it sent (the payload) — pull out the meeting id` | `Parse the payload` |
+| `Refuse it as a duplicate (409)` | `→ 409` |
+
+- **Gloss once per `##` section**, then use the term bare; a new section re-glosses so a reader landing mid-file still follows.
+- **Concrete real names need no gloss** — `Zoom`, `the Save button`, `the invoices table`, `/zoom/events`. Only abstract category-nouns (webhook, payload, endpoint, handler, token, cache) require the parenthetical.
+
+**Below the divider** — and ONLY below it: `## What it does today` / `## What changes` (each its own flow, same style), `## The rules` (the `[RULE]` guard map), `## ⚠ Divergence`, `## Why this shape` (the Six-Stage answers in plain sentences), `## Where it lives` (file/function pointers). **Code identifiers live here, never in the flow.**
+
+**§Enforcement:** `gsd-t pseudocode-style (--doc <f> | --dir <d>)` — deterministic, exit 0 clean / 4 violations / 64 bad input. FAIL-blocking in `gsd-t-verify` alongside the guard-map gate. It checks the flow block ONLY, so the `[RULE]` guard map below the divider is never style-checked. Self-check any pseudocode you write BEFORE presenting it. Docs predating contract v1.2.0 are listed in `.gsd-t/pseudocode/.style-grandfathered` and skip with a named reason; removing a name is how a doc opts in.
+
 ### No-Fallback-Ever Doctrine (governed, enforced — the strongest sibling of No-Silent-Degradation)
 
 **Pretend every project is a vampire and the word "fallback" is garlic.** A fallback — **anything that continues after a failure** (a `catch` that keeps going, `|| default`, a silent degrade, a secondary path, a "try X else Y" where Y masks X failing) — is **BANNED unless the user explicitly approves it first, OR you can cite a confirmed, reproducible case where the straight-line path provably fails and ONLY a fallback catches it.** No trivial exception. This is a Destructive-Action-Guard-class STOP: before writing any such branch, **halt and ask the user.**

package/templates/PseudoCode-spec.md

@@ -1,194 +1,137 @@
-# {Title} — {one-line subject of this behavior map}
+# {Title}
 
-**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.}**
+{One sentence: what happens, in plain words. Two max. Usually one is enough.}
 
-> **⚠ {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.}
+```text
+{Where it starts — a screen, an arriving message, a scheduled moment}
+  {The first thing that happens}
+  {Is <the question being decided>}:
+    Yes: {what happens}
+      {Is <the next question>}:
+        Yes: {what happens}
+        No:  {what happens instead}
+    No:  {what happens instead}
+```
 
-_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)
+  HOW TO WRITE THIS  (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:
+
+  THE FLOW IS THE DOCUMENT. Everything else is an appendix below the divider
+  that the reader never has to open. Do not put explanation above the flow.
+
+  ── SHAPE ───────────────────────────────────────────────────────────────────
+  • A nested decision tree, indented 2 spaces per level. Not prose. Not code.
+  • Each line is one thing that happens, or one question being decided.
+  • A question line ends with a colon and is answered by indented
+    `Yes:` / `No:` lines directly beneath it (or named outcomes when there are
+    more than two — `Found:` / `Expired:` / `Never seen:`).
+  • NO function-call syntax. Write `Save it against the client's record`, never
+    `saveForClient(clientId, record)`. No `if`/`return`/`throw`/`tx:`/`→`.
+  • NO paragraphs inside the flow block. If a line needs a paragraph, the flow
+    is wrong — split it into more lines.
+
+  ── WORDS ───────────────────────────────────────────────────────────────────
+  Plain English carries the sentence; the technical name rides ALONGSIDE it in
+  parentheses. The reader must never have to translate a line in their head.
+
+      GOOD: Zoom's webhook (its automatic ping to us) arrives at /zoom/events
+      GOOD: Read the message it sent (the payload) — pull out the meeting id
+      GOOD: Save it in the invoices table
+      BAD:  A webhook fires                       (which webhook? whose?)
+      BAD:  Parse the payload                     (untranslated jargon)
+      BAD:  Return 401                            (means nothing on its own)
+
+  • Name the REAL thing. "Zoom", "the Save button", "the invoices table",
+    "/zoom/events" are concrete and welcome. Bare category-nouns — webhook,
+    payload, endpoint, handler, token, cache — are not, unless glossed.
+  • GLOSS ONCE PER SECTION. First use in a section carries the plain
+    explanation in parentheses; later lines in that same section use it bare.
+    A new `##` section re-glosses, so a reader landing mid-file still follows.
+  • Plain FIRST, term in parentheses SECOND. Not the reverse.
+
+  ── FILE STRUCTURE ──────────────────────────────────────────────────────────
+      # Title
+      One-sentence purpose.
+      The flow.
+      ---
+      Everything else.
+
+  Below the divider, in any order, only what this subject actually has:
+    • `## What it does today` / `## What changes` — the before/after, each as
+      its own flow in the same style.
+    • `## The rules` — the guard map. Every invariant as a one-line `[RULE]`
+      (grammar owned by the contract §2 — do not re-derive it here).
+    • `## ⚠ Divergence` — flags wherever this supersedes shipped behavior.
+      Keeping existing behavior = no flag. (Contract §4.)
+    • `## Why this shape` — the Architect's Six-Stage answers, in plain words.
+    • `## Where it lives` — file and function pointers, if useful. These belong
+      HERE, not in the flow.
+
+  ── NAMING + CITATION ───────────────────────────────────────────────────────
+  • Name the file `PseudoCode-[Title].md` where [Title] is the SUBJECT
+    (`PseudoCode-ProfileUrlSave.md`), never a milestone id. Only this blank
+    mold keeps the `-spec` suffix.
+  • A milestone may produce several files — one per coherent subject.
+  • Plan tasks cite a section 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.
+  • Grammars live in `.gsd-t/contracts/pseudocode-source-of-truth-contract.md`
+    (§1.1 flow style · §2 guard-map · §3 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.}
+## What it does today
 
 ```text
-PRECONDITION:
-  {The exact starting state — what is loaded / grouped / present, and what is
-   deliberately NOT persisted yet.}
+{The current flow, same nested style. Delete this section for new behavior
+ that has no "today".}
 ```
 
-> ⚠ **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.}
+## What changes
 
 ```text
-{ACTOR}  on {trigger}:
-    {step}
-    {the call / the guard}
-    on {outcome}:  {what happens}
-    on {failure}:  {the safe fallback — never a crash}
+{The new flow, same nested style. The reader should be able to diff this
+ against the section above by eye.}
 ```
 
 ---
 
-## 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".}
+## The rules
 
 ```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}
+{invariant in one line}                          [RULE] {the invariant}
+{what can never happen}                          [RULE] {the prohibition}
+{what happens on failure}                        [RULE] {the safe-failure invariant}
 ```
 
----
-
-## 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}
-```
+{One short paragraph, plain words: the one thing that must never happen, and
+why repeating any step is harmless.}
 
 ---
 
-## {N}. {Subject}-safety map — every guard, as a one-line [RULE]
+## ⚠ Divergence
 
-```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.}**
+{`⚠ Divergence: <section or RULE-ID> — supersedes shipped <what>. Reason: <the
+intention>.` for each supersede. Delete this whole section if nothing is
+superseded.}
 
 ---
 
-## {Optional} — {ONE STORE / shared-state / known-gaps notes}
+## Why this shape
 
-> {Optional sections the exemplars carry: a shared-store note, a "Known gaps /
-> status (as of {version})" list. Include only if the subject has them.}
+{The Architect's Six-Stage answers, in plain jargon-free sentences. What the
+objective is · what it conflicts with · what already exists that we reuse ·
+why this is the simplest version · whether it will be reused again · what
+could go wrong.}
 
 ---
 
-## Appendix — Raw pseudocode (no intention comments)
+## Where it lives
 
-```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
-```
+| Step in the flow | File |
+|------------------|------|
+| {the flow line} | `{path}` |

package/templates/prompts/keep-or-supersede-subagent.md

@@ -38,6 +38,8 @@ Every **supersede** WRITES a `⚠ Divergence` flag into `PseudoCode-[Title].md`,
 
 **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.
 
+**WHERE the flag goes (contract §1.1.4):** under the `## ⚠ Divergence` heading **below the first `---` divider** — never inside the flow block at the top of the document. The flow is the readable decision tree the user approves; divergence flags, the guard map, and file pointers all live below the divider. (The `gsd-t pseudocode-style` gate checks the flow block only, so a flag placed correctly is never style-checked — one placed in the flow will fail it.)
+
 > **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)

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

@@ -869,6 +869,7 @@ ${STATED_CLAIMS_INSTRUCTION}`,
 TWO-ALTITUDE INTENTION-FIRST FLOW (M87, default-ON — contract pseudocode-source-of-truth-contract.md §1). Author the milestone at two altitudes, IN ORDER:
   ALTITUDE 1 — HIGH-LEVEL APPROACH (signed off FIRST): emit the high-level approach pseudocode — what/why/when (the user's intention, never agent reasoning), the actors, and a one-breath summary ("one call in one breath"). PRESENT this approach to the user for SIGN-OFF. The detailed doc is authored ONLY AFTER the approach is approved — the sign-off is the checkpoint between the two altitudes. (This is a PROSE flow: describe the checkpoint; do NOT assert a machine-checkable DEFINED-state predicate — that is M88.)
   ALTITUDE 2 — DETAILED doc: only after the approach is signed off, author .gsd-t/pseudocode/PseudoCode-[Title].md at exemplar granularity (the §1 section set: Intention, Mechanism, one-breath table, Guard map, Divergence flags, Appendix). [Title] = the SUBJECT (e.g. PseudoCode-PayPal.md), never a milestone id; a milestone may produce several.
+  STYLE (contract §1.1, GOVERNED + machine-gated): "# Title" → one sentence of purpose → THE FLOW → "---" → everything else. The flow is a NESTED DECISION TREE IN PLAIN ENGLISH — 2-space indent per level, one thing per line, a question line ending ":" answered by indented "Yes:" / "No:" (or named outcomes) directly beneath it. BANNED in the flow: function-call syntax (loadStore(path):), code keywords (if/return/throw/catch/tx:), bare status codes (→ 409) or SCREAMING_SNAKE constants (MODULE_NOT_FOUND), and any paragraph — a line needing a paragraph means the flow is under-decomposed, so split it. A technical term rides ALONGSIDE plain words in parentheses rather than replacing them: plain FIRST, term second, glossed once per "##" section — "Zoom's webhook (its automatic ping to us) arrives at /zoom/events", "Read the message it sent (the payload) — pull out the meeting id". Concrete real names (Zoom, the Save button, the invoices table, /zoom/events) need no gloss; abstract category-nouns (webhook, payload, endpoint, handler, token, cache) do. The guard map, divergence flags, Six-Stage answers, and every file/function pointer sit BELOW the divider. Mold: templates/PseudoCode-spec.md. Worked reference: .gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md. Self-check with: gsd-t pseudocode-style --doc <the file> (non-zero = fix before presenting; the same gate is FAIL-blocking in verify).
 DEFAULT-ON; skip is a LOGGED decision in progress.md naming WHY — NEVER a silent default-off (feedback_no_silent_degradation).
 KEEP-OR-SUPERSEDE: before encoding any model inherited from shipped code, run the keep-or-supersede protocol (templates/prompts/keep-or-supersede-subagent.md) — per inherited model ASK keep or supersede; each supersede WRITES a ⚠ Divergence flag (§4 grammar) into the doc. Keep = no flag.
 
@@ -914,8 +915,19 @@ const _architectPassLine = _ARCHITECT_PHASES.has(phaseName)
       `ARCHITECT'S OVERSIGHT — run this Six-Stage Pass BEFORE finalizing the ${phaseName}, IN ORDER.`,
       `Each stage can KILL/reshape the plan. Answer each with EVIDENCE (a grep, a Read, or the`,
       `graph slice above) — never conviction. Record the answers in plain, jargon-free language`,
-      `in the milestone's PseudoCode document (.gsd-t/pseudocode/), house style: title + one-line`,
-      `purpose, CURRENT/PROPOSED blocks, "# plain comment" inline, a summary table.`,
+      `in the milestone's PseudoCode document (.gsd-t/pseudocode/), in the GOVERNED style of`,
+      `contract pseudocode-source-of-truth-contract.md §1.1: "# Title" → one sentence of purpose`,
+      `→ THE FLOW → "---" → everything else. The flow is a NESTED DECISION TREE IN PLAIN ENGLISH`,
+      `(2-space indent, one thing per line, a question line ending ":" answered by indented`,
+      `"Yes:" / "No:" beneath it). BANNED in the flow: function-call syntax, if/return/throw/tx:,`,
+      `bare status codes or SCREAMING_SNAKE constants, and any paragraph. A technical term rides`,
+      `ALONGSIDE plain words in parentheses rather than replacing them — plain first, glossed once`,
+      `per "##" section (e.g. "Zoom's webhook (its automatic ping to us) arrives at /zoom/events");`,
+      `concrete real names (Zoom, the Save button, the invoices table) need no gloss. The Six-Stage`,
+      `answers go under "## Why this shape" BELOW the divider, alongside the guard map, divergence`,
+      `flags, and any file/function pointers — code identifiers NEVER appear in the flow.`,
+      `Self-check with: gsd-t pseudocode-style --doc <the file>  (non-zero = fix before presenting;`,
+      `the same gate is FAIL-blocking in verify).`,
       `  1. OBJECTIVE — what is the core objective, and why is it the objective?`,
       `  2. CONFLICT — does it conflict with another objective? must a prior one be re-examined?`,
       `  3. REUSE — have I already done any piece of this? Can I reuse the PROCESS, or the OUTPUT`,

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

@@ -39,7 +39,7 @@ export const meta = {
     { title: "Auto-Research Gate", detail: "M89 §7 ENFORCE: scan for status=uncited markers (A4 — no silent guess)" },
     { title: "CI-Parity",          detail: "M57 build-coverage + ci-parity (FAIL-blocking)" },
     { title: "Test-Data Purge",    detail: "M58 test-data --purge (FAIL-blocking)" },
-    { title: "Guard-Map Gate",     detail: "M87 [RULE] guard-map gate (FAIL-blocking, §7 discovery)" },
+    { title: "Guard-Map Gate",     detail: "M87 [RULE] guard-map gate + §1.1 flow-line style gate (FAIL-blocking, §7 discovery)" },
     { title: "Orthogonal Triad",   detail: "code-review ultra ∥ Red Team ∥ QA" },
     { title: "Synthesis",          detail: "merge without collapsing categories" },
   ],
@@ -721,6 +721,51 @@ if (guardMapDiscovery.docsFound === 0 || (guardMapDiscovery.firePairs || []).len
   log(`M87 guard-map gate green (${guardMapResults.length} doc+map pair(s) fired) — proceeding to orthogonal triad`);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// PseudoCode §1.1 flow-line STYLE gate (contract v1.2.0, FAIL-blocking)
+//
+// Sibling of the guard-map gate above: guard-map holds what a doc CONTAINS, this
+// holds how it READS. A PseudoCode doc exists so the user can approve DIRECTION
+// before code; a doc written as transliterated source (`loadStore(path):`,
+// `MODULE_NOT_FOUND`, `→ 409`) buried under preamble cannot do that job.
+//
+// Needs no discovery agent — it globs the dir itself (contract §7 reused) and is
+// pure deterministic code. Pre-v1.2.0 docs are grandfathered via
+// .gsd-t/pseudocode/.style-grandfathered as a logged skip WITH A REASON.
+// ─────────────────────────────────────────────────────────────────────────────
+const styleGate = await runCli(
+  projectDir,
+  "pseudocode-style",
+  ["--dir", `${projectDir}/.gsd-t/pseudocode`, "--json"],
+  "gsd-t-pseudocode-style.cjs",
+  "pseudocode-style",
+  true,
+  "Guard-Map Gate"
+);
+const styleEnv = styleGate.envelope || {};
+if (styleGate.exitCode === 64) {
+  // Bad input (missing dir) — a project with no .gsd-t/pseudocode/ has nothing to
+  // gate. Surfaced, not silent.
+  log(`PseudoCode style gate: SKIP — ${styleEnv.reason || "no .gsd-t/pseudocode directory"}`);
+} else if (!styleGate.ok) {
+  const v = styleEnv.violations || [];
+  const named = v.slice(0, 8).map((x) => `${(x.doc || "").split("/").pop()}:${x.line} ${x.rule}`).join("; ")
+    || styleEnv.reason || "(violation detail unavailable)";
+  log(`PseudoCode style gate FAIL exitCode=${styleGate.exitCode} — ${v.length} violation(s): ${named} — halting before triad`);
+  return {
+    status: "pseudocode-style-gate-failed",
+    overallVerdict: "VERIFY-FAILED",
+    reason: `PseudoCode §1.1 flow-line style violations (${v.length}): ${named}. The flow must read as a nested decision tree in plain English — technical terms glossed alongside plain words, code identifiers below the --- divider. See templates/PseudoCode-spec.md and .gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md for the worked reference.`,
+    pseudocodeStyle: styleEnv,
+    guardMap: { discovery: guardMapDiscovery, results: guardMapResults },
+    verifyGate: vg.envelope,
+    autoResearchGate: arGate,
+  };
+} else {
+  const skipped = (styleEnv.skips || []).length;
+  log(`PseudoCode style gate: PASS (${styleEnv.docsChecked || 0} doc(s), ${skipped} grandfathered) — proceeding to orthogonal triad`);
+}
+
 phase("Orthogonal Triad");
 
 const briefRef = brief.briefPath || "(brief generation failed — re-walk repo)";