@tekyzinc/gsd-t 5.7.10 → 5.9.10

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.9.10] - 2026-08-07
+
+### Added — projects repair their own install, and fallbacks need approval by name
+
+**Every registered project was running a broken install.** Binvoice had 20 of its 38 tools. The verify gate was a stale copy in all 33 projects, so every one of them has been running an outdated quality gate.
+
+The cause was one line: a tool missing from the package was skipped in silence, and the pass then reported "copied N tools" — where N looked fine. The report was the concealment. Two more copies of the same defect sat in the utility-script and template installers.
+
+**Install self-repair (M108).** Each session now checks its project's tools before any work starts, restores what is missing from the installed package, and refuses to continue if it cannot. Not a workaround: it fixes the failure, then the work proceeds with everything present. Every repair is logged to a shared file, and `gsd-t install-check --report` names any tool that has gone missing in more than one project — which points at the installer rather than the project. A per-project fix that also tells GSD-T what to mend in itself.
+
+- `bin/gsd-t-install-check.cjs`: reads the expected tool list from the installer (never a second copy that can go stale), compares, repairs, halts when it can't
+- `scripts/gsd-t-install-heal.js`: runs it at session start, first in the chain; silent when the install is already complete
+- `bin/gsd-t.js`: three silent skips now report every undelivered file; new `install-check` command
+- `test/m108-install-heal.test.js`: 12 tests, including one asserting the silent skip never comes back
+
+**Fallback gate (M106).** A fallback — anything that continues after a failure — can no longer be written unless it was approved by name. The rule has been written down since v5.0.14 and kept being broken: a lookup for a post's author failed, the code substituted the last known seller, and posts were recorded as written by someone who never wrote them. That shipped while the rule was live.
+
+Two things about the rule changed as a result. The damage is fabricated data **plus a disabled alarm** — author detection broke because a code change broke it, and the substitution meant nobody ever went looking. And consent must be specific: a fallback buried inside a long plan approved as a whole is not approved, because whoever wrote the plan controls the burying.
+
+Detection matches the shape of the code, not its wording, so rewording cannot evade it. It runs when code is written, when a plan is reviewed, before a commit, and on demand across existing code. A one-time baseline records what was already there so the gate judges new work only.
+
+- `bin/gsd-t-fallback-detect.cjs`, `scripts/gsd-t-fallback-guard.js`, `test/m106-fallback-gate.test.js`
+
+**Shorter replies (M107).** A second Claude rewrites replies over 60 words — answer first, no preamble, no backstory, no jargon — before you read them. The rewrite is thrown away and the original kept if it drops a question, a code block, every file path, or invents a number.
+
+- `bin/gsd-t-concise-rewrite.cjs`, `scripts/gsd-t-concise-hook.js`, `test/m107-concise-rewrite.test.js`
+
+Switch either gate off per project: `.gsd-t/fallback-gate.json` or `.gsd-t/concise.json` with `{"enabled": false}`.
+
+## [5.8.10] - 2026-08-05
+
+### Changed — the architect now interviews you before it assesses
+
+The architect sometimes focused on the wrong thing, or skipped something because it decided the thing was out of scope. Rather than patch that from the description, 16 real architect runs across 10 sessions were audited. They contained **21 corrections the user had to make — and 13 of those were facts the user already held and would have given for free.** Only 4 of 16 runs needed no correction.
+
+| Failure | n | What it sounded like |
+|---|---|---|
+| Re-derived an already-settled rule | 8 | *"That rule was also implemented, at least I thought it was last week."* |
+| Asserted real-world behavior the user knew was false | 5 | *"I believe you're wrong. When scrolling the feed…"* — it had measured a saved page and described it as the live one |
+| Weighed a trade-off the user had already closed | 3 | *"Stop telling me rather or two. Just tell me how we get to one."* |
+| Output the user could not read | 3 | *"Try again without any jargon. I don't understand the grid."* |
+| Analyzed an adjacent thing | 2 | *"Either we're having a miscommunication or you didn't find all the bugs."* |
+| Excluded a dimension held in scope | 2 | *"Now consider capture performance in the context of these changes."* |
+
+The top two — 13 of 21 — share one cause: **the architect reasoned where it should have asked.**
+
+- `commands/gsd-t-architect.md`: a grounding loop now runs before the Six-Stage Pass — read the code and the standing rules → **interview** → **research** → loop, **max 3 cycles** (1-2 expected). The interview leads by showing its read of *how the thing works today* as a plain-English flow for the user to confirm or correct, which kills a wrong premise in one line instead of after a wasted pass. Two questions are mandatory every run, aimed at the top two failures: what is already settled and not open for re-litigation (echoing the harvested rules back so a stale one gets corrected cheaply), and what is true at runtime that the code cannot show. The rest branch by target type — bug-hunt, performance, plan-review, subsystem-audit, security. It gathers the evidence it can and explicitly names what it cannot get from the repo.
+- **Research is gated on confidence and runs after the interview, never before** — so it cannot anchor the questions on an external solution shape, and so no search is spent on a question the user would answer in one line. The audit found no correction of the form "you didn't know how others solve this," so research is real but secondary to asking.
+- **When external practice contradicts a standing project rule, the rule wins and the conflict is named in one line.** The narrow case where a fallback is genuinely warranted requires all three of: the primary path fails a high percentage of the time, the cause is outside our control, and completing the workflow is critical. Otherwise the answer is a halt.
+- **At the 3-cycle cap the architect asks whether to halt or proceed** with the uncertainty flagged. It does not decide that alone.
+- The interview runs in the main session and the pass in a fresh subagent — a subagent cannot ask anything mid-run, and relaying questions out as pings had already produced babysitting. The confirmed grounding is threaded into the subagent so it never re-derives what was just settled.
+- Eight standing checks distilled from the corrections now run every pass: audit *existing* fallbacks as a root-cause candidate, no data left in limbo, delete the legacy path in the same change, two mechanisms doing one job means route to one rather than present a trade-off, state a verification path, production-data impact before a migration or merge, label any claim resting on a snapshot, and cover the always-in-scope dimensions. Output constraints are hard: plain English in the lead, no file:line grids, no shorthand.
+- `.gsd-t/contracts/architects-oversight-contract.md` → v1.1.0: adds §0 (the grounding loop) and guards G-8..G-11.
+- Two new flags: `--no-interview`, `--no-research`.
+- **Fixed in passing:** the command still pointed at the pre-M99 graph path `.gsd-t/graph.db` instead of `.gsd-t/graphDB/graph.db` — the same false negative recorded in 5.2.11, which had been silently disabling the architect's own reuse check.
+
+The measure of a run is now what happens after it: a run succeeds if the build it directed needed few follow-ups. A well-formed report that led to rework is a failed run. Suite 3120/0/13-skip.
+
 ## [5.7.10] - 2026-08-03
 
 ### Added — one session per working tree, enforced (M105)

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.7.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.9.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.
@@ -200,7 +200,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-partition` | Decompose into domains + contracts | In wave |
 | `/gsd-t-plan` | Create atomic task lists per domain (tasks auto-split to fit one context window) | In wave |
 | `/gsd-t-impact` | Analyze downstream effects | In wave |
-| `/gsd-t-architect` | Run the Architect's Oversight Six-Stage Pass on existing work — finds the simplest solution + reuse + traps, as plain-English pseudocode (plan-only; `--build` to auto-build) | Manual |
+| `/gsd-t-architect` | Interviews you first (shows its read of current behavior for confirmation, researches when unsure — max 3 cycles), then runs the Architect's Oversight Six-Stage Pass — simplest solution + reuse + traps, as plain-English pseudocode (plan-only; `--build` to auto-build, `--no-interview`/`--no-research` to skip a stage) | Manual |
 | `/gsd-t-execute` | Run tasks — task-level fresh dispatch, worktree isolation, adaptive replanning | In wave |
 | `/gsd-t-test-sync` | Sync tests with code changes | In wave |
 | `/gsd-t-qa` | QA agent — test generation, execution, gap reporting | Auto-spawned |

package/bin/gsd-t-concise-rewrite.cjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * gsd-t-concise-rewrite.cjs
+ *
+ * M107-D1 — Rewrites a reply into its shortest honest form.
+ *
+ * [RULE] concise-rewrite-never-changes-a-fact
+ * [RULE] concise-rewrite-halts-never-silently-degrades
+ * [RULE] concise-rewrite-preserves-questions-and-warnings
+ *
+ * A fresh Claude, given only the text and the rules, cuts what the writer is
+ * attached to. It has no memory of the work, so it has nothing to defend.
+ *
+ * ─── Usage ──────────────────────────────────────────────────────────────────
+ *   node gsd-t-concise-rewrite.cjs --text "<reply>" [--project <dir>] [--json]
+ *   echo "<reply>" | node gsd-t-concise-rewrite.cjs --stdin
+ *
+ * ─── Exit codes ─────────────────────────────────────────────────────────────
+ *   0  rewritten (or skipped because it was already short)
+ *   4  the rewrite could not be done — the ORIGINAL is returned, marked
+ *   64 bad input
+ *
+ * On failure it returns the ORIGINAL text and says so. It never returns
+ * nothing, never truncates, never guesses. Showing a long reply is a poor
+ * outcome; showing a silently mangled one is a wrong one.
+ *
+ * Zero dependencies beyond the `claude` CLI on PATH.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const EXIT_OK = 0;
+const EXIT_FAILED = 4;
+const EXIT_BAD_INPUT = 64;
+
+const DEFAULTS = {
+  enabled: true,
+  skipUnder: 60,      // words — below this, rewriting buys nothing
+  model: "sonnet",
+  timeoutMs: 45000,
+};
+
+const RULES = `You rewrite a reply so it can be read in as little time as possible.
+
+The reader is a slow reader. Every extra line costs him real time. Jargon costs
+him more than length — he has to stop and translate it, and then ask for it
+again in plain words.
+
+Rewrite the reply below following these rules exactly:
+
+1. ANSWER FIRST. The answer is the first thing. Nothing before it.
+2. NO PREAMBLE. Cut any sentence that announces a point instead of making it.
+3. NO BACKSTORY. Cut every explanation of why something failed before, what
+   cannot work, how it works today, or what was rejected — unless the reply is
+   answering a direct question about that. He asks when he wants it.
+4. NO JARGON. Plain words. If a technical term is genuinely needed, put the
+   plain meaning first and the term in brackets after it.
+5. CUT ANYTHING NOT ASKED FOR.
+6. Prefer a short list or a small table over a paragraph.
+
+KEEP THESE. They are not optional, and dropping any one of them means the
+rewrite is rejected and thrown away:
+
+- The first line, if it is a dated status banner.
+- EVERY question being asked of the reader. If the reply ends by asking him
+  something, that question MUST appear in your rewrite, as its own line, at
+  the end. This is the single most common way a rewrite is rejected.
+- Any warning, failure, or thing that went wrong.
+- File paths and links, exactly as written.
+- Code blocks, exactly as written.
+- Specific numbers and names.
+
+Never:
+- change a fact or a number
+- drop a warning, a failure, or a question
+- add anything that was not in the original
+- soften a bad outcome
+
+Return ONLY the rewritten reply. No commentary about what you changed.`;
+
+function readConfig(projectDir) {
+  const p = path.join(projectDir, ".gsd-t", "concise.json");
+  if (!fs.existsSync(p)) return { ...DEFAULTS };
+  try {
+    return { ...DEFAULTS, ...JSON.parse(fs.readFileSync(p, "utf8")) };
+  } catch (_) {
+    // Unreadable config → defaults. Rewriting with defaults is the safe
+    // direction; it cannot lose content, only shorten it.
+    return { ...DEFAULTS };
+  }
+}
+
+function wordCount(s) {
+  return (String(s).trim().match(/\S+/g) || []).length;
+}
+
+/**
+ * Facts that must survive the rewrite. If any disappears, the rewrite is
+ * rejected and the original is returned — a rewrite that drops a warning or a
+ * question is worse than a long reply.
+ */
+function extractInvariants(text) {
+  return {
+    questions: (text.match(/[^.!?\n]*\?/g) || []).map((q) => q.trim()).filter((q) => q.length > 10),
+    numbers: text.match(/\b\d[\d,._]*\b/g) || [],
+    paths: text.match(/[\w./-]+\.(?:js|cjs|mjs|ts|tsx|json|md|py|sh)\b/g) || [],
+    codeBlocks: (text.match(/```/g) || []).length / 2,
+  };
+}
+
+function checkInvariants(original, rewritten) {
+  const a = extractInvariants(original);
+  const b = extractInvariants(rewritten);
+  const lost = [];
+
+  if (a.questions.length > 0 && b.questions.length === 0) {
+    lost.push("a question to the reader was dropped");
+  }
+  const lostPaths = a.paths.filter((p) => !rewritten.includes(p));
+  if (lostPaths.length > 0 && lostPaths.length === a.paths.length && a.paths.length > 0) {
+    lost.push("every file path was dropped");
+  }
+  if (a.codeBlocks > 0 && b.codeBlocks < a.codeBlocks) {
+    lost.push("a code block was dropped");
+  }
+  // A number appearing in the rewrite that was never in the original means
+  // something was invented.
+  const invented = b.numbers.filter((n) => n.length > 2 && !a.numbers.includes(n));
+  if (invented.length > 0) {
+    lost.push(`a number appeared that was not in the original: ${invented[0]}`);
+  }
+  return lost;
+}
+
+/** Ask a fresh Claude to do the rewrite. */
+function rewrite(text, cfg) {
+  const prompt = `${RULES}\n\n--- REPLY TO REWRITE ---\n${text}`;
+  const run = spawnSync("claude",
+    ["-p", prompt, "--model", cfg.model, "--dangerously-skip-permissions"],
+    { encoding: "utf8", timeout: cfg.timeoutMs, maxBuffer: 8 * 1024 * 1024 });
+
+  if (run.error) return { ok: false, error: run.error.message };
+  if (run.status !== 0) return { ok: false, error: `claude exited ${run.status}: ${(run.stderr || "").slice(0, 200)}` };
+  const out = (run.stdout || "").trim();
+  if (!out) return { ok: false, error: "the rewriter returned nothing" };
+  return { ok: true, text: out };
+}
+
+function parseArgs(argv) {
+  const args = { project: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") args.json = true;
+    else if (a === "--stdin") args.stdin = true;
+    else if (a === "--text") args.text = argv[++i];
+    else if (a === "--project") args.project = argv[++i];
+  }
+  return args;
+}
+
+function emit(result, asJson) {
+  if (asJson) process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  else process.stdout.write(result.text + "\n");
+  process.exit(result.exitCode);
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const projectDir = path.resolve(args.project);
+  const cfg = readConfig(projectDir);
+
+  let text = args.text;
+  if (args.stdin) {
+    try { text = fs.readFileSync(0, "utf8"); } catch (_) { text = ""; }
+  }
+  if (typeof text !== "string" || !text.trim()) {
+    emit({ ok: false, exitCode: EXIT_BAD_INPUT, text: "", error: "no text given" }, true);
+  }
+
+  const before = wordCount(text);
+
+  if (!cfg.enabled) {
+    emit({ ok: true, exitCode: EXIT_OK, text, skipped: "switched off", words: before }, args.json);
+  }
+  if (before < cfg.skipUnder) {
+    emit({ ok: true, exitCode: EXIT_OK, text, skipped: "already short", words: before }, args.json);
+  }
+
+  const r = rewrite(text, cfg);
+  if (!r.ok) {
+    emit({
+      ok: false, exitCode: EXIT_FAILED, text,
+      error: r.error,
+      note: "Rewrite failed — this is the original, unchanged.",
+      words: before,
+    }, args.json);
+  }
+
+  const lost = checkInvariants(text, r.text);
+  if (lost.length > 0) {
+    emit({
+      ok: false, exitCode: EXIT_FAILED, text,
+      error: `the rewrite lost something: ${lost.join("; ")}`,
+      note: "Rewrite rejected — this is the original, unchanged.",
+      words: before,
+    }, args.json);
+  }
+
+  const after = wordCount(r.text);
+  emit({
+    ok: true, exitCode: EXIT_OK, text: r.text,
+    words: before, wordsAfter: after,
+    saved: before - after,
+  }, args.json);
+}
+
+if (require.main === module) main();
+
+module.exports = { wordCount, extractInvariants, checkInvariants, readConfig, RULES };