@tekyzinc/gsd-t 4.20.10 → 5.0.10

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.0.10] - 2026-07-12
+
+### Added — `/gsd-t-architect`: run the Architect's Oversight pass on demand
+
+A standalone command that runs the M101 Six-Stage Pass (Objective → Conflict → Reuse → Simplicity → Reuse-forecast → Risk) on **existing** work — an already-frozen plan, a messy subsystem, or a pasted tangle of problems — and produces the simplest correct solution as plain-English pseudocode, plus the traps each stage surfaces and what's already reusable. Major bump: this is the on-demand front door to design-first, reuse-first development, not an incremental command. Where the plan/milestone workflow runs the pass *while generating* a plan, this runs it as a standalone audit over work that already exists.
+
+- `commands/gsd-t-architect.md`: prose-driven command — spawns one opus analysis subagent, reasons from the code graph (reuse/duplication) and real code, not memory. Default = plan-only then offers to build; `--build` auto-builds the simplest fix; `--chat-only` skips writing a file. Always prints a findings + plan summary to the session, even in auto-build. Reuses the existing prose-command + Task-subagent pattern (`/gsd-t-status`, `/gsd-t-impact`) — no new workflow file (the doctrine obeying its own Stage 3/4).
+- `README.md` + `commands/gsd-t-help.md`: command documented.
+- `test/filesystem.test.js`: command counts 54→55 / 48→49.
+
+## [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.
+**v5.0.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,6 +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-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/commands/gsd-t-architect.md

@@ -0,0 +1,135 @@
+# GSD-T: Architect — Run the Architect's Oversight Six-Stage Pass on Existing Work
+
+You are the **architect**. You assess a plan, a subsystem, or a tangle of problems the user
+points you at, and you find the **simplest correct solution** — reusing what already exists,
+surfacing the traps, and writing the answer in plain-English pseudocode the user can approve
+BEFORE any code is written.
+
+This is a standalone, on-demand run of the **Architect's Oversight Doctrine** (see the project
+`CLAUDE.md` / `~/.claude/CLAUDE.md` § Architect's Oversight, and
+`.gsd-t/contracts/architects-oversight-contract.md`). Use it when a plan already exists (or is
+half-formed) and you want it interrogated for simplicity + reuse before building.
+
+Unlike the plan/milestone workflow (which runs the Six-Stage Pass *while generating* a plan),
+this command runs it as a **standalone pass over existing work** — an already-frozen plan, a
+messy subsystem, or a pasted description of problems.
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS`:
+- **First positional** = `$TARGET` — what to assess. Either a plain-English description
+  ("the feed scanning stalls — image watcher, completeness, comment finder"), a file/dir path,
+  or "the current plan" (→ read `.gsd-t/domains/*/tasks.md` + `.gsd-t/progress.md` Current Milestone).
+- **`--build`** — after producing the plan, AUTO-BUILD the simplest solution in the same run
+  (do not stop to ask). Default (no flag): produce the plan, then OFFER to build.
+- **`--chat-only`** — report in the session only; do NOT write a pseudocode file to disk.
+  Default: write the pseudocode artifact to `.gsd-t/pseudocode/`.
+
+If `$TARGET` is empty, ask the user what to assess. Do not guess.
+
+---
+
+## Behavior contract (what the user asked for)
+
+1. **Default = plan, then offer to build.** Produce the assessment + plan, then end by asking
+   "Build the simplest solution now?" — unless `--build` was passed, in which case auto-build.
+2. **`--build` = auto-build after planning.** Assess → plan → implement the simplest solution,
+   without pausing — BUT still print the findings + plan summary to the session first.
+3. **ALWAYS print a session summary** — even in auto-build mode. The user scans the conversation
+   for anything that catches their eye while it keeps moving. Never silently proceed.
+
+---
+
+## Step 1: Launch the architect via a Task subagent
+
+Give the assessment a fresh context window. Spawn ONE Task subagent (`model: opus`) — this is
+high-stakes design judgment, top tier. Pass it the target and this protocol.
+
+**Before spawning**, gather evidence sources so the subagent reasons from facts, not memory:
+- If a code graph exists (`.gsd-t/graph.db`), the subagent uses `gsd-t graph` for reuse/caller
+  queries (Stage 3 + Stage 5 duplication check). If absent, it greps/reads and says so LOUDLY
+  (reuse-detection is reduced — never a silent "nothing found").
+- Read the relevant code the target names (or the plan files).
+
+---
+
+## Step 2: The subagent runs the Six-Stage Pass (with EVIDENCE, never conviction)
+
+The subagent works through the six stages IN ORDER. Each can kill or reshape the plan. Every
+"am I sure?" is answered by looking (grep / Read / graph), not by asserting.
+
+1. **OBJECTIVE** — What is the core objective, in one plain sentence? Why is it the objective?
+   (Often the traps shrink once this is pinned down.)
+2. **CONFLICT** — Does solving this conflict with another objective? Must a previously-built
+   piece be re-examined/re-planned?
+3. **REUSE** — Have I already accomplished any piece of this? Can I reuse the **process**, or
+   the **output** (a value already computed/stored)? *Query the graph, not memory.* This is the
+   stage that kills redundant work (e.g. re-deriving a value already stored locally).
+   **Also — is this the SAME pattern repeated elsewhere?** If the target is one instance of a
+   bug, search for the other instances (one fix for a class beats N fixes for N instances).
+4. **SIMPLICITY** — What is the simplest, most efficient solution? Prove it's simplest.
+5. **REUSE FORECAST & DUPLICATION** — For anything new: HIGH reuse likelihood (core entity /
+   recurs / pure transform) → build clean + extractable; LOW → simplest inline. 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 the duplication (a "reuse-candidate"
+   note) so it's visible, never a silent rogue twin.
+6. **RISK** — Does the proposed fix create security or stability/scalability risk? **And prove
+   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.)
+
+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.
+
+---
+
+## Step 3: The subagent produces the output
+
+**A — Plain-English pseudocode** (the artifact), in the house style — title + one-line purpose,
+`CURRENT` (what it does today) and `PROPOSED` (the simplest fix) blocks, `# plain comment` inline,
+a summary table, near-zero preamble. For each CURRENT block, say **why it does what it does now**
+— and flag explicitly if it's a "got complicated over time" accretion (mechanisms stacked by
+successive fixes). Unless `--chat-only`, write it to `.gsd-t/pseudocode/PseudoCode-<Target>.md`.
+
+**B — Session summary** (always printed, even under `--build`):
+- **Core objective** (one line)
+- **Is this a "complicated over time" issue?** (yes/no + the accretion history if yes)
+- **What's reusable** (process or a stored output already available)
+- **Same pattern elsewhere?** (other instances of the bug/design found)
+- **Simplest solution** (one paragraph)
+- **Traps surfaced** (each stage's kill/risk finding — especially the Stage-6 "does the fix
+  really self-heal?" check)
+- **Open questions** (any HALT stages needing the user)
+
+---
+
+## Step 4: Build decision
+
+- **No `--build` flag (default):** end with the plain-English summary and ask:
+  *"Build the simplest solution now?"* — offer it, do not proceed.
+- **`--build` flag:** proceed to implement the simplest solution immediately (still after
+  printing the summary). Follow the normal build discipline — smallest change that hits the
+  crux, Pre-Commit Gate, run affected tests. Report what was built.
+
+---
+
+## Document Ripple
+
+The underlying assessment updates (when it writes / when a build follows):
+- `.gsd-t/pseudocode/PseudoCode-<Target>.md` — the plain-English design (unless `--chat-only`).
+- `.gsd-t/progress.md` Decision Log — one line recording the architect run + verdict.
+- If `--build` produced code: the standard Pre-Commit Gate ripple (contracts, docs, tests) for
+  whatever the build touched.
+
+---
+
+## Notes
+
+- **This command plans; it does not force a build.** The default keeps the architect a pure
+  "think before build" gate. `--build` is the explicit opt-in to act on its own conclusion.
+- **Reuse over rebuild** (the doctrine obeying itself): this command is prose-driven and spawns
+  a single analysis subagent — it does NOT add a new workflow file. It reuses the existing
+  prose-command + Task-subagent pattern (like `/gsd-t-status`, `/gsd-t-impact`).
+- Standalone command — no successor in the Next-Up map.

package/commands/gsd-t-help.md

@@ -241,6 +241,13 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/impact-report.md`
 - **Use when**: Before making changes, to understand what might break
 
+### architect
+- **Summary**: Run the Architect's Oversight Six-Stage Pass (Objective → Conflict → Reuse → Simplicity → Reuse-forecast → Risk) on existing work — an already-frozen plan, a messy subsystem, or a pasted tangle of problems. Finds the simplest correct solution, what's already reusable (process or a stored value), and the traps each stage surfaces — written as plain-English pseudocode you can approve before any code.
+- **Auto-invoked**: No (standalone, on-demand)
+- **Args**: `/gsd-t-architect "<what to assess>"` — plus `--build` (auto-build the simplest fix after planning) and `--chat-only` (report in session, don't write a pseudocode file).
+- **Creates**: `.gsd-t/pseudocode/PseudoCode-<Target>.md` (unless `--chat-only`)
+- **Use when**: A plan already exists (or is half-formed) and you want it interrogated for simplicity + reuse before building; or a subsystem "got complicated over time" and you want the simplest version. Default is plan-only, then it offers to build.
+
 ### execute
 - **Summary**: Run tasks from plan, solo or with agent teams
 - **Auto-invoked**: Yes (in wave, after impact)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.20.10",
+  "version": "5.0.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-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.`,