@tekyzinc/gsd-t 4.20.10 → 4.20.11

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.20.11] - 2026-07-12
+
+### Added — M101: Architect's Oversight Doctrine
+
+Fills GSD-T's empty architect seat. Every existing quality gate (Red Team, QA, code-review, pre-mortem) asks "is this correct?" — none asked "is this the smartest, simplest design given what already exists?" The result was the wrong thing built correctly, tested thoroughly, and shipped (origin: a real waste where a whole-page scan re-derived a value already stored locally, invisible under jargon). Now every build runs a Six-Stage Pass before code: Objective → Conflict → Reuse (process AND output, queried against the code graph) → Simplicity → Reuse-forecast → Risk, each answered with evidence not conviction. Three-layer enforcement, sibling of the M90 Unproven-Assumption Doctrine.
+
+- `templates/CLAUDE-global.md` + `~/.claude/CLAUDE.md`: the doctrine (definition layer) — Six-Stage Pass, reuse logic (HIGH/LOW forecast, extract-don't-mutate, graph-registered reuse-candidate links to prevent silent duplicate sprawl), plain-English proof, jargonless output co-equal with brevity (absorbs backlog #47).
+- `~/.claude/scripts/gsd-t-architect-oversight-guard.js`: PreToolUse Write|Edit reminder hook (trigger layer) — one line at the build moment, fail-open, code-only (silent on prose/pseudocode/docs/non-project). Wired into settings.json.
+- `templates/workflows/gsd-t-phase.workflow.js`: injects the Six-Stage directive into plan/milestone phases (execution layer; `[RULE] phase-workflow-injects-architect-pass`, enforced by the existing guard-map gate).
+- `.gsd-t/contracts/architects-oversight-contract.md` v1.0.0 STABLE; `.gsd-t/pseudocode/PseudoCode-ArchitectsOversight.md` (self-obedience, plain-English house style).
+- `scripts/gsd-t-auto-route.js`: sharpened READER_CONTRACT jargon rule + 2 worked examples (backlog #47).
+- `test/m101-architect-oversight-hook.test.js`: 9 tests (fires on code, silent on prose, fails open on garbage).
+
+Follow-on (recorded, not built): a dedicated verify agent for pseudocode-completeness / reuse-evidence / no-silent-twin checks. The existing guard-map gate already enforces the `[RULE]` marker.
+
 ## [4.20.10] - 2026-07-08
 
 ### Added — M100: Universal Trace + Audit Logging (framework defaults)

package/README.md

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

package/package.json

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

package/templates/CLAUDE-global.md

@@ -429,6 +429,33 @@ asserting. If you lack a fresh source, say so explicitly: *"I believe X, but I d
 source — please verify."* Do NOT state an external/time-varying fact as known when it is a guess.
 See memory pointer: `feedback_auto_research_external_gaps`.
 
+### Architect's Oversight Doctrine (M101 — governed, enforced)
+
+**Contract:** `.gsd-t/contracts/architects-oversight-contract.md` v1.0.0 STABLE
+
+**Never build before the design has passed the architect's interrogation.** GSD-T staffs verifiers (Red Team, QA, code-review, pre-mortem) — all asking "is this correct?" — but no seat asked "is this the *smartest, simplest* design given what we already have?" The result: the wrong thing built correctly, then thoroughly tested, then shipped (the Binvoice completeness-scan waste — a whole-page scan re-deriving a count already stored locally). This doctrine fills the empty architect seat. Sibling to the Unproven-Assumption Doctrine: that one bars unproven *facts*; this one bars unproven *necessity*.
+
+**The Six-Stage Pass — run IN ORDER before proposing or building any solution. Each stage can KILL the plan. Every "am I sure?" is answered with EVIDENCE (a grep, a Read, a graph query), never conviction — self-confidence is what produced the waste.**
+
+1. **Objective** — What is the core objective? Why is it the core objective? *(Kills: building the wrong thing.)*
+2. **Conflict** — Does it support or conflict with other core objectives? Must we re-examine/re-plan an already-built objective? *(Kills: a local win that breaks the system; frozen past decisions.)*
+3. **Reuse** — Have I already accomplished any piece of this? Can I reuse the **process**, or the **output** of that process? *(Query the graph — not memory. This stage kills redundant work like the completeness scan. Split is load-bearing: reuse the answer already produced, not just the code.)*
+4. **Simplicity** — Is this the simplest, most efficient plan? Am I sure? *(Evidence, not conviction. Kills bloat.)*
+5. **Reuse forecast & duplication** — see §Reuse Logic below. *(Kills both over-engineering and rogue-twin sprawl.)*
+6. **Risk** — Security risks? Stability/scalability risks? Am I sure? *(Kills fast-but-fragile.)*
+   → **Then build.**
+
+**§Reuse Logic (Stage 5 — how to avoid both sprawl and stability-breakage):**
+- **Forecast reuse likelihood** against long-term project scope (read requirements/architecture — don't guess): **HIGH** (core domain entity / recurs in roadmap / pure transformation) or **LOW** (one-off UI/debug/glue / single caller). HIGH → build clean + extractable now (NOT config-knobbed — that's the YAGNI trap), register in the graph as reuse-likely. LOW → simplest inline thing, no abstraction.
+- **When a similar-but-not-reusable thing already exists:** (a) same WHAT (job) or same HOW (surface)? Same WHAT → generalize; merely similar → build new. (b) If generalize: **extract a shared core, do NOT mutate** the working original (old callers keep identical behavior). (c) If blast-radius/stability forbids touching it → build new, **but register a "reuse-candidate" link in the graph** pointing at the twin, so the duplication is visible and re-decided on next touch. **Never build a silent rogue twin** — sprawl disables Stage 3's reuse-check for everyone after you.
+- **A wrong forecast self-corrects:** the graph's similarity check surfaces a LOW-forecast function that got reused anyway at the next Stage 3. So the forecast need only be directionally right — the graph rescues the misses. That is what removes the paralysis.
+
+**§Plain-English proof (the artifact you can always review, never must):** the Six-Stage answers are written into the milestone's **PseudoCode document** in plain, jargon-free language (style: `.gsd-t/pseudocode/` — title + one-line purpose, `CURRENT`/`PROPOSED` blocks, `# plain comment` inline, a summary table; near-zero preamble). Jargon is where unexamined complexity hides — a layman-legible sentence has nowhere for a pointless operation to survive. The pseudocode IS the audit, and it lets the user approve *direction before code* as the senior reviewer, not a rubber-stamp.
+
+**§Jargonless output (co-equal with brevity, NOT a trade-off):** short and clear are different axes; jargon is short, so brevity rules alone reward it. Every reply, plan, options-prompt, and mid-work narration glosses jargon in plain words on first use. The crux: individual shorthand may be decodable, but **several mashed into one sentence become unintelligible** — never force the reader toward an "I don't understand" escape hatch; if that option would help, the sentence already failed. Enforced by the Reader Contract (injected every turn).
+
+**§Enforcement (three layers — same shape as Unproven-Assumption):** (1) this doctrine = the *definition* (reference, always available); (2) a **PreToolUse hook on Write/Edit** = the *trigger* — injects a one-line reminder pointing here at the build moment, so it can't be missed under load; (3) the **plan/milestone workflow gate** = the *execution* — the Six-Stage Pass runs as blocking `agent()` steps with graph/doc evidence, and pseudocode-completeness is a verify check. Injecting the doctrine ≠ executing it; the workflow does the doing.
+
 ### 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

@@ -867,6 +867,38 @@ let result;
 // M90 §2 D4-T4: holds the divergence-path result from the competition arm (R-ARCH-1).
 // Set inside the competition arm (before Finalize), attached to result after.
 let _pendingArchTriggerDivergence = null;
+
+// M101 — Architect's Oversight Six-Stage Pass. Injected as a PROTOCOL DIRECTIVE into
+// the design phases (plan/milestone) where the design is decided, before code exists.
+// Reuses the existing phase agent rather than adding a parallel gate (the doctrine's
+// own "reuse the process" rule). Each stage answered with EVIDENCE (grep/Read/graph),
+// never conviction. Contract: architects-oversight-contract.md §1/§4.
+// [RULE] phase-workflow-injects-architect-pass
+const _ARCHITECT_PHASES = new Set(["plan", "milestone"]);
+const _architectPassLine = _ARCHITECT_PHASES.has(phaseName)
+  ? [
+      ``,
+      `ARCHITECT'S OVERSIGHT — run this Six-Stage Pass BEFORE finalizing the ${phaseName}, IN ORDER.`,
+      `Each stage can KILL/reshape the plan. Answer each with EVIDENCE (a grep, a Read, or the`,
+      `graph slice above) — never conviction. Record the answers in plain, jargon-free language`,
+      `in the milestone's PseudoCode document (.gsd-t/pseudocode/), house style: title + one-line`,
+      `purpose, CURRENT/PROPOSED blocks, "# plain comment" inline, a summary table.`,
+      `  1. OBJECTIVE — what is the core objective, and why is it the objective?`,
+      `  2. CONFLICT — does it conflict with another objective? must a prior one be re-examined?`,
+      `  3. REUSE — have I already done any piece of this? Can I reuse the PROCESS, or the OUTPUT`,
+      `     (a value already computed/stored)? Consult the graph slice, NOT memory. This stage`,
+      `     kills redundant work (e.g. re-deriving a value already stored locally).`,
+      `  4. SIMPLICITY — is this the simplest, most efficient plan? Prove it.`,
+      `  5. REUSE FORECAST — HIGH (core entity / recurs / pure transform) → build clean+extractable,`,
+      `     register in graph as reuse-likely. LOW → simplest inline, no abstraction. If a similar`,
+      `     thing exists: same JOB → extract a shared core (do NOT mutate the working original);`,
+      `     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?`,
+      `A stage you cannot answer with evidence HALTS the plan (needs-human) — do not proceed on a hunch.`,
+    ].join("\n")
+  : "";
+
 if (!competitionOn) {
   // ── Single-producer path (default, unchanged behavior) ──
   phase("Phase");
@@ -879,6 +911,7 @@ if (!competitionOn) {
       userInput ? `\nUser input:\n${userInput}` : "",
       ``,
       `Objective: ${baseObjective}`,
+      _architectPassLine,
       ``,
       `Follow the CLAUDE.md Pre-Commit Gate. Commit artifacts with prefix "${(milestone || "m").toLowerCase()}(${phaseName})".`,
       `Return JSON per the schema.`,