@tekyzinc/gsd-t 5.0.13 → 5.0.14

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.0.14] - 2026-07-13
+
+### Added — No-Fallback-Ever Doctrine (never branch around a failure without asking)
+
+"Pretend every project is a vampire and the word fallback is garlic." A fallback — anything that CONTINUES after a failure (catch-and-continue, `|| default`, silent degrade, try-X-else-Y where Y masks X failing) — is now BANNED unless the user approves it first, or you can cite a confirmed reproducible case only a fallback catches. This reflex is what hid the 12-day broken-graph break and the "npm install silently kept the old version" skew. The preferred move where a straight line can fail is a HALT (stop + demand fix), which is explicitly NOT a fallback. Strongest sibling of the existing No-Silent-Degradation feedback.
+
+- `templates/CLAUDE-global.md` (+ `~/.claude/CLAUDE.md`): the doctrine (definition) — banned scope, the halt-not-fallback distinction, the ask-first test, and the release-process clause (verify the change landed / version advanced, HALT if not — never trust a reported-success install).
+- `scripts/gsd-t-architect-oversight-guard.js`: the Write/Edit trigger reminder now also challenges fallbacks at the build moment (reused the existing architect hook — no new hook).
+- `templates/workflows/gsd-t-phase.workflow.js` + `commands/gsd-t-architect.md`: added Stage 6b (No-Fallback) to the Six-Stage Pass directive.
+- `.gsd-t/contracts/architects-oversight-contract.md`: Stage 6b row.
+- Reused the existing `bin/gsd-t-graph-anti-grep-lint.cjs` for the graph-specific mechanical guard; deliberately did NOT build a general static fallback-detector (it can't judge proven-necessary — that's the ask).
+- `test/m101-architect-oversight-hook.test.js`: 4 wiring tests (doctrine in both templates, hook, workflow, command).
+
 ## [5.0.13] - 2026-07-12
 
 ### Fixed — a BROKEN graph now HALTS instead of silently falling back to grep

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.0.13** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.0.14** - 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/commands/gsd-t-architect.md

@@ -79,6 +79,12 @@ The subagent works through the six stages IN ORDER. Each can kill or reshape the
    the simpler fix actually works** — if the plan says "handled elsewhere / picked up later,"
    VERIFY that's true; do not assert self-healing you haven't checked. (This is the trap that
    hides inside a simplification.)
+6b. **NO-FALLBACK-EVER** — Does the design add ANY fallback (anything that CONTINUES after a
+   failure: catch-and-continue, `|| default`, silent degrade, try-X-else-Y where Y masks X
+   failing)? If yes, do NOT design it in — surface it as an OPEN QUESTION for the user, UNLESS
+   you can cite a confirmed reproducible case only a fallback catches. The straight-line process
+   that produces the result is the goal; where it can fail, prefer a **HALT** (stop + demand
+   fix), which is NOT a fallback. (See CLAUDE.md § No-Fallback-Ever Doctrine.)
 
 A stage the subagent cannot answer with evidence is a HALT — surface it as an open question for
 the user, do not paper over it with a guess.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.0.13",
+  "version": "5.0.14",
   "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/scripts/gsd-t-architect-oversight-guard.js

@@ -33,13 +33,19 @@
 const fs = require("fs");
 const path = require("path");
 
-// One line. A pointer, not the doctrine. Keeps context cost ~nil.
+// A pointer, not the doctrine. Keeps context cost ~nil. Carries TWO reminders:
+// the Six-Stage Pass (design-first) and the No-Fallback-Ever rule (never branch
+// around a failure without asking) — both fire at the write-code moment.
 const REMINDER =
   "[GSD-T ARCHITECT] About to write/edit code — run the Architect's Oversight " +
   "Six-Stage Pass FIRST (Objective → Conflict → Reuse[query the graph] → " +
   "Simplicity → Reuse-forecast → Risk), each answered with evidence not conviction. " +
   "Is this the simplest design, and does something reusable already exist? " +
-  "See ~/.claude/CLAUDE.md § Architect's Oversight Doctrine.";
+  "NO-FALLBACK-EVER: if this adds anything that CONTINUES AFTER A FAILURE " +
+  "(catch-and-continue, || default, silent degrade, try-X-else-Y) — STOP and ask the " +
+  "user first, unless you can cite a confirmed reproducible case only a fallback catches. " +
+  "A HALT (stop + demand fix) is NOT a fallback and is the preferred move. " +
+  "See ~/.claude/CLAUDE.md § Architect's Oversight + No-Fallback-Ever Doctrines.";
 
 // File extensions that are PROSE/config, not code — skip the reminder for these.
 // (The doctrine's own artifacts are markdown; reminding while authoring them is noise.)

package/templates/CLAUDE-global.md

@@ -456,6 +456,23 @@ See memory pointer: `feedback_auto_research_external_gaps`.
 
 **§Enforcement (three layers — same shape as Unproven-Assumption):** (1) this doctrine = the *definition* (reference, always available); (2) a **PreToolUse hook on Write/Edit** = the *trigger* — injects a one-line reminder pointing here at the build moment, so it can't be missed under load; (3) the **plan/milestone workflow gate** = the *execution* — the Six-Stage Pass runs as blocking `agent()` steps with graph/doc evidence, and pseudocode-completeness is a verify check. Injecting the doctrine ≠ executing it; the workflow does the doing.
 
+### No-Fallback-Ever Doctrine (governed, enforced — the strongest sibling of No-Silent-Degradation)
+
+**Pretend every project is a vampire and the word "fallback" is garlic.** A fallback — **anything that continues after a failure** (a `catch` that keeps going, `|| default`, a silent degrade, a secondary path, a "try X else Y" where Y masks X failing) — is **BANNED unless the user explicitly approves it first, OR you can cite a confirmed, reproducible case where the straight-line path provably fails and ONLY a fallback catches it.** No trivial exception. This is a Destructive-Action-Guard-class STOP: before writing any such branch, **halt and ask the user.**
+
+**Why:** the reflex to add a fallback "just in case" is what hides real failures — a fallback that guards an *unproven* case doesn't add safety, it adds a place for a real failure to hide (e.g. a graph query that silently falls back to grep when the graph is actually broken). The desired discipline is the **straight-line process that produces the result**; if the straight line can fail, the answer is **HALT and surface it**, not branch around it.
+
+**The one thing that is NOT a fallback (and is REQUIRED where a straight line can fail):** a **HALT** — refusing to continue and demanding a fix (return `blocked-needs-human`, exit non-zero, loud message). A halt is the *opposite* of a fallback: it stops the hiding instead of enabling it. When you're tempted to write a fallback, the correct move is almost always a halt.
+
+**Test before writing any "continue after failure" branch:**
+1. Is this a fallback (continues past a failure) or a halt (stops)? Halt → allowed. Fallback → continue to 2.
+2. Can I name a **confirmed, reproducible** failing case where ONLY this fallback catches it? If NO → **STOP and ask the user.** If YES → cite it in a comment + the commit, then proceed.
+3. Never judge "trivial" yourself — the trivial-fallback judgment is exactly the one that has been failing. Ask.
+
+**Applies to the release process too:** a publish/propagate step must **verify the change actually landed** (installed version advanced; a sample project received the new file) and **HALT if it didn't** — never trust an install/copy that *reports* success. A package manager silently keeping the old version is itself a banned silent fallback.
+
+**§Enforcement (three layers):** (1) this doctrine = the definition; (2) the **Architect's Oversight Write/Edit trigger is extended** to challenge every fallback at the build moment ("is this a fallback? name the proven case or ask"); (3) mechanical guards where they already exist — the graph consumers' `try→catch→grep` fallback is caught by `bin/gsd-t-graph-anti-grep-lint.cjs` (reused, not duplicated); a general static "detect every fallback" lint is deliberately NOT built (it can't judge *proven-necessary* — that is the human/architect ask, which is layer 2).
+
 ### Phase Flow
 - Upon completing a phase, automatically proceed to the next phase
 - ONLY run Discussion phase if truly required (clear path → skip to Plan)

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

@@ -928,6 +928,12 @@ const _architectPassLine = _ARCHITECT_PHASES.has(phaseName)
       `     if stability forbids touching it → build new BUT register a "reuse-candidate" graph link`,
       `     to the twin (never a silent rogue duplicate).`,
       `  6. RISK — any security or stability/scalability risk? Am I sure?`,
+      `  6b. NO-FALLBACK-EVER — does this plan add ANY fallback (anything that CONTINUES after a`,
+      `     failure: catch-and-continue, || default, silent degrade, try-X-else-Y where Y masks X`,
+      `     failing)? If yes: STOP and surface it as an OPEN QUESTION for the user — do NOT design`,
+      `     it in — UNLESS you can cite a confirmed reproducible case only a fallback catches. The`,
+      `     straight-line process that produces the result is the goal; where it can fail, prefer a`,
+      `     HALT (stop + demand fix), which is NOT a fallback. Fallbacks are rare and ask-first.`,
       `A stage you cannot answer with evidence HALTS the plan (needs-human) — do not proceed on a hunch.`,
     ].join("\n")
   : "";