@tekyzinc/gsd-t 5.0.14 → 5.1.10

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.1.10] - 2026-07-13
+
+### Added — Simply Stated Doctrine (clarity as a defect gate, the verbose-virus cure)
+
+The recurring "verbose virus" — GSD-T deliverables that are dense, jargon-heavy, and unreadable (one architecture review drew "plain English please" five times in a single message) — has resisted every prior fix (Reader Contract, retired brevity Stop hook, jargon lint) because those treat verbosity as OUTPUT polish and are reminders that lose under load. Simply Stated is a different mechanism: it treats verbosity as a SYMPTOM of unclear thinking, and the same unclear thinking ships the bugs. Before GSD-T presents an architecture/plan/finding/milestone, it must state it simply first — every word load-bearing, straight-line logic, no jargon or nested clauses. If it can't, the thinking isn't done: RE-THINK, don't re-word. HALT-as-defect, not a soft nudge. "Simply" ≠ dumbed down — the content stays as sophisticated as the problem; only the expression is clean ("too sophisticated to simplify" is a banned escape hatch).
+
+- `templates/CLAUDE-global.md` (+ `~/.claude/CLAUDE.md`): the doctrine (definition) — the clarity=thinking equivalence, the HALT, the anti-dumbing-down clause.
+- `scripts/gsd-t-architect-oversight-guard.js`: the Write/Edit trigger reminder now carries the Simply-Stated challenge (reused the architect hook — no new hook).
+- `templates/workflows/gsd-t-phase.workflow.js`: Stage 7 (Simply-Stated clarity gate) in the Six-Stage Pass — the plan isn't done until it has a clean simply-stated lead.
+- `commands/gsd-t-architect.md`: Stage 7 in the pass + "Simply Stated" is now the REQUIRED FIRST LINE of the architect's session summary.
+- `.gsd-t/contracts/architects-oversight-contract.md`: Stage 7 row.
+- `test/m101-architect-oversight-hook.test.js`: 5 wiring tests (both templates, hook, workflow, command).
+
 ## [5.0.14] - 2026-07-13
 
 ### Added — No-Fallback-Ever Doctrine (never branch around a failure without asking)

package/README.md

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

@@ -0,0 +1,65 @@
+"use strict";
+
+// bin/gsd-t-doc-marker.cjs
+//
+// M102 — the ONE shared marker-block idempotent doc-writer. Extracted from the
+// M100 logging scaffolder's private `writeChoiceToProjectDocs` (so there is a
+// single writer, not two copies): both bin/gsd-t-logging-scaffolder.cjs and
+// bin/gsd-t-env-registry.cjs call this.
+//
+// upsertMarkedDocBlock(targetPath, startMarker, endMarker, block):
+//   - If targetPath contains BOTH markers, the region between them (inclusive)
+//     is REPLACED with `block` (idempotent re-write).
+//   - Otherwise `block` is appended to the end of the file (creating the file
+//     and any missing parent dirs).
+//   - `block` MUST already begin with startMarker and end with endMarker — the
+//     caller composes the full block (same contract the M100 writer used).
+//
+// Zero external npm runtime deps — fs/path only. Symlink-guarded: refuses to
+// write through a symlinked target (defense-in-depth, matches the installer's
+// settings-writer scaffold).
+
+const fs = require("fs");
+const path = require("path");
+
+function isSymlink(filePath) {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+// Replace the [startMarker … endMarker] region with `block`, or append it.
+// Returns the written targetPath. Idempotent: a second call with the same
+// block leaves the file byte-identical.
+function upsertMarkedDocBlock(targetPath, startMarker, endMarker, block) {
+  if (!targetPath) throw new Error("upsertMarkedDocBlock: targetPath is required");
+  if (!startMarker || !endMarker) throw new Error("upsertMarkedDocBlock: start/end markers are required");
+  if (typeof block !== "string") throw new Error("upsertMarkedDocBlock: block must be a string");
+
+  if (isSymlink(targetPath)) {
+    throw new Error(`upsertMarkedDocBlock: refusing to write through symlinked target: ${targetPath}`);
+  }
+
+  let content = "";
+  if (fs.existsSync(targetPath)) {
+    content = fs.readFileSync(targetPath, "utf8");
+  } else {
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (content.includes(startMarker) && content.includes(endMarker)) {
+    const startIdx = content.indexOf(startMarker);
+    const endIdx = content.indexOf(endMarker) + endMarker.length;
+    content = content.slice(0, startIdx) + block + content.slice(endIdx);
+  } else {
+    content = content.replace(/\s*$/, "") + "\n\n" + block + "\n";
+  }
+
+  fs.writeFileSync(targetPath, content, "utf8");
+  return targetPath;
+}
+
+module.exports = { upsertMarkedDocBlock };

package/bin/gsd-t-env-registry-check.cjs

@@ -0,0 +1,318 @@
+"use strict";
+
+// bin/gsd-t-env-registry-check.cjs
+//
+// M102 D3 — the deterministic verify-gate lint for the Environment Registry.
+// FAIL-CLOSED. Two failure conditions (spec D3):
+//   (a) any Environments row cell is NOT the POSITIVE shape its column is
+//       supposed to hold (a value that is not a real hostname / not the enum /
+//       not a $VAR / not a curated command token = a probable inline secret);
+//   (b) the env-access DOC RULE is present in the project's CLAUDE.md but the
+//       `## Environments` table MARKERS are absent from docs/infrastructure.md
+//       (rule promises a registry the doc doesn't provide).
+//
+// A project that has neither the table nor the rule is a NO-OP PASS (it simply
+// hasn't adopted M102 yet) — distinguishable from a wired-but-broken FAIL.
+//
+// Zero external npm runtime deps — fs/path only.
+//
+// PRIMARY GUARD = POSITIVE PER-COLUMN SHAPE (re-derived here, NOT a call into
+// the writer). The gate RE-IMPLEMENTS the positive shapes so a writer bug can
+// never silently disable it. It maps each cell to its column and requires the
+// cell to BE the shape that column holds:
+//   - host        → localhost / IPv4 / dotted-DNS / short lowercase service label
+//   - db/name     → short lowercase snake identifier (≤16, no digit→letter)
+//   - auth method → enumerated auth-method name
+//   - fetch/connect command → every token is $VAR / flag / hostname / curated word
+//   - access gotchas → enumerated (vpn|ip-allowlist|ssh-tunnel|bastion|none) + via host
+//   - secret vault → enumerated vault name
+//   - secret env-var NAME → UPPER_SNAKE
+// A cell that is NOT its column's positive shape → FAIL.
+//
+// BACKSTOP (extra layer, applied to EVERY cell regardless of column): the
+// imported known-prefix/JWT/base64/hex `looksLikeSecretValue` + the gate's OWN
+// embedded-credential regex. These are NOT the primary guard — the positive
+// per-column shape is. A secret that somehow matched a positive shape (it can't
+// by construction) would still trip these.
+
+const fs = require("fs");
+const path = require("path");
+
+const {
+  ENV_MARKER_START,
+  ENV_MARKER_END,
+  ENV_COLUMNS,
+  looksLikeSecretValue,
+} = require("./gsd-t-env-registry.cjs");
+
+// The gate ALSO carries its own inline embedded-credential detector so it is
+// not solely dependent on the imported symbol — a proto://user:pw@ literal in
+// ANY cell fails independently of the writer's classification.
+const GATE_EMBEDDED_CRED = /[a-z][a-z0-9+.\-]*:\/\/[^\s:/@]+:(?!\$)[^\s:/@]+@/i;
+
+// ─── Gate's OWN re-implemented POSITIVE shapes (independent of the writer) ────
+//
+// Deliberately re-declared here (not imported) so the gate is a genuinely
+// independent implementation — a bug in the writer's shapes cannot disable the
+// gate's.
+
+const GATE_DOTTED_HOSTNAME =
+  /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+const GATE_IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const GATE_BARE_HOST_LABEL = /^[a-z][a-z-]{0,15}$/;
+const GATE_VAR_REF = /^["']?\$\{?[A-Za-z_][A-Za-z0-9_]*\}?["']?$/;
+const GATE_UPPER_SNAKE = /^[A-Z][A-Z0-9_]*$/;
+// An ISO-8601 timestamp (the `recorded` column) is structural, not a secret.
+const GATE_ISO_TS = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+const GATE_AUTH_METHODS = new Set([
+  "password", "iam", "oauth", "oauth2", "service-account", "ssh-key",
+  "api-key", "none", "scram-sha-256", "md5", "trust", "token", "key",
+  "cert", "mtls", "kerberos", "ldap",
+]);
+const GATE_VAULTS = new Set([
+  "local", "local (.env)", ".env", "env",
+  "vercel", "neon", "gcp-secret-manager", "google secret manager",
+  "aws-secrets-manager", "aws secrets manager", "doppler", "1password",
+  "hashicorp-vault", "vault", "azure-key-vault", "infisical",
+]);
+const GATE_GOTCHA_ENUM = new Set(["vpn", "ip-allowlist", "ssh-tunnel", "bastion", "none"]);
+const GATE_CLI_WORDS = new Set([
+  "psql", "mysql", "mysqldump", "mongo", "mongosh", "redis-cli", "sqlite3",
+  "pg_dump", "pg_restore", "pg_dumpall", "cqlsh", "clickhouse-client",
+  "neonctl", "vercel", "gcloud", "aws", "az", "doppler", "supabase",
+  "flyctl", "fly", "heroku", "railway", "wrangler", "turso", "op", "infisical",
+  "kubectl", "helm", "terraform", "vault",
+  "ssh", "scp", "sftp", "curl", "wget", "ldapsearch", "nc", "openssl", "rsync",
+  "env", "pull", "push", "list", "get", "set", "secrets", "versions",
+  "access", "version", "exec", "run", "connect", "login", "logout",
+  "connection-string", "db-url", "database-url", "redis-url",
+  "admin", "default", "latest", "read", "write", "describe", "show",
+  "from", "cat", "source", "printenv", "dotenv",
+]);
+const GATE_DOTFILE_TOKEN = /^\.[a-z][a-z0-9]*(?:\.[a-z][a-z0-9-]*)*$/;
+
+function gateIsDbNameShape(s) {
+  if (typeof s !== "string" || s.length === 0 || s.length > 16) return false;
+  if (!/^[a-z][a-z0-9_]*$/.test(s)) return false;
+  if (/[0-9][a-z]/.test(s)) return false;
+  return true;
+}
+function gateIsHostShape(s) {
+  if (s === "localhost") return true;
+  if (GATE_IPV4.test(s)) return true;
+  if (GATE_DOTTED_HOSTNAME.test(s)) return true;
+  if (GATE_BARE_HOST_LABEL.test(s)) return true;
+  return false;
+}
+function gateIsVarRef(tok) {
+  const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
+  return GATE_VAR_REF.test(tok) || /^\$\{?[A-Za-z_][A-Za-z0-9_]*\}?$/.test(bare);
+}
+// A single command token is on the positive allowlist?
+function gateCommandTokenOk(tok) {
+  const bare = tok.replace(/^["']/, "").replace(/["']$/, "");
+  if (bare === "") return true;
+  if (gateIsVarRef(tok)) return true;
+  if (/^--?[A-Za-z][A-Za-z0-9-]*$/.test(bare)) return true; // bare flag
+  if (/^--?[A-Za-z][A-Za-z0-9-]*=/.test(bare)) {
+    const value = bare.slice(bare.indexOf("=") + 1);
+    if (value === "") return true;
+    return gateCommandTokenOk(value);
+  }
+  if (gateIsHostShape(bare)) return true;
+  if (GATE_DOTFILE_TOKEN.test(bare)) return true;
+  if (GATE_CLI_WORDS.has(bare.toLowerCase())) return true;
+  if (gateIsDbNameShape(bare)) return true;
+  return false;
+}
+function gateTokenizeCommand(s) {
+  const tokens = [];
+  const re = /"[^"]*"|'[^']*'|\S+/g;
+  let m;
+  while ((m = re.exec(s)) !== null) tokens.push(m[0]);
+  return tokens;
+}
+function gateCommandOk(cell) {
+  for (const tok of gateTokenizeCommand(cell)) {
+    if (!gateCommandTokenOk(tok)) return false;
+  }
+  return true;
+}
+function gateGotchasOk(cell) {
+  const tokens = cell.split(/[,\s]+/).filter(Boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i].toLowerCase();
+    if (GATE_GOTCHA_ENUM.has(t)) continue;
+    if (t === "via") {
+      const next = tokens[i + 1];
+      if (!next || !gateIsHostShape(next)) return false;
+      i++;
+      continue;
+    }
+    if (gateIsHostShape(tokens[i])) continue;
+    return false;
+  }
+  return true;
+}
+
+// The BACKSTOP leak test — the known-prefix/JWT/base64/hex detector + the
+// embedded-cred regex. Applied to EVERY cell as an extra layer.
+function cellHitsBackstop(cell) {
+  if (typeof cell !== "string" || !cell) return false;
+  if (looksLikeSecretValue(cell)) return true;
+  if (GATE_EMBEDDED_CRED.test(cell)) return true;
+  return false;
+}
+
+// PRIMARY GUARD: is this cell the POSITIVE shape its column is supposed to hold?
+// Returns true if the cell is VALID for its column. An empty cell / placeholder
+// (`—`) is always valid. `col` is the column NAME.
+function cellMatchesColumnShape(col, cell) {
+  if (typeof cell !== "string") return true;
+  const s = cell.trim();
+  if (s === "" || s === "—") return true;
+  switch (col) {
+    case "id":
+      // <scope>-<kind> — lowercase identifier with a hyphen.
+      return /^[a-z0-9][a-z0-9-]*$/.test(s);
+    case "scope":
+      return s === "local" || s === "staging" || s === "prod";
+    case "kind":
+      return /^[a-z0-9][a-z0-9-]*$/.test(s);
+    case "host":
+      return gateIsHostShape(s.replace(/:\d+$/, ""));
+    case "port":
+      return /^\d+$/.test(s);
+    case "db/name":
+      return gateIsDbNameShape(s);
+    case "auth method":
+      return GATE_AUTH_METHODS.has(s.toLowerCase());
+    case "secret vault":
+      return GATE_VAULTS.has(s.toLowerCase());
+    case "secret env-var NAME":
+      return GATE_UPPER_SNAKE.test(s);
+    case "fetch command":
+    case "connect command":
+      return gateCommandOk(s);
+    case "access gotchas":
+      return gateGotchasOk(s);
+    case "read-only default":
+      return s === "YES" || s === "NO";
+    case "recorded":
+      return GATE_ISO_TS.test(s);
+    default:
+      // Unknown column — fall back to refusing anything the backstop flags.
+      return !cellHitsBackstop(s);
+  }
+}
+
+// The gate's leak test for a cell in a KNOWN column: FAIL if it is NOT the
+// column's positive shape OR (backstop) it hits the known-prefix/embedded-cred
+// detector. The positive shape is the PRIMARY guard.
+function cellLeaks(col, cell) {
+  if (typeof cell !== "string" || !cell) return false;
+  if (!cellMatchesColumnShape(col, cell)) return true; // primary: wrong shape
+  if (cellHitsBackstop(cell)) return true; // backstop: extra layer
+  return false;
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (_) {
+    return null;
+  }
+}
+
+function splitRow(line) {
+  const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  const cells = [];
+  let cur = "";
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i];
+    if (ch === "\\" && trimmed[i + 1] === "|") {
+      cur += "|";
+      i++;
+    } else if (ch === "|") {
+      cells.push(cur.trim());
+      cur = "";
+    } else {
+      cur += ch;
+    }
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+function check(projectDir) {
+  const infraPath = path.join(projectDir, "docs", "infrastructure.md");
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+
+  const infra = readSafe(infraPath) || "";
+  const claude = readSafe(claudePath) || "";
+
+  const hasMarkers = infra.includes(ENV_MARKER_START) && infra.includes(ENV_MARKER_END);
+  // The env-access rule is identified by its stable marker phrase.
+  const hasRule = /Environment Access — read-first, HALT-and-document/.test(claude);
+
+  const failures = [];
+
+  // (b) rule present but table markers absent.
+  if (hasRule && !hasMarkers) {
+    failures.push(
+      "env-access rule is present in CLAUDE.md but the `## Environments` table markers are absent from docs/infrastructure.md"
+    );
+  }
+
+  // (a) secret-shaped value in any row cell.
+  if (hasMarkers) {
+    const start = infra.indexOf(ENV_MARKER_START);
+    const end = infra.indexOf(ENV_MARKER_END);
+    const block = infra.slice(start, end);
+    const lines = block.split("\n");
+    for (const line of lines) {
+      if (!line.trim().startsWith("|")) continue;
+      const cells = splitRow(line);
+      if (cells[0] === "id") continue; // header
+      if (cells.every((c) => /^-{1,}$/.test(c) || c === "")) continue; // separator
+      for (let i = 0; i < cells.length; i++) {
+        const col = ENV_COLUMNS[i] || `col${i}`;
+        if (cellLeaks(col, cells[i])) {
+          failures.push(
+            `Environments row cell (${col}) contains a secret-shaped literal value: "${cells[i]}" — record the env-var NAME and a $VAR reference, never a literal secret`
+          );
+        }
+      }
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    check: "env-registry",
+    hasMarkers,
+    hasRule,
+    failures,
+    note:
+      !hasMarkers && !hasRule
+        ? "no-op PASS: project has not adopted the M102 Environments registry (no table, no rule)"
+        : undefined,
+  };
+}
+
+function parseArgs(argv) {
+  const out = { projectDir: "." };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--project") out.projectDir = argv[++i] || ".";
+  }
+  return out;
+}
+
+module.exports = { check };
+
+if (require.main === module) {
+  const { projectDir } = parseArgs(process.argv.slice(2));
+  const result = check(projectDir);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(result.ok ? 0 : 1);
+}