@tekyzinc/gsd-t 5.9.10 → 5.10.10

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.10.10] - 2026-08-07
+
+### Added — a project's CLAUDE.md is written from what actually happened in it
+
+The template was GSD-T's own CLAUDE.md. It byte-copied into another project with that project's name substituted into GSD-T's own prose — 127 lines describing an npm CLI installer the project was not. Every new project was getting a file about the wrong software.
+
+**`/gsd-t-setup` now reads the project's history first.** A rule that keeps getting broken is the rule that most needs writing down, and nobody recalls those on request — they have to be found. Three sources: git, the decision log, and what you typed in past sessions.
+
+Session history is large — one project holds 315 MB across 57 sessions. Keeping only what you typed leaves 645 KB; dropping pasted logs leaves 92 complaint-shaped turns. **735 milliseconds, no subagents.**
+
+The search terms were corrected against real transcripts. Every obvious guess scored zero — "I never asked you to", "that's the third time". People don't accuse; they restate the requirement. "still not", "you keep", "why did you" are what actually appear.
+
+**Then it shows you the rules the project already states, and you tick the ones that can never be broken.** Six sources, ranked by how many agree — repetition is the evidence. Each rule shows where it came from, so you're confirming something you already said rather than recalling it. Capped at 12 on screen; the rest are written to a file, never dropped.
+
+On one project the top four are its real inviolable rules with their ids. Three other projects each surface their own true rule first.
+
+**The template is replaced** with a real mold: 45 lines, every section omittable with a stated reason, and one rule written into the mold itself — nothing that carries a number which changes on its own. A version, a line count, or "currently in progress" is wrong within a week and belongs in `progress.md`.
+
+- `bin/gsd-t-project-history.cjs`: the funnel, three sources, each reporting whether it was there
+- `bin/gsd-t-rule-mine.cjs`: six sources, deduplicated by what the rule claims
+- `templates/CLAUDE-project.md`: replaced
+- `commands/gsd-t-setup.md`: reads history, shows a tick-list, uses the mold
+- `test/m109-project-claude-md.test.js`: 15 tests
+
+**Not fixed, and said plainly:** a project CLAUDE.md is still written once and never updated, so a fresh file starts going stale immediately. The fix — giving project files the same marker-block treatment the global file has — is a separate milestone.
+
+Run `/gsd-t-setup` inside a project to rewrite its file. It shows you the result and waits for a yes before writing.
+
 ## [5.9.10] - 2026-08-07
 
 ### Added — projects repair their own install, and fallbacks need approval by name

package/README.md

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

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-project-history.cjs
+ *
+ * M109-D1 — Reads what actually happened in a project, so its CLAUDE.md can be
+ * written from evidence rather than from a template.
+ *
+ * [RULE] history-distinguishes-absent-from-unreadable
+ * [RULE] history-names-every-session-it-could-not-read
+ * [RULE] history-reads-what-the-user-typed-not-what-was-pasted
+ *
+ * Three sources, cheapest first: git, the decision log, and what the user typed
+ * in past sessions. The transcripts are the richest and the largest — binvoice
+ * holds 315 MB across 27 sessions — so they are funnelled, not read whole:
+ *
+ *   315 MB  raw sessions
+ *    2.9 MB  keep only the user's own turns
+ *    645 KB  drop pasted logs (35 giant lines held 78% of the bytes)
+ *    7.4 KB  keep only complaint-shaped lines
+ *
+ * Two seconds, no subagents, and the result fits in context.
+ *
+ * ─── Absent is not the same as unreadable ───────────────────────────────────
+ * A source that ISN'T THERE is an ordinary fact — a project may have no git
+ * history. A source that IS there but cannot be read is a FAILURE, and saying
+ * "not available" about it would produce a thinner CLAUDE.md that looks
+ * complete. Those two cases are reported differently, and the second one halts.
+ *
+ * The one sanctioned exception (David's call, 2026-08-07): among many session
+ * files, one that cannot be read is skipped and NAMED rather than halting —
+ * a single truncated in-progress session should not block the rewrite. Every
+ * skipped session is listed in the output and belongs in the generated file.
+ *
+ * ─── Usage ──────────────────────────────────────────────────────────────────
+ *   node gsd-t-project-history.cjs --project <dir> [--json] [--sessions N]
+ *
+ * ─── Exit codes ─────────────────────────────────────────────────────────────
+ *   0  read something
+ *   4  no history at all — the caller must halt, never write a thin file
+ *   64 a source exists but could not be read, or bad input
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const EXIT_OK = 0;
+const EXIT_NO_HISTORY = 4;
+const EXIT_UNREADABLE = 64;
+
+// A pasted log is not something the user typed. 35 such lines held 78% of
+// binvoice's post-filter bytes.
+const PASTE_THRESHOLD = 2000;
+
+/** Thrown when a source exists but cannot be read. Never treated as absent. */
+class Unreadable extends Error {}
+
+/**
+ * What a complaint actually looks like — measured against real transcripts,
+ * not assumed. The obvious guesses all scored zero:
+ *   "I never asked you to"  0 hits
+ *   "that's the third time" 0 hits
+ *   "you were supposed to"  0 hits
+ * The user does not accuse. He restates the requirement.
+ */
+const COMPLAINT = new RegExp([
+  "still (not|isn'?t|doesn'?t|don'?t|broken|failing|wrong|happening)",
+  "you keep",
+  "why (did|didn'?t|do|does|is|are) (you|it|this)",
+  "keeps? (happening|coming up|breaking|failing)",
+  "hard rule",
+  "(third|3rd|second|2nd) (time|attempt|try)",
+  "same (result|issue|problem|error|thing)",
+  "revert(ed|ing)?\\b",
+  "that'?s (wrong|not right|incorrect)",
+  "without asking",
+  "never (do|again|clear|change|touch|delete|assume)",
+  "don'?t (just|ever|keep|do that)",
+  "i (didn'?t|never) (ask|say|want)",
+  "stop (doing|adding|using)",
+  "you (broke|removed|deleted|changed) ",
+  "not what i (asked|wanted|said)",
+].join("|"), "i");
+
+// Turns that are machinery, not the user speaking.
+const NOT_TYPED = [
+  /^<command-name>/,
+  /^<local-command/,
+  /^\[Request interrupted/,
+  /^<system-reminder>/,
+  /^Caveat: The messages below/,
+  /hook (success|feedback)/i,
+];
+
+/** Where Claude Code keeps a project's sessions. */
+function transcriptDir(projectDir) {
+  const encoded = path.resolve(projectDir).replace(/\//g, "-");
+  return path.join(os.homedir(), ".claude", "projects", encoded);
+}
+
+/** The text of one turn, whatever shape the record uses. */
+function turnText(record) {
+  const c = record && record.message && record.message.content;
+  if (typeof c === "string") return c;
+  if (!Array.isArray(c)) return "";
+  return c.filter((b) => b && b.type === "text").map((b) => b.text || "").join("\n");
+}
+
+/**
+ * The funnel. Returns every complaint-shaped thing the user typed, newest
+ * session first. A session that cannot be read is skipped and NAMED.
+ */
+function readTranscripts(projectDir, maxSessions) {
+  const dir = transcriptDir(projectDir);
+  if (!fs.existsSync(dir)) {
+    return { present: false, why: `no session history at ${dir}` };
+  }
+
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch (e) {
+    throw new Unreadable(`${dir} exists but could not be listed: ${e.message}`);
+  }
+  if (!names.length) return { present: false, why: `no sessions recorded in ${dir}` };
+
+  let files = names
+    .map((f) => {
+      const full = path.join(dir, f);
+      return { full, mtime: fs.statSync(full).mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime)
+    .map((x) => x.full);
+
+  if (maxSessions > 0 && files.length > maxSessions) files = files.slice(0, maxSessions);
+
+  const complaints = [];
+  const skipped = [];
+  const stats = { sessions: files.length, rawBytes: 0, userTurns: 0, afterPaste: 0, matched: 0 };
+
+  for (const file of files) {
+    let raw;
+    try {
+      stats.rawBytes += fs.statSync(file).size;
+      raw = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      // Sanctioned: one bad session does not block the rewrite, but it is named
+      // here and reported to the user. Never silent.
+      skipped.push({ session: path.basename(file, ".jsonl"), why: e.message });
+      continue;
+    }
+
+    const session = path.basename(file, ".jsonl");
+    for (const line of raw.split("\n")) {
+      if (!line) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch (_) { continue; } // a half-written last line
+      if (!rec || rec.type !== "user" || rec.isSidechain || rec.isMeta) continue;
+
+      const text = turnText(rec).trim();
+      if (!text) continue;
+      stats.userTurns++;
+
+      if (text.length > PASTE_THRESHOLD) continue;   // pasted, not typed
+      if (NOT_TYPED.some((re) => re.test(text))) continue;
+      stats.afterPaste++;
+
+      if (!COMPLAINT.test(text)) continue;
+      stats.matched++;
+
+      complaints.push({
+        session,
+        when: rec.timestamp || null,
+        branch: rec.gitBranch || null,
+        text: text.length > 600 ? text.slice(0, 600) + "…" : text,
+      });
+    }
+  }
+
+  return { present: true, complaints, skipped, stats };
+}
+
+/** Decision-log entries — already curated, much smaller. */
+function readDecisionLog(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "progress.md");
+  if (!fs.existsSync(p)) return { present: false, why: "no .gsd-t/progress.md" };
+
+  let text;
+  try {
+    text = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new Unreadable(`progress.md exists but could not be read: ${e.message}`);
+  }
+
+  const start = text.indexOf("## Decision Log");
+  if (start === -1) return { present: false, why: "progress.md has no Decision Log section" };
+
+  // A date stamp carries a time and a zone — "2026-08-05 21:15 PDT: [debug] …" —
+  // so the colon that ends it is the one AFTER the zone, not the first one on
+  // the line. Matching the first colon finds nothing.
+  const entries = [];
+  for (const line of text.slice(start).split("\n")) {
+    const m = line.match(/^-\s+(\d{4}-\d{2}-\d{2}(?:\s+[\d:]+)?(?:\s+[A-Z]{2,5})?)\s*:\s*(.+)$/);
+    if (!m) continue;
+    entries.push({ when: m[1], text: m[2].length > 400 ? m[2].slice(0, 400) + "…" : m[2] });
+  }
+  return { present: true, entries };
+}
+
+/**
+ * Files fixed the same way repeatedly. A file that keeps being fixed is a rule
+ * nobody wrote down — and this works when there are no transcripts at all.
+ */
+function readGit(projectDir) {
+  const git = (args) => execFileSync("git", ["-C", projectDir, ...args], {
+    encoding: "utf8", timeout: 20000, maxBuffer: 32 * 1024 * 1024,
+  });
+
+  if (!fs.existsSync(path.join(projectDir, ".git"))) {
+    return { present: false, why: "not a git repository" };
+  }
+
+  let commits, branch;
+  try {
+    commits = parseInt(git(["rev-list", "--count", "HEAD"]).trim(), 10);
+    branch = git(["branch", "--show-current"]).trim();
+  } catch (e) {
+    throw new Unreadable(`.git exists but git could not read it: ${e.message}`);
+  }
+
+  // A real revert says so at the start of its subject. Matching "broke" or a
+  // bare "revert" anywhere pulled in 20 ordinary commits on binvoice — every
+  // one a false positive, which buries the handful that are real.
+  let reverts;
+  try {
+    reverts = git(["log", "--oneline", "-i", "--grep=^revert", "--grep=^chore: revert", "--grep=reverts commit", "-n", "40"])
+      .split("\n").filter(Boolean).slice(0, 20);
+  } catch (e) {
+    throw new Unreadable(`git log failed while looking for reverts: ${e.message}`);
+  }
+
+  let hotFiles;
+  try {
+    const counts = {};
+    const out = git(["log", "-i", "--name-only", "--pretty=format:", "--grep=fix", "-n", "300"]);
+    for (const f of out.split("\n")) {
+      const name = f.trim();
+      if (!name) continue;
+      counts[name] = (counts[name] || 0) + 1;
+    }
+    hotFiles = Object.entries(counts)
+      .filter(([, n]) => n >= 3)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 12)
+      .map(([file, fixes]) => ({ file, fixes }));
+  } catch (e) {
+    throw new Unreadable(`git log failed while looking for repeatedly-fixed files: ${e.message}`);
+  }
+
+  return { present: true, commits, branch, reverts, hotFiles };
+}
+
+function parseArgs(argv) {
+  const args = { project: process.cwd(), sessions: 0 };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--project") args.project = argv[++i];
+    else if (a === "--sessions") args.sessions = parseInt(argv[++i], 10) || 0;
+  }
+  return args;
+}
+
+function halt(message, asJson) {
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ ok: false, exitCode: EXIT_UNREADABLE, halt: message }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`[gsd-t] ${message}\n`);
+  }
+  process.exit(EXIT_UNREADABLE);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const projectDir = path.resolve(args.project);
+  const asJson = args.json || !process.stdout.isTTY;
+
+  if (!fs.existsSync(projectDir)) halt(`No such directory: ${projectDir}`, asJson);
+
+  const started = Date.now();
+
+  // A source that exists but cannot be read HALTS. Reporting it as "not
+  // available" would produce a thinner CLAUDE.md that looks complete.
+  let git, log, sessions;
+  try {
+    git = readGit(projectDir);
+    log = readDecisionLog(projectDir);
+    sessions = readTranscripts(projectDir, args.sessions);
+  } catch (e) {
+    if (e instanceof Unreadable) {
+      halt(
+        `${e.message}\n\nThis source exists, so its contents belong in the rewrite. ` +
+        `Continuing would produce a CLAUDE.md that looks complete but isn't.`,
+        asJson
+      );
+    }
+    throw e;
+  }
+
+  // Every source says whether it was there, so a thin result can never be
+  // mistaken for "this project has no history."
+  const sources = {
+    git: git.present ? `${git.commits} commits` : `none — ${git.why}`,
+    decisionLog: log.present ? `${log.entries.length} entries` : `none — ${log.why}`,
+    sessions: sessions.present
+      ? `${sessions.stats.sessions} sessions, ${sessions.stats.matched} things worth reading`
+      : `none — ${sessions.why}`,
+  };
+
+  const anything = git.present || log.present || sessions.present;
+
+  const result = {
+    ok: anything,
+    exitCode: anything ? EXIT_OK : EXIT_NO_HISTORY,
+    project: path.basename(projectDir),
+    sources,
+    tookMs: Date.now() - started,
+    git: git.present ? git : null,
+    decisionLog: log.present ? log.entries.slice(0, 40) : null,
+    complaints: sessions.present ? sessions.complaints : null,
+    skippedSessions: sessions.present ? sessions.skipped : [],
+    funnel: sessions.present ? sessions.stats : null,
+  };
+
+  if (!anything) {
+    result.halt = "No history at all. Do not write a thinner CLAUDE.md and call it normal — ask the user how to proceed.";
+  }
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    process.stdout.write(`History for ${result.project}\n\n`);
+    for (const [k, v] of Object.entries(sources)) process.stdout.write(`  ${k.padEnd(13)} ${v}\n`);
+    if (result.skippedSessions.length) {
+      process.stdout.write(`\n  ${result.skippedSessions.length} session(s) could NOT be read:\n`);
+      for (const s of result.skippedSessions) process.stdout.write(`    ${s.session} — ${s.why}\n`);
+    }
+    if (sessions.present) {
+      const s = sessions.stats;
+      process.stdout.write(`\n  ${(s.rawBytes / 1e6).toFixed(0)} MB raw → ${s.userTurns} typed → ${s.afterPaste} after dropping pastes → ${s.matched} worth reading\n`);
+    }
+    if (result.complaints && result.complaints.length) {
+      process.stdout.write(`\nWhat kept going wrong:\n\n`);
+      for (const c of result.complaints.slice(0, 15)) {
+        process.stdout.write(`  ${(c.when || "").slice(0, 10)}  ${c.text.replace(/\s+/g, " ").slice(0, 110)}\n`);
+      }
+    }
+    if (git.present && git.hotFiles.length) {
+      process.stdout.write(`\nFiles fixed repeatedly:\n`);
+      for (const h of git.hotFiles.slice(0, 8)) process.stdout.write(`  ${h.fixes}×  ${h.file}\n`);
+    }
+    process.stdout.write(`\n(${result.tookMs} ms)\n`);
+  }
+  process.exit(result.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { readTranscripts, readDecisionLog, readGit, transcriptDir, COMPLAINT, turnText, Unreadable };

package/bin/gsd-t-rule-mine.cjs

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-rule-mine.cjs
+ *
+ * M109-D2 — Finds every rule already stated in a project, so David can tick the
+ * ones that can never be broken instead of trying to recall them.
+ *
+ * [RULE] rule-mine-never-invents-a-rule
+ * [RULE] rule-mine-shows-where-each-came-from
+ * [RULE] rule-mine-keeps-what-it-cannot-rank
+ *
+ * Six sources, best evidence first. A rule found in three places ranks top —
+ * repetition IS the evidence.
+ *
+ * Every rule carries where it came from. That column is what makes the list
+ * fast to read: David is confirming something he already said, not recalling it.
+ *
+ * ─── Usage ──────────────────────────────────────────────────────────────────
+ *   node gsd-t-rule-mine.cjs --project <dir> [--json] [--top N]
+ *
+ * ─── Exit codes ─────────────────────────────────────────────────────────────
+ *   0  found rules
+ *   4  found none — the caller must ask, never write a rules section anyway
+ *   64 a source exists but could not be read
+ *
+ * Zero dependencies.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const EXIT_OK = 0;
+const EXIT_NONE = 4;
+const EXIT_UNREADABLE = 64;
+
+const DEFAULT_TOP = 12;   // more than this on screen has already failed
+
+/** Thrown when a source exists but cannot be read. Never treated as absent. */
+class Unreadable extends Error {}
+
+/**
+ * Lines that state a rule. Deliberately broad — a rule wrongly included costs
+ * one glance, a rule missed costs a broken build.
+ */
+const RULE_SHAPE = new RegExp([
+  "\\bnever\\b",
+  "\\balways\\b",
+  "\\bmust (not |never )?\\b",
+  "\\bdo not\\b|\\bdon'?t\\b",
+  "\\bforbidden\\b|\\bbanned\\b|\\bprohibited\\b",
+  "\\brequired\\b|\\bmandatory\\b",
+  "\\bonly ever\\b|\\bunder no circumstances\\b",
+  "\\bread-?only\\b",
+  "\\bno-?fallback\\b",
+].join("|"), "i");
+
+// Prose that mentions a rule without being one.
+const NOT_A_RULE = [
+  /^#{1,6}\s/,                     // a heading
+  /^\|.*\|.*\|/,                   // a table row
+  /^\s*```/,
+  /^\s*[-*]\s*\[[ x]\]/i,          // a checklist item
+  /\bfor example\b|\be\.g\.\b/i,
+  /^\s*<!--/,
+];
+
+function clean(line) {
+  return line
+    .replace(/^\s*[-*+]\s+/, "")
+    .replace(/^\s*\d+\.\s+/, "")
+    .replace(/\*\*/g, "")
+    .replace(/`/g, "")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .trim();
+}
+
+/**
+ * The claim a rule makes, stripped of wording, so the same rule stated three
+ * different ways collapses to one entry.
+ */
+function claimKey(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 3 && !STOP.has(w))
+    .sort()
+    .slice(0, 8)
+    .join(" ");
+}
+
+const STOP = new Set([
+  "never", "always", "must", "should", "would", "could", "does", "this", "that",
+  "with", "from", "into", "when", "what", "which", "have", "been", "will",
+  "they", "them", "then", "than", "your", "yours", "make", "made", "only",
+  "ever", "under", "unless", "because", "there", "their", "these", "those",
+]);
+
+/**
+ * A fragment is a piece of a sentence torn out of a paragraph — "domain never
+ * opens orders.ts.", "empty/flagged), never javascript:/data:.". It reads as a
+ * rule to a pattern but tells a human nothing they can act on, and it buries
+ * the real rules. A rule must start like a sentence and stand on its own.
+ */
+function isFragment(t) {
+  if (/^[a-z]/.test(t)) return true;               // starts mid-sentence
+  if (/^[>)\]}]/.test(t)) return true;             // a quote or a stray bracket
+  if (/^(and|but|or|so|then|which|that|where|when)\b/i.test(t)) return true;
+  if (/[([{]/.test(t) && !/[)\]}]/.test(t)) return true;  // an unclosed bracket
+  if (/:$/.test(t)) return true;                   // a label, not a rule
+  const words = t.split(/\s+/).length;
+  return words < 4;
+}
+
+function push(out, text, source, detail) {
+  const t = clean(text);
+  if (t.length < 15 || t.length > 300) return;
+  if (!RULE_SHAPE.test(t)) return;
+  if (NOT_A_RULE.some((re) => re.test(text))) return;
+  if (isFragment(t)) return;
+  out.push({ text: t, source, detail: detail || "" });
+}
+
+/** Read a file, or throw. An unreadable source is never reported as absent. */
+function readOr(p, label) {
+  try {
+    return fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new Unreadable(`${label} exists but could not be read: ${e.message}`);
+  }
+}
+
+/** 1. Contracts — already written as rules, with their reasons. */
+function fromContracts(projectDir, found) {
+  const dir = path.join(projectDir, ".gsd-t", "contracts");
+  if (!fs.existsSync(dir)) return { present: false };
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    throw new Unreadable(`${dir} exists but could not be listed: ${e.message}`);
+  }
+  let n = 0;
+  for (const name of names) {
+    const text = readOr(path.join(dir, name), name);
+    for (const line of text.split("\n")) {
+      const before = found.length;
+      push(found, line, "contract", name.replace(/\.md$/, ""));
+      if (found.length > before) n++;
+    }
+  }
+  return { present: true, count: n, files: names.length };
+}
+
+/**
+ * A rule announced by its own heading — "## The Inviolable Rule (HC-005) —
+ * NEVER scan the whole page". These are the rules that matter most, and reading
+ * line-by-line misses them entirely: the heading states the rule and the
+ * paragraph beneath explains it.
+ */
+const RULE_HEADING = /^#{2,4}\s+(.*(?:inviolable|hard rule|hc-\d+|never|must not|forbidden|non-goal|do not).*)$/i;
+
+function fromHeadings(text, found, source, detail) {
+  let n = 0;
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(RULE_HEADING);
+    if (!m) continue;
+    // The heading is the rule. Strip the section marker and any id in brackets,
+    // then keep the part that states the requirement.
+    let t = clean(m[1]).replace(/^The Inviolable Rule\s*/i, "").replace(/^\(([^)]+)\)\s*[—-]?\s*/, "");
+    const id = (m[1].match(/HC-\d+/i) || [])[0] || "";
+    if (t.length < 8) {
+      // The heading is only an id — the rule is the first real line beneath it.
+      for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+        const c = clean(lines[j]);
+        if (c.length > 20 && !/^#{1,6}\s/.test(lines[j])) { t = c; break; }
+      }
+    }
+    if (t.length < 15) continue;
+    found.push({
+      text: t.length > 200 ? t.slice(0, 200) + "…" : t,
+      source,
+      detail: id || detail || "",
+      heading: true,
+    });
+    n++;
+  }
+  return n;
+}
+
+/** 2. The existing CLAUDE.md, minus anything restating a global rule. */
+function fromClaudeMd(projectDir, found, globalText) {
+  const p = path.join(projectDir, "CLAUDE.md");
+  if (!fs.existsSync(p)) return { present: false };
+  const text = readOr(p, "CLAUDE.md");
+
+  // Headed rules first — these are the ones that matter.
+  let n = fromHeadings(text, found, "existing CLAUDE.md", "");
+
+  let restated = 0;
+  for (const line of text.split("\n")) {
+    const t = clean(line);
+    if (globalText && t.length > 40 && globalText.includes(t)) { restated++; continue; }
+    const before = found.length;
+    push(found, line, "existing CLAUDE.md", "");
+    if (found.length > before) n++;
+  }
+  return { present: true, count: n, restatedFromGlobal: restated };
+}
+
+/** 3. [RULE] markers in the pseudocode docs — machine-findable by design. */
+function fromPseudocode(projectDir, found) {
+  const dir = path.join(projectDir, ".gsd-t", "pseudocode");
+  if (!fs.existsSync(dir)) return { present: false };
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    throw new Unreadable(`${dir} exists but could not be listed: ${e.message}`);
+  }
+  let n = 0;
+  for (const name of names) {
+    const text = readOr(path.join(dir, name), name);
+    for (const line of text.split("\n")) {
+      if (!/\[RULE\]/.test(line)) continue;
+      const t = clean(line.replace(/\[RULE\]\s*/, "").replace(/-/g, " "));
+      if (t.length < 10) continue;
+      found.push({ text: t, source: "pseudocode", detail: name.replace(/^PseudoCode-|\.md$/g, "") });
+      n++;
+    }
+  }
+  return { present: true, count: n };
+}
+
+/** 4. A project-local hook is a rule somebody already enforced in code. */
+function fromHooks(projectDir, found) {
+  const p = path.join(projectDir, ".claude", "settings.json");
+  if (!fs.existsSync(p)) return { present: false };
+  const raw = readOr(p, ".claude/settings.json");
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch (e) {
+    throw new Unreadable(`.claude/settings.json exists but is not valid JSON: ${e.message}`);
+  }
+  let n = 0;
+  for (const [event, arr] of Object.entries((settings && settings.hooks) || {})) {
+    for (const m of arr || []) {
+      for (const h of (m.hooks || [])) {
+        const cmd = h.command || "";
+        const script = (cmd.match(/([\w-]+)\.(?:js|cjs|sh)/) || [])[1];
+        if (!script) continue;
+        // A project-local guard names the rule it enforces; only its own count.
+        if (!cmd.includes(projectDir) && !cmd.includes("./")) continue;
+        found.push({
+          text: `Enforced by a hook on ${event}: ${script.replace(/-/g, " ")}`,
+          source: "project hook",
+          detail: script,
+        });
+        n++;
+      }
+    }
+  }
+  return { present: true, count: n };
+}
+
+/** 5. Decision-log entries recording a directive from the user. */
+function fromDecisionLog(projectDir, found) {
+  const p = path.join(projectDir, ".gsd-t", "progress.md");
+  if (!fs.existsSync(p)) return { present: false };
+  const text = readOr(p, "progress.md");
+  const start = text.indexOf("## Decision Log");
+  if (start === -1) return { present: false };
+  let n = 0;
+  for (const line of text.slice(start).split("\n")) {
+    if (!/^-\s+\d{4}-\d{2}-\d{2}/.test(line)) continue;
+    if (!/USER DIRECTIVE|hard rule|David'?s (call|ruling|decision)|never again/i.test(line)) continue;
+    // Take the sentence that states the rule, not the whole entry.
+    const sentences = line.split(/(?<=[.!?])\s+/);
+    for (const s of sentences) {
+      const before = found.length;
+      push(found, s, "decision log", (line.match(/^-\s+(\d{4}-\d{2}-\d{2})/) || [])[1] || "");
+      if (found.length > before) { n++; break; }
+    }
+  }
+  return { present: true, count: n };
+}
+
+/** 6. Files fixed the same way repeatedly — a rule nobody wrote down. */
+function fromGit(projectDir, found) {
+  if (!fs.existsSync(path.join(projectDir, ".git"))) return { present: false };
+  let out;
+  try {
+    out = execFileSync("git", ["-C", projectDir, "log", "-i", "--name-only",
+      "--pretty=format:", "--grep=fix", "-n", "300"],
+      { encoding: "utf8", timeout: 20000, maxBuffer: 32 * 1024 * 1024 });
+  } catch (e) {
+    throw new Unreadable(`.git exists but git log failed: ${e.message}`);
+  }
+  const counts = {};
+  for (const f of out.split("\n")) {
+    const name = f.trim();
+    if (!name) continue;
+    counts[name] = (counts[name] || 0) + 1;
+  }
+  const hot = Object.entries(counts).filter(([, n]) => n >= 5)
+    .sort((a, b) => b[1] - a[1]).slice(0, 6);
+  for (const [file, fixes] of hot) {
+    found.push({
+      text: `Changes to ${file} are riskier than they look — fixed ${fixes} times`,
+      source: "git",
+      detail: `${fixes} fixes`,
+    });
+  }
+  return { present: true, count: hot.length };
+}
+
+/**
+ * Collapse the same rule stated in several places into one entry, keeping the
+ * clearest wording and merging where it came from. Rank by how many DIFFERENT
+ * sources agree — repetition is the evidence.
+ */
+function merge(found) {
+  const byClaim = new Map();
+  for (const r of found) {
+    const key = claimKey(r.text);
+    if (!key) continue;
+    if (!byClaim.has(key)) {
+      byClaim.set(key, { text: r.text, sources: new Map() });
+    }
+    const entry = byClaim.get(key);
+    // A rule that had its own heading is the authoritative wording — it beats a
+    // sentence found mid-paragraph, whatever the lengths.
+    if (r.heading && !entry.heading) { entry.text = r.text; entry.heading = true; }
+    else if (!entry.heading && r.text.length < entry.text.length && r.text.length > 25) entry.text = r.text;
+
+    if (!entry.sources.has(r.source)) entry.sources.set(r.source, []);
+    const list = entry.sources.get(r.source);
+    if (r.detail && !list.includes(r.detail)) list.push(r.detail);
+  }
+
+  return [...byClaim.values()]
+    .map((e) => ({
+      text: e.text,
+      seenIn: [...e.sources.entries()].map(([s, d]) => (d.length ? `${s} (${d.slice(0, 2).join(", ")})` : s)),
+      sourceCount: e.sources.size,
+      heading: !!e.heading,
+      // A rule stated as a whole sentence beats a fragment. "Consumers
+      // (read-only):" is a table header, not a rule anybody can act on.
+      wellFormed: /\s(never|always|must|do not|don't|only|no)\s/i.test(e.text) && !/:$/.test(e.text),
+    }))
+    .sort((a, b) =>
+      (Number(b.heading) - Number(a.heading)) ||
+      (Number(b.wellFormed) - Number(a.wellFormed)) ||
+      (b.sourceCount - a.sourceCount) ||
+      (a.text.length - b.text.length));
+}
+
+function parseArgs(argv) {
+  const args = { project: process.cwd(), top: DEFAULT_TOP };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--project") args.project = argv[++i];
+    else if (a === "--top") args.top = parseInt(argv[++i], 10) || DEFAULT_TOP;
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const projectDir = path.resolve(args.project);
+  const asJson = args.json || !process.stdout.isTTY;
+
+  let globalText = "";
+  const globalPath = path.join(process.env.HOME || "", ".claude", "CLAUDE.md");
+  if (fs.existsSync(globalPath)) {
+    try { globalText = fs.readFileSync(globalPath, "utf8"); } catch (e) {
+      // The global file decides which project rules are mere restatements.
+      // Without it every restated rule would be listed as project-specific.
+      process.stdout.write(JSON.stringify({
+        ok: false, exitCode: EXIT_UNREADABLE,
+        halt: `The global CLAUDE.md exists at ${globalPath} but could not be read: ${e.message}. ` +
+              `Without it, rules copied from the global file would be listed as if this project invented them.`,
+      }, null, 2) + "\n");
+      process.exit(EXIT_UNREADABLE);
+    }
+  }
+
+  const found = [];
+  let sources;
+  try {
+    sources = {
+      contracts: fromContracts(projectDir, found),
+      claudeMd: fromClaudeMd(projectDir, found, globalText),
+      pseudocode: fromPseudocode(projectDir, found),
+      hooks: fromHooks(projectDir, found),
+      decisionLog: fromDecisionLog(projectDir, found),
+      git: fromGit(projectDir, found),
+    };
+  } catch (e) {
+    if (e instanceof Unreadable) {
+      const msg = `${e.message}\n\nThis source exists, so the rules in it belong in the list. ` +
+                  `Continuing would offer a list that looks complete but isn't.`;
+      if (asJson) process.stdout.write(JSON.stringify({ ok: false, exitCode: EXIT_UNREADABLE, halt: msg }, null, 2) + "\n");
+      else process.stderr.write(`[gsd-t] ${msg}\n`);
+      process.exit(EXIT_UNREADABLE);
+    }
+    throw e;
+  }
+
+  const rules = merge(found);
+  const shown = rules.slice(0, args.top);
+  const rest = rules.slice(args.top);
+
+  const result = {
+    ok: rules.length > 0,
+    exitCode: rules.length > 0 ? EXIT_OK : EXIT_NONE,
+    project: path.basename(projectDir),
+    sources: Object.fromEntries(Object.entries(sources).map(([k, v]) =>
+      [k, v.present ? `${v.count} found` : "none"])),
+    total: rules.length,
+    shown: shown.map((r, i) => ({ n: i + 1, ...r })),
+    remainder: rest.length,
+    remainderRules: rest,
+  };
+
+  if (!rules.length) {
+    result.halt = "No rules found anywhere in this project. Do not write a rules section — ask the user.";
+  }
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else if (!rules.length) {
+    process.stdout.write(`No rules found in ${result.project}.\n`);
+  } else {
+    process.stdout.write(`\n${shown.length} candidate rules for ${result.project}. `);
+    process.stdout.write(`Tick the ones that must NEVER be broken.\n\n`);
+    process.stdout.write(`     RULE${" ".repeat(62)}SEEN IN\n`);
+    shown.forEach((r, i) => {
+      const words = r.text.split(" ");
+      const lines = [];
+      let cur = "";
+      for (const w of words) {
+        if ((cur + " " + w).trim().length > 60) { lines.push(cur.trim()); cur = w; }
+        else cur += " " + w;
+      }
+      if (cur.trim()) lines.push(cur.trim());
+      const seen = r.seenIn.join(" + ");
+      process.stdout.write(`${String(i + 1).padStart(2)} [ ] ${lines[0].padEnd(62)}${seen}\n`);
+      for (const l of lines.slice(1)) process.stdout.write(`       ${l}\n`);
+    });
+    if (rest.length) {
+      process.stdout.write(`\n  (${rest.length} more written to .gsd-t/setup-rules-full.md — none dropped)\n`);
+    }
+    process.stdout.write(`\nTick numbers (e.g. 1,3,4) or 'all':\n`);
+  }
+  process.exit(result.exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { merge, claimKey, RULE_SHAPE, clean, Unreadable };

package/bin/gsd-t.js

@@ -1709,6 +1709,9 @@ const GLOBAL_BIN_TOOLS = [
   // M108 — Install self-check, run by the SessionStart hook and by
   // `gsd-t install-check`.
   "gsd-t-install-check.cjs",
+  // M109 — project-history reader + rule miner, used by /gsd-t-setup to write a
+  // project CLAUDE.md from what actually happened rather than from a template.
+  "gsd-t-project-history.cjs", "gsd-t-rule-mine.cjs",
 ];
 
 function installGlobalBinTools() {
@@ -3150,6 +3153,9 @@ const PROJECT_BIN_TOOLS = [
   // M108 — Install self-check. Every project carries its own copy so it can
   // verify and repair itself even when the global install is what broke.
   "gsd-t-install-check.cjs",
+  // M109 — project-history reader + rule miner, so /gsd-t-setup can write a
+  // project CLAUDE.md from what actually happened rather than from a template.
+  "gsd-t-project-history.cjs", "gsd-t-rule-mine.cjs",
   // M89 — Auto-research gate classifier (classify a guessed claim as internal vs external;
   // propagated to each registered project's bin/ so the workflow runCli fallback resolves
   // downstream — per [[project_global_bin_propagation_gap]]).

package/commands/gsd-t-setup.md

@@ -72,109 +72,133 @@ CLAUDE.md Analysis:
 
 Note: "No existing CLAUDE.md — will generate from scratch."
 
-## Step 4: Ask Targeted Questions
+## Step 3.5: Read what actually happened here
 
-Only ask what could NOT be auto-detected. Skip questions where the answer is already clear from scanning.
+Before writing anything, read the project's own history. A rule that keeps
+getting broken is the rule that most needs writing down, and nobody remembers
+those on request — they have to be found.
 
-**Potential questions** (ask only if not auto-detected):
+```bash
+node bin/gsd-t-project-history.cjs --project . --json
+```
 
-1. **Branch Guard**: "Which branch should commits target?" (skip if only `main` or `master` exists)
-2. **Autonomy Level**: "What autonomy level? Level 1 (Supervised), Level 2 (Standard), Level 3 (Full Auto — default)" (skip if existing CLAUDE.md already declares it)
-3. **Workflow Preferences**: "Any overrides to the global defaults? (Research Policy, Phase Flow)" (skip if user has no overrides)
-4. **Deployed URLs**: "Production, staging, and local URLs?" (skip if found in .env or existing docs)
-5. **Project-specific rules**: "Any 'never do' rules specific to this project?" (skip if existing CLAUDE.md already has them)
+Three sources, cheapest first. Each reports whether it was there; a missing one
+is **named**, never skipped in silence:
 
-**Do NOT ask about**:
-- Tech stack (auto-detected)
-- Naming conventions (auto-detected)
-- Testing framework (auto-detected)
-- File structure (auto-detected)
-- Anything already covered by the global CLAUDE.md
+| Source | What it gives |
+|---|---|
+| Git | Files fixed the same way repeatedly, and real reverts |
+| Decision log | Directives already recorded, with dates |
+| Past sessions | What the user typed when something kept going wrong |
 
-## Step 5: Generate CLAUDE.md
+Session history is large — one project holds 315 MB — so the tool funnels it:
+keep only the user's own turns, drop pasted logs, keep only complaint-shaped
+lines. Under a second, and the result fits in context.
 
-Build the file using this structure. Include only sections that have real content — omit empty sections entirely.
+**If it exits 4, there is no history at all.** Do not carry on and write a
+thinner file. Stop and ask:
 
-```markdown
-# {Project Name}
+```
+Sources found: git 67 commits | decision log 1 line | sessions 0 | contracts 0
+
+I can mine 0 rules from this project's history.
+
+  a) Write stack and commands only — the rules section left out, with the
+     reason written into the file. Not a normal CLAUDE.md.
+  b) You dictate the rules now.
+  c) Stop.
+```
+
+Whichever they pick, the gap goes **into the generated file** — "Rules: none
+derivable, no project history" — so thinness stays visible rather than reading
+as "this project has no rules."
 
-## Branch Guard
-**Expected branch**: {branch}
+## Step 4: Show the rules found, and let the user tick them
 
-## Project Overview
-{Brief description — what problem does this solve and for whom?}
+Do **not** ask the user to recall rules. Mine every rule the project already
+states, and let them confirm:
 
-### Architecture
-{High-level architecture summary if the project has one — e.g., "Three-tier WebSocket bridge" with a diagram. Keep it concise. Details belong in docs/architecture.md}
+```bash
+node bin/gsd-t-rule-mine.cjs --project . --top 12
+```
+
+Six sources, ranked by how many agree — a rule found in three places ranks top,
+because repetition is the evidence. The output is a tick-list:
+
+```
+12 candidate rules for binvoice. Tick the ones that must NEVER be broken.
 
-## Where Things Live
+     RULE                                                    SEEN IN
+ 1 [ ] NEVER contact the buyer directly                      CLAUDE.md (HC-003)
+ 2 [ ] TEXT-FIRST capture (enforced by a pre-write gate)     CLAUDE.md (HC-004)
+ 3 [ ] NEVER scan the whole page                             CLAUDE.md (HC-005)
 
-| Need to find... | Look here |
-|-----------------|-----------|
-| {component} | {path} |
+Tick numbers (e.g. 1,3,4) or 'all':
+```
 
-## Key Technologies
-{Bulleted list of language, framework, database, testing, etc.}
+The right-hand column is what makes this fast — the user is confirming
+something they already said, not recalling it. **Cap the screen at 12.**
+Anything below goes to `.gsd-t/setup-rules-full.md`; nothing is dropped.
 
-## Documentation
-- Requirements: docs/requirements.md
-- Architecture: docs/architecture.md
-- Workflows: docs/workflows.md
-- Infrastructure: docs/infrastructure.md
+**Never invent a rule.** Every one comes from somewhere in the project, and the
+tick-list shows where. A rule the user did not tick is not inviolable — it may
+still belong elsewhere in the file, but not in that section.
 
-## Autonomy Level
-**Level {N} — {Name}** ({description})  <!-- default: Level 3 — Full Auto -->
+**Determine these by reading, never by asking:**
 
-## Workflow Preferences
-<!-- Override global defaults. Delete what you don't need to override. -->
+| | How |
+|---|---|
+| Which branch | `git branch --show-current` |
+| Where the repo misleads | Two version fields disagreeing, a legacy path that still looks live |
+| Which files are dangerous | Fixed 5+ times in the git history |
+| Stack, build, test | The manifest |
 
-### Research Policy
-{project-specific overrides, or omit section}
+**Ask only if genuinely unresolvable:** the autonomy level when no existing
+CLAUDE.md declares one, and deployed URLs when nothing records them.
 
-### Phase Flow
-{project-specific overrides, or omit section}
+## Step 5: Generate CLAUDE.md
 
-## Testing
-{Framework, file organization, naming, running instructions}
+Use the mold at `templates/CLAUDE-project.md`. It is a real mold — do NOT copy
+any existing project's file, and never GSD-T's own.
 
-## Code Patterns to Follow
-{Project-specific conventions that differ from or extend global defaults}
+**Every section may be left out, with the reason stated. None may be padded.**
 
-### Naming Conventions
-{If different from global defaults}
+| Section | Include when | Fill from |
+|---|---|---|
+| Title + one-line what-this-is | Always | The manifest, the README |
+| **Rules that can never be broken** | The user ticked at least one | Step 4's tick-list, verbatim |
+| Where the repo misleads you | Reading the code gives a confident wrong answer | Determined, never asked |
+| Files riskier than they look | Some file was fixed 5+ times | Git history |
+| Where this differs from global | A genuine difference exists | Compared against `~/.claude/CLAUDE.md` |
+| Stack and commands | Always | The manifest |
+| Where things are written down | Always | Fixed pointers |
 
-## Running the App
-{Dev server, build commands, first-time setup}
+**Target 40–70 lines.** If it is longer, something in it is either restating a
+global rule or repeating what the repo already says.
 
-## Environment Variables
-| Variable | Purpose | Default |
-|----------|---------|---------|
-| {VAR} | {purpose} | {default} |
+### What must never appear
 
-## Deployed URLs
-- **Production**: {url}
-- **Staging**: {url}
-- **Local**: http://localhost:{port}
+| Never | Why |
+|---|---|
+| Anything the global file already says | Three projects each paste the entire Destructive Action Guard verbatim — 15 wasted lines apiece |
+| Anything a hook or gate enforces | The machine does not read this file |
+| A version number, a line count, "currently in progress" | Wrong within a week. It belongs in `progress.md` |
+| A file listing, a dependency list, a command count | The repo answers it, and answers it currently |
+| A rule nobody stated | Every rule comes from the tick-list, and the tick-list shows its source |
 
-## Don't Do These Things
-{Project-specific rules only — don't repeat global rules}
+### The line that matters most
 
-## GSD-T Workflow
-This project uses contract-driven development.
-- State: .gsd-t/progress.md
-- Contracts: .gsd-t/contracts/
-- Domains: .gsd-t/domains/
+A rule states **what must never happen and what breaks if it does**. If it is
+enforced by a hook or a gate, say so — the reader should know a machine is
+watching:
 
-## Current Status
-See `.gsd-t/progress.md` for current milestone/phase state.
+```
+- **Never touch facebook.com** — no permissions, no requests, no DOM writes.
+  A single write turns a read-only observer into an actor on someone else's
+  account. Enforced by a pre-write gate.
 ```
 
-### Section Rules:
-- **NEVER duplicate** global CLAUDE.md content (Destructive Action Guard, Pre-Commit Gate, Prime Directives, etc.)
-- **ALWAYS include**: Branch Guard, GSD-T Workflow, Current Status
-- **Include if relevant**: Where Things Live, Testing, Code Patterns, Environment Variables
-- **Omit if empty**: Deployed URLs (if not deployed), Architecture (if trivial), Workflow Preferences (if no overrides)
-
+Not: *"Be careful with Facebook interactions."*
 ## Step 5.5: Quality North Star Configuration
 
 After generating the CLAUDE.md content (Step 5) and before presenting it to the user, offer a Quality North Star section if one is not already present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.9.10",
+  "version": "5.10.10",
   "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-project.md

@@ -1,127 +1,70 @@
-# GSD-T Framework (@tekyzinc/gsd-t)
+# {PROJECT_NAME}
 
-Prime Directives, core guards, and workflow rules live in `~/.claude/CLAUDE.md`. This file covers what's specific to this repo.
+{ONE_LINE_WHAT_THIS_IS}
 
-## Overview
+> Everything general lives in `~/.claude/CLAUDE.md` and applies here. This file
+> holds only what is true of this project and nothing else.
 
-Contract-driven development methodology for Claude Code. npm package providing slash commands, a CLI installer, templates, and stack rules for reliable parallelizable AI-assisted development.
+## Rules that can never be broken
 
-## Autonomy Level
+<!--
+  Ticked by David from what the project already says. Nothing invented, nothing
+  copied from the global file. If a rule is enforced by a hook or a gate, say so
+  — the reader should know a machine is watching.
 
-> Overrides global: pins the default from `~/.claude/CLAUDE.md` § Autonomy Levels.
+  Leave this section out entirely if none were found, and say why.
+-->
+{RULES}
 
-**Level 3 — Full Auto**. Only pause for blockers, destructive actions, or project completion.
+## Where the repo misleads you
 
-## Tech Stack
+<!--
+  Only where reading the code gives a confident WRONG answer — two version
+  fields disagreeing, a legacy path that still looks live, a config that is not
+  the one in use. Leave out if none.
+-->
+{MISLEADS}
 
-- **Language**: JavaScript (Node.js >= 16), zero external runtime deps for the installer
-- **Distribution**: npm package `@tekyzinc/gsd-t`
-- **CLI**: `bin/gsd-t.js` (install, update, init, status, uninstall, doctor, graph, headless, …)
-- **Testing**: `npm test` (Node built-in test runner) + manual CLI testing
+## Files that are riskier than they look
 
-## Project Structure
+<!--
+  Determined by reading, never asked. A file fixed the same way five times is a
+  rule nobody wrote down. Say what breaks, not just which file. Leave out if none.
+-->
+{DANGER_MAP}
 
-```
-bin/                     — CLI entry (gsd-t.js) + orchestrators (orchestrator.js, design-orchestrator.js)
-                           + support modules (gsd-t-context-brief.cjs, cli-preflight.cjs, gsd-t-verify-gate.cjs, gsd-t-model-tier-policy.cjs, …)
-commands/                — slash commands for Claude Code (GSD-T workflow + utility)
-templates/               — document + prompt + stack templates
-  CLAUDE-{global,project}.md, requirements.md, architecture.md, workflows.md,
-  infrastructure.md, progress.md, backlog.md, backlog-settings.md, design-contract.md
-  prompts/               — validation subagent protocols (qa, red-team, design-verify)
-  stacks/                — Stack Rules Engine templates (injected at spawn time)
-scripts/                 — runtime scripts (design review, context meter hook, event writer)
-examples/                — example project structure + settings
-docs/methodology.md      — GSD → GSD-T evolution and concepts
-package.json, README.md, GSD-T-README.md, CHANGELOG.md
-```
+## Where this differs from the global rules
 
-Exact command list: `ls commands/`. Exact stack rule set: `ls templates/stacks/`. Don't hand-maintain counts in docs.
+<!-- ONLY genuine differences. An empty table means there are none — leave it out. -->
 
-## Meta-Project Notes
+| Global default | Here | Why |
+|---|---|---|
+{OVERRIDES}
 
-- The "source" is the `.md` files in `commands/` + `templates/` and the JS in `bin/` + `scripts/`. There is no `src/`.
-- Changes to command files change the methodology itself — treat them as code; verify by running the workflow.
-- The `.gsd-t/` state dir coexists with the commands that *define* `.gsd-t/` — intentional.
-- `bin/gsd-t.js` is the primary testable surface; command files are validated by use.
+## Stack and commands
 
-## Conventions
+{STACK}
 
-**CLI** — ANSI colors via escape codes, zero external deps, sync file APIs, version tracked in `package.json` and `~/.claude/.gsd-t-version`.
+| | |
+|---|---|
+| Build | `{BUILD_CMD}` |
+| Test | `{TEST_CMD}` |
+| Branch | `{BRANCH}` |
 
-**Command files** — pure markdown, no frontmatter, accept `$ARGUMENTS`, step-numbered, thin Workflow invokers (`Workflow({scriptPath, args})`). Include a Document Ripple section listing files the underlying Workflow expects domain workers to update. Validation protocol bodies stay in `templates/prompts/*-subagent.md`; Workflow scripts load them via `_lib.loadProtocol(name)`. Don't inline the protocol.
+## Where things are written down
 
-**Templates** — `{Project Name}`, `{Date}`, `{description}` replacement tokens; tables for structured data.
+| | |
+|---|---|
+| State and decisions | `.gsd-t/progress.md` |
+| Interfaces between parts | `.gsd-t/contracts/` |
+| How to reach environments | `docs/infrastructure.md` |
 
-**Directory structure** — `.gsd-t/contracts/` (domain interfaces), `.gsd-t/domains/{name}/` (scope/tasks/constraints), `.gsd-t/milestones/` (archives), `.gsd-t/scan/` (analysis outputs).
+<!--
+  Written {GENERATED_DATE} from this project's own history.
 
-**Publishing** — after `npm publish`, ALWAYS run `/gsd-t-version-update-all` to propagate to registered projects.
+  Nothing above should carry a number that changes on its own — no version, no
+  line count, no "currently in progress". Those belong in progress.md, and a
+  file that repeats them is wrong within a week.
 
-## GSD-T Workflows (M61 — v4.0.10+)
-
-Phase orchestration lives in `templates/workflows/`. Each command file (`commands/gsd-t-*.md`) is a thin invoker that calls `Workflow({scriptPath, args})`. Canonical scripts:
-
-- `gsd-t-execute.workflow.js` — preflight → brief → file-disjointness → parallel(domain workers) → integrate → verify-gate
-- `gsd-t-verify.workflow.js` — orthogonal triad with M57 CI-parity + M58 test-data purge as FAIL-blocking gates
-- `gsd-t-wave.workflow.js`, `-integrate`, `-debug`, `-quick`, `-phase` (generic upper-stage runner)
-
-Shared helpers: `templates/workflows/_lib.js`. Each helper prefers project-local `bin/<tool>.cjs` and falls back to global `gsd-t` PATH binary.
-
-The brains stay in `bin/`: `gsd-t-file-disjointness.cjs`, `gsd-t-task-graph.cjs`, `gsd-t-context-brief.cjs`, `cli-preflight.cjs`, `gsd-t-verify-gate.cjs`, `gsd-t-verify-gate-judge.cjs`, `gsd-t-build-coverage.cjs`, `gsd-t-ci-parity.cjs`, `gsd-t-test-data-ledger.cjs`, `journey-coverage.cjs`. Workflows invoke them via `lib.*` helpers.
-
-## Validation Protocols (KEPT — methodology layer)
-
-Three validation protocol bodies stay at `templates/prompts/`:
-- `qa-subagent.md` — test mechanics + shallow-test detection + contract compliance
-- `red-team-subagent.md` — adversarial / security / boundaries; verdict `FAIL` / `GRUDGING-PASS`
-- `design-verify-subagent.md` — visual MATCH/DEVIATION against the design contract
-
-These are invoked as Workflow `agent()` stages with schema-validated output. The methodology body is unchanged; only the invocation context (Workflow stage vs. Task subagent) updated. Per `.gsd-t/contracts/orthogonal-validation-contract.md` v1.0.0 STABLE.
-
-
-# Destructive Action Guard (MANDATORY)
-
-**NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels.
-
-Before any of these actions, STOP and ask the user:
-- DROP TABLE, DROP COLUMN, DROP INDEX, TRUNCATE, DELETE without WHERE
-- Renaming or removing database tables or columns
-- Schema migrations that lose data or break existing queries
-- Replacing an existing architecture pattern (e.g., normalized → denormalized)
-- Removing or replacing existing files/modules that contain working functionality
-- Changing ORM models in ways that conflict with the existing database schema
-- Removing API endpoints or changing response shapes that existing clients depend on
-- Any change that would require other parts of the system to be rewritten
-
-**Rule: "Adapt new code to existing structures, not the other way around."**
-
-## Pre-Commit Gate (project-specific additions)
-
-The global gate applies first (see `~/.claude/CLAUDE.md`). Additionally for this repo:
-
-- **Command file interface/behavior changed** → update `GSD-T-README.md` + `README.md` commands table + `templates/CLAUDE-global.md` + `commands/gsd-t-help.md`.
-- **Command added/removed** → update all 4 files above, bump `package.json`, update any command-counting logic in `bin/gsd-t.js`.
-- **New command invokes a Workflow** → verify `scriptPath` resolves to `templates/workflows/<name>.workflow.js` and `args` shape matches the script's `meta.phases`.
-- **CLI installer changed** → smoke test `install`, `update`, `status`, `doctor`, `init`, `uninstall`.
-- **Template changed** → verify `gsd-t-init` still produces correct output.
-- **Wave flow changed (phases added/removed/reordered)** → update `gsd-t-wave.md`, `GSD-T-README.md` wave diagram, `README.md` workflow section.
-- **Contract or domain boundary changed** → update `.gsd-t/contracts/` and owning `scope.md`.
-
-## Don't
-
-- NEVER add external npm runtime dependencies to the installer — zero-dep invariant.
-- NEVER rename a command without updating all 4 reference files above.
-- NEVER modify wave phase sequence without updating wave, README, GSD-T-README in the same commit.
-- NEVER let installer's command count diverge from `commands/` directory reality.
-- NEVER inline validation-subagent protocol bodies into Workflow scripts — `_lib.loadProtocol("qa"|"red-team"|"design-verify")` reads the methodology body from `templates/prompts/`.
-
-## Recovery After Interruption
-
-1. Read `.gsd-t/progress.md`
-2. Read `README.md` for what the package delivers
-3. Check `commands/` and `package.json` for current state
-4. Continue from current task; don't restart the phase
-
-## Current Status
-
-See `.gsd-t/progress.md`.
+  Regenerate with /gsd-t-setup.
+-->