@tekyzinc/gsd-t 5.6.11 → 5.8.10

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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)
+
+Several sessions ran against one project, each told to use its own git worktree. Three did. One worked directly in the main project folder, and its uncommitted work interleaved with another session's on the same branch — neither side able to commit or merge without dragging in or losing the other's half-finished milestone. The instruction was given; nothing enforced it.
+
+- `scripts/gsd-t-worktree-guard.js`: a PreToolUse hook on Write/Edit. Blocks an edit in the MAIN working tree when another GSD-T session is live there, and prints the exact `git worktree add` command — including the stash-and-carry form when the session already has uncommitted work. Silent when alone in main (working there solo is fine), silent inside a worktree, silent outside a git repo, and fail-open on any internal error: it detects a collision, it does not gate correctness.
+- Liveness reuses the per-session `.gsd-t/heartbeat-<id>.jsonl` file that the SessionStart/Stop/SessionEnd hooks already write INTO the tree the session works in. Its location is the claim; its modification time is the signal. No new bookkeeping.
+- **The liveness window is the load-bearing detail.** A first pass using two hours read three long-closed sessions as live and would have fired on a user working alone — the false positive that teaches someone to disable a guard. The window is five minutes: a working session writes constantly.
+- `bin/gsd-t.js`: the architect-hook registrar is generalized to take a marker + command, so registering a second Write|Edit hook needed no duplicated code. Registered on install, stripped on uninstall.
+- `test/m105-worktree-guard.test.js`: 13 tests. The fail-open case caught a real hole — unparseable hook input fell back to `process.cwd()`, so the guard judged whichever directory it happened to launch from rather than the one under edit. Unreadable input now means no decision.
+
+Opt out per project with `.gsd-t/worktree-guard-config.json` `{"enabled": false}`. An invalid config leaves the guard ON. Suite 3120/0/13-skip.
+
 ## [5.6.11] - 2026-08-02
 
 ### Fixed — four bugs that reported a healthy code graph as broken (M104)

package/README.md

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

@@ -494,6 +494,17 @@ const ARCHITECT_HOOK_MARKER = "gsd-t-architect-oversight-guard";
 const ARCHITECT_HOOK_COMMAND =
   'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-architect-oversight-guard.js" || true\'';
 
+// M105 — worktree-collision PreToolUse hook on Write|Edit. Same global-package
+// pattern. Blocks an edit when ANOTHER GSD-T session is live in the SAME working
+// tree (detected from the per-session heartbeat files already written into
+// .gsd-t/), and tells the user the exact `git worktree add` command to run.
+// Silent when working alone, silent inside a worktree, silent outside a repo,
+// and fail-open on any internal error — it detects a collision, it does not gate
+// correctness.
+const WORKTREE_HOOK_MARKER = "gsd-t-worktree-guard";
+const WORKTREE_HOOK_COMMAND =
+  'bash -c \'[ -f "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-worktree-guard.js" ] && node "$(npm root -g)/@tekyzinc/gsd-t/scripts/gsd-t-worktree-guard.js" || true\'';
+
 // Append entries to {projectDir}/.gitignore. Each entry added only if absent.
 // Idempotent. Returns true if any entries were added, false otherwise.
 function ensureGitignoreEntries(projectDir, entries) {
@@ -942,6 +953,17 @@ function configureReadInterceptHook(settingsPath) {
 // read-intercept installer but on PreToolUse. The script fails-open so this is
 // safe globally (silent in non-GSD-T projects and on prose/doc writes).
 function configureArchitectHook(settingsPath) {
+  return configureWriteEditHook(settingsPath, ARCHITECT_HOOK_MARKER, ARCHITECT_HOOK_COMMAND, "architect");
+}
+
+// M105 — register the worktree-collision guard. Reuses the same registrar rather
+// than copying it (the function below was architect-specific; generalized to take
+// the marker + command, so a third Write|Edit hook needs no new code).
+function configureWorktreeGuardHook(settingsPath) {
+  return configureWriteEditHook(settingsPath, WORKTREE_HOOK_MARKER, WORKTREE_HOOK_COMMAND, "worktree guard");
+}
+
+function configureWriteEditHook(settingsPath, marker, command, label) {
   const targetPath = settingsPath || SETTINGS_JSON;
   let settings = {};
   if (fs.existsSync(targetPath)) {
@@ -949,21 +971,21 @@ function configureArchitectHook(settingsPath) {
       settings = JSON.parse(fs.readFileSync(targetPath, "utf8"));
       if (!settings || typeof settings !== "object") settings = {};
     } catch {
-      warn("settings.json has invalid JSON — cannot configure architect hook");
+      warn(`settings.json has invalid JSON — cannot configure ${label} hook`);
       return { installed: false, action: "noop" };
     }
   }
   if (!settings.hooks) settings.hooks = {};
   if (!Array.isArray(settings.hooks.PreToolUse)) settings.hooks.PreToolUse = [];
 
-  const cmd = ARCHITECT_HOOK_COMMAND;
+  const cmd = command;
   let action = "noop";
   let found = false;
   for (const entry of settings.hooks.PreToolUse) {
     if (!entry || !Array.isArray(entry.hooks)) continue;
     for (const h of entry.hooks) {
       if (!h || typeof h.command !== "string") continue;
-      if (h.command === cmd || h.command.includes(ARCHITECT_HOOK_MARKER)) {
+      if (h.command === cmd || h.command.includes(marker)) {
         found = true;
         if (h.command !== cmd) { h.command = cmd; action = "updated"; }
         if (entry.matcher !== "Write|Edit") { entry.matcher = "Write|Edit"; action = action === "noop" ? "updated" : action; }
@@ -1007,7 +1029,7 @@ function removeInterceptHooks(settingsPath) {
   if (!settings.hooks) return false;
 
   const postMarkers = [GRAPH_INTERCEPT_HOOK_MARKER, READ_INTERCEPT_HOOK_MARKER];
-  const preMarkers = [ARCHITECT_HOOK_MARKER];
+  const preMarkers = [ARCHITECT_HOOK_MARKER, WORKTREE_HOOK_MARKER];
   let removed = 0;
 
   const stripByMarkers = (arr, markers) => {
@@ -2006,6 +2028,13 @@ async function doInstall(opts = {}) {
     else info("Architect-oversight hook already configured");
   }
 
+  const wtHook = configureWorktreeGuardHook(SETTINGS_JSON);
+  if (wtHook.installed) {
+    if (wtHook.action === "added") success("Worktree-collision guard added (blocks a second session editing the same tree — M105)");
+    else if (wtHook.action === "updated") success("Worktree-collision guard refreshed");
+    else info("Worktree-collision guard already configured");
+  }
+
   heading("Graph Engine (CGC)");
   installCgc();
 

package/commands/gsd-t-architect.md

@@ -14,6 +14,33 @@ Unlike the plan/milestone workflow (which runs the Six-Stage Pass *while generat
 this command runs it as a **standalone pass over existing work** — an already-frozen plan, a
 messy subsystem, or a pasted description of problems.
 
+**The measure of a good run is what happens AFTER it.** A run succeeded if the build it directed
+finished with few follow-ups and few bug fixes. A beautiful report that led to five rounds of
+rework is a FAILED run. Everything below exists to buy that outcome.
+
+---
+
+## Why the grounding loop exists (read this — it is the point of the command)
+
+An audit of 16 real architect runs found **21 corrections the user had to make. 13 of them were
+facts the user already held and would have given for free** — settled decisions the architect
+re-derived and got wrong, and real-world behavior it asserted from a saved page instead of asking.
+Only 4 of 16 runs needed no correction.
+
+The two dominant failures, both preventable by asking first:
+
+| Failure | Count | 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 a real-world fact the user knew was false** | 5 | *"I believe you're wrong. When scrolling the feed…"* (reasoned from a saved HTML file, not the live page) |
+| 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, missed the real one | 2 | *"Either we're having a miscommunication or you didn't find all the bugs."* |
+| Excluded a dimension the user held in scope | 2 | *"Now consider capture performance in the context of these changes."* |
+
+So: **ask before you reason.** The architect is not being thorough when it derives a constraint
+the user could have stated in one line — it is guessing in an expensive way.
+
 ---
 
 ## Argument Parsing
@@ -26,6 +53,11 @@ Parse `$ARGUMENTS`:
   (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/`.
+- **`--no-interview`** — skip the interview/research loop (Steps 1-3) and go straight to the
+  Six-Stage Pass. Step 0 (reading code + harvesting standing rules) ALWAYS runs — it costs the user
+  nothing. For a target already tightly scoped in the same session. Default: run the loop.
+- **`--no-research`** — run the interview but never the external research step. For work that is
+  purely internal to this repo. Default: research when confidence is low.
 
 If `$TARGET` is empty, ask the user what to assess. Do not guess.
 
@@ -33,29 +65,197 @@ 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
+1. **Ground before you assess.** Read → interview → research → loop until confident (Steps 1-3),
+   THEN run the Six-Stage Pass. Never open with the pass.
+2. **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,
+3. **`--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
+4. **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
+## Step 0: Read first — arrive with a draft understanding, not questions
+
+**Do this in the MAIN session** (not a subagent — subagents cannot talk to the user mid-run).
+
+Gather everything you can WITHOUT the user, so the interview spends their time only on what code
+cannot tell you:
+
+- **Read the target** — the named code/plan/files, their callers, the tests over them.
+- **Query the code graph** (`gsd-t graph`) for the reuse and duplication checks. Absent/empty
+  graph → grep instead and say so LOUDLY (reuse-detection is reduced; never a silent
+  "nothing found"). A BROKEN graph is a HALT, not a grep fallback.
+- **Harvest the standing rules — do NOT re-derive them.** Read, in this order:
+  - project `CLAUDE.md` + `~/.claude/CLAUDE.md` — hard constraints
+  - `.gsd-t/pseudocode/PseudoCode-*.md` for the touched area — especially each `[RULE]` guard map
+    and any `## ⚠ Divergence`
+  - `.gsd-t/contracts/` for the touched domains
+  - `.gsd-t/progress.md` Decision Log — the last ~30 days of entries touching these files
+- **Classify the target type** (drives the interview shape — see Step 1):
+  `bug-hunt` · `perf` · `plan-review` · `subsystem-audit` · `security/stealth`.
+- **Label every piece of evidence `LIVE` or `SNAPSHOT`.** A saved HTML file, a fixture, a stored
+  sample, a log from last week are all SNAPSHOT. **Any claim about runtime behavior that rests on
+  a SNAPSHOT must be marked as unproven and put to the user in the interview.** This is the exact
+  hole that produced *"FB only keeps about 6 to 8 posts visible at a time and virtualizes the
+  rest"* — the architect had measured a 4.5 MB saved feed and described it as the live page.
 
-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.
+---
+
+## Step 1: The interview — show your understanding, ask only what code can't answer
+
+**The interview is adaptive. It is NOT a fixed questionnaire.** Its shape follows the target type
+and what Step 0 left genuinely unresolved. Never ask a question you already answered by reading.
+
+### 1a — Lead with pseudocode of how it works TODAY (the confirmation artifact)
+
+Before any question, show the user **your read of the current behavior as a plain-English flow**,
+in the house style (nested decision tree, `pseudocode-source-of-truth-contract.md` §1.1). Then
+show **what you believe correct looks like**. Keep both short — this is a confirmation device, not
+the deliverable.
+
+This is the single highest-value move in the command: it surfaces a wrong premise in one line of
+the user's time instead of after a full wasted pass.
+
+```
+Here's how I believe it works today:
+
+  A comment arrives on screen
+    Do we already know the post's author:
+      Yes: Attach the comment to that post
+      No:  Read the post header now
+        Header readable:
+          Yes: Cache it, attach the comment
+          No:  Drop the comment
+
+And what I believe SHOULD happen: … (the same, in flow form)
+
+Is that right? Correct anything wrong before I go further.
+```
+
+### 1b — Ask the questions that matter for THIS target type
+
+Ask **2-5 questions max**, drawn from the branch below. Prefer specific over generic. Skip any the
+user's own request already answered.
+
+**ALWAYS ask, every type (these are the top-2 failure modes):**
+1. **Settled ground** — *"What decisions here are already made and NOT open for re-litigation?"*
+   Then **echo back the constraints you harvested in Step 0** so a stale one gets corrected in one
+   line. Format: *"I'm treating these as fixed: [list]. Correct any that have changed."*
+2. **What the code can't tell me** — *"What do you know about how this behaves in the real world
+   that I can't read from the code?"* — and name every SNAPSHOT-derived claim explicitly:
+   *"I'm inferring X from a saved page, not the live system. Is X actually true?"*
+
+**Type-specific branches:**
+
+| Target type | Ask about |
+|---|---|
+| **bug-hunt** | The observable symptom in the user's own words — *"what would you see on screen when it's fixed?"* · Existing evidence: *"do you have screenshots, saved HTML, traces, a prod query I should reason from?"* · Whether a thing you're about to call unavoidable really is — *"is this a genuine page/system limit, or a fallback hiding a fixable bug?"* · The business rule in the user's words when the bug touches one |
+| **perf** | Is the evidence a saved page or the live system? · What triggers the hot path, how often, driven by what? · **How will we measure before/after, and on whose machine?** (a perf verdict with no verification path is incomplete) · Re-assert the stealth/no-timer constraints |
+| **plan-review** | Deploy/merge order and who is using the system while this lands · Does it touch production data — is cleanup implied? · **Is any part of this plan already built?** (a past run proposed building things that already existed and were running) |
+| **subsystem-audit** | *"Do you want a map of what's there, or the single path to one clean design?"* · *"Which of these findings would be re-litigating something you already decided?"* |
+| **security/stealth** | Rank by what — risk, or the operational thing the user actually feels (smoothness, cost)? · Which other dimensions must this answer also satisfy? |
+
+### 1c — Get the evidence you cannot gather yourself
+
+You gather what you can; you ASK for the rest. Both, in the same breath:
 
-**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).
+> *"I pulled these myself: [files/functions/fixtures]. I can't get these from the repo — can you
+> provide them: [a captured HTML of a post that missed comments, a screenshot of the failure,
+> the prod row for order 4471]?"*
+
+Never silently proceed without evidence you know you need. Naming the gap is the job.
+
+---
+
+## Step 2: Research — only when you are not confident, and only after the interview
+
+**Gate:** after the interview, score your confidence in **the problem/solution landscape** — do you
+know how this class of problem is solved well, or are you about to invent an approach from your own
+priors? **Confident → skip research entirely.** Not confident → research.
+
+Research runs AFTER the interview (never before) so it does not anchor you on an external solution
+shape before you know the user's actual constraints — and so you never spend a search on a question
+the user would have answered in one line.
+
+**What to research** — how others have solved *this class of problem* recently: current library or
+platform behavior, known-good patterns, known failure modes, anything time-varying you'd otherwise
+assert from memory. Cite what you find (URL + date) per the auto-research rule; a time-varying
+external fact stated without a source is a guess.
+
+**When research contradicts a standing rule (e.g. the common solution uses a fallback, the project
+bans fallbacks): the user's rule wins, and you name the conflict in ONE line.** Not a debate:
+
+> *"The usual solution here catches the failure and retries with a default. Your no-fallback rule
+> bars that; the compliant version halts and reports instead. Say so if you want the fallback."*
+
+**The rare case where a fallback IS right — and how to tell.** The no-fallback rule exists because
+90%+ of fallbacks written were covering edge cases that never or rarely happen, papered over
+easily-fixable bugs, and created unpredictable downstream damage. It does not exist because
+fallbacks are never correct. A fallback is genuinely warranted only when **all** of these hold:
+
+- the primary path fails a **high** percentage of the time, and
+- the cause is **outside our control** (a third party, a network, a platform behavior we cannot
+  fix), and
+- completing the workflow is **critical** — stopping is worse than degrading.
+
+If all three hold, propose it explicitly with the evidence for each. If any fails — especially if
+the failure is a bug we could just fix — the answer is a **HALT**, not a fallback.
 
 ---
 
-## Step 2: The subagent runs the Six-Stage Pass (with EVIDENCE, never conviction)
+## Step 3: Loop until confident — max 3 cycles
+
+Interview and research feed each other. After research, if new questions surfaced, **go back and
+ask them**. If those answers open a new research gap, research again. Continue until you are
+confident you can direct a build that will not need rework.
+
+- **Cycle = one interview round (+ its research, if any).** Hard cap: **3 cycles.**
+- **Expected: 1-2 cycles resolve it ~90% of the time.** Needing 3 is a signal the target was
+  poorly bounded — say so.
+- **Do not pad.** If you are confident after the first round, stop and run the pass. Extra rounds
+  cost the user's time and buy nothing.
+- **At the cap, if you are STILL not confident: stop and ask the user which they want** — halt the
+  run, or proceed with the uncertainty flagged. Present the remaining unresolved questions and why
+  you could not resolve them, then let them choose. Do not decide this yourself.
+
+**Only when confident (or when the user says proceed) do you move to the Six-Stage Pass.**
+
+---
+
+## Step 4: 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 CONFIRMED GROUNDING from Steps 0-3, not just the raw target.** This is what the
+interview was for; a subagent that has to re-derive it will make the same mistakes again. Include:
+
+- `$TARGET` and this protocol
+- The **target type** (bug-hunt / perf / plan-review / subsystem-audit / security-stealth)
+- The **confirmed current-behavior flow** the user signed off in Step 1a — plus any correction
+  they made to it (their correction is now a FACT, not a hypothesis)
+- The **standing rules** the user confirmed as fixed — flagged **NOT open for re-litigation**
+- The **real-world facts the user supplied** that code cannot show — each marked as user-asserted
+- The **evidence inventory**, each item labelled `LIVE` or `SNAPSHOT`, plus anything the user
+  provided during the interview
+- The **research findings** with citations, if research ran — including any named rule-vs-practice
+  conflict
+- The **dimensions confirmed in scope** (performance, stealth, prod-data impact, deploy order …)
+- Any question the user declined to answer, marked **UNRESOLVED — do not assume**
+
+The subagent treats all of the above as settled input. If its analysis contradicts a confirmed
+item, that is a finding to SURFACE, never a premise to quietly overturn.
+
+Graph note: if a code graph exists (`.gsd-t/graphDB/graph.db` — resolve via
+`bin/gsd-t-graph-store-resolver.cjs`, never hardcode the path), 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").
+
+---
+
+## Step 5: 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.
@@ -81,10 +281,16 @@ The subagent works through the six stages IN ORDER. Each can kill or reshape the
    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.)
+   failing)? If yes, do NOT design it in — surface it as an OPEN QUESTION for the user. 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.
+   **The rare warranted case — all three must hold:** the primary path fails a HIGH percentage of
+   the time · the cause is OUTSIDE our control (third party / network / platform behavior we
+   cannot fix) · completing the workflow is CRITICAL (stopping is worse than degrading). Propose
+   it with evidence for each condition. If any fails — especially if the failure is a bug we could
+   simply fix — the answer is a HALT. **Also audit the EXISTING code in the target for fallbacks
+   that are themselves the bug**; a past run's root cause was literally *"it's your fallbacks that
+   are screwing up the system."* (See CLAUDE.md § No-Fallback-Ever Doctrine.)
 7. **SIMPLY-STATED** (clarity gate — the review is NOT done until this passes) — state every
    finding and the verdict SIMPLY: precise and complete, but every word load-bearing, the logic
    in a straight line, ZERO jargon standing in for a clear idea, no nested clauses hiding a
@@ -95,9 +301,23 @@ The subagent works through the six stages IN ORDER. Each can kill or reshape the
 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.
 
+**Standing checks — run these every pass, without being told.** Each was a correction the user had
+to make by hand in a past run. Treat a violation as a finding:
+
+| Check | Why |
+|---|---|
+| **Is a fallback the root cause here?** Audit existing fallbacks in the target, not just new ones | *"It's your fallbacks that are screwing up the system"* |
+| **Does the design leave data in limbo** (quarantined, held, parked for later recovery)? Prefer: record a trace and drop | *"Never quarantine because nothing quarantined would ever be recovered"* |
+| **Does it leave a legacy path alive alongside the new one?** Deleting the old path belongs in the same change | *"I want all legacy code removed… which keeps happening over and over again"* |
+| **Two mechanisms doing one job** → propose the route to ONE, don't present it as a trade-off | *"Stop telling me rather or two. Just tell me how we get to one."* |
+| **Does it state a verification path** — how we'd prove it worked, and on whose machine? | *"How do you analyze and verify?"* |
+| **Production-data impact + cleanup**, before any migration or merge | asked unprompted across three runs |
+| **Is any claim about live behavior resting on a SNAPSHOT?** Label it; never state it as observed | the saved-feed virtualization error |
+| **Are the always-in-scope dimensions covered** — performance on user-facing paths, plus any project hard-constraint (stealth, security, cost)? | *"Now consider capture performance in the context of these changes"* |
+
 ---
 
-## Step 3: The subagent produces the output
+## Step 6: The subagent produces the output
 
 **A — Plain-English pseudocode** (the artifact), in the house style defined by contract
 `.gsd-t/contracts/pseudocode-source-of-truth-contract.md` **§1.1** and the mold
@@ -127,6 +347,12 @@ in the flow). For each "what it does today" flow, say **why it does what it does
 explicitly if it's a "got complicated over time" accretion (mechanisms stacked by successive
 fixes).
 
+Also below the divider: **`## What I confirmed with you`** — the grounding record. The
+user-confirmed current behavior, the rules held fixed, the real-world facts they supplied, the
+research sources (if any), and anything left unresolved. `## What it does today` must match what
+the user confirmed in the interview; if the analysis later contradicted it, that belongs in
+`## ⚠ Divergence`, not a quiet rewrite.
+
 Worked reference: `.gsd-t/pseudocode/PseudoCode-BrokenGraphHalts.md`. Unless `--chat-only`, write
 the artifact to `.gsd-t/pseudocode/PseudoCode-<Target>.md`, then **self-check it** with
 `gsd-t pseudocode-style --doc <the file>` — a non-zero exit means the style is wrong; fix it
@@ -144,11 +370,19 @@ before presenting. (The same gate is FAIL-blocking in verify.)
 - **Simplest solution** (one paragraph)
 - **Traps surfaced** (each stage's kill/risk finding — especially the Stage-6 "does the fix
   really self-heal?" check)
+- **Grounded on** (2-4 lines, always) — what the user confirmed in the interview that the analysis
+  rests on, what research found (with sources) if it ran, and how many interview cycles it took.
+  This makes a wrong premise visible at a glance instead of buried in the reasoning.
 - **Open questions** (any HALT stages needing the user)
 
+**Output constraints (hard — these were real complaints):** plain English in the lead, no
+file:line grids up top, no architect shorthand. *"Try again without any jargon. I don't understand
+the grid."* and *"I don't understand any of this explanation… It's way too long, too wordy."* Put
+code identifiers below the divider in the artifact, never in the summary lead.
+
 ---
 
-## Step 4: Build decision
+## Step 7: Build decision
 
 - **No `--build` flag (default):** end with the plain-English summary and ask:
   *"Build the simplest solution now?"* — offer it, do not proceed.
@@ -175,4 +409,13 @@ The underlying assessment updates (when it writes / when a build follows):
 - **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`).
+- **The interview runs in the MAIN session, the pass runs in a subagent.** A subagent cannot ask
+  the user anything mid-run — relaying questions out as teammate pings was tried and produced
+  babysitting (*"Is the architect still running?"*). So: ground it in the main chat where a real
+  back-and-forth works, then hand the confirmed grounding to a fresh context for the analysis.
+- **Asking is cheaper than deriving.** The audit at the top of this file is the justification: the
+  architect's most common failure was spending reasoning on facts the user would have stated in
+  one line. When torn between inferring and asking — ask.
+- **Cycle discipline.** 1-2 grounding cycles should cover ~90% of runs. Needing 3 means the target
+  was poorly bounded; say so rather than absorbing it silently.
 - Standalone command — no successor in the Next-Up map.

package/commands/gsd-t-help.md

@@ -242,11 +242,13 @@ Use these when user asks for help on a specific command:
 - **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.
+- **Summary**: Grounds itself with you FIRST, then runs 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.
+- **Grounding loop (before the pass)**: reads the code + your standing rules → **interviews you** (shows its read of how the thing works today as a plain-English flow for you to confirm or correct, then asks only what code can't answer — questions branch by target type: bug / performance / plan-review / audit / security) → **researches** how others solve this class of problem, but only when it isn't confident and only after the interview → loops if new questions surface. **Max 3 cycles** (1-2 expected); still unsure at the cap → it asks whether to halt or proceed with the uncertainty flagged.
 - **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).
+- **Args**: `/gsd-t-architect "<what to assess>"` — plus `--build` (auto-build the simplest fix after planning), `--chat-only` (report in session, don't write a pseudocode file), `--no-interview` (skip the grounding loop when the target is already tightly scoped), `--no-research` (interview but never search externally).
 - **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.
+- **Why the interview**: an audit of 16 real runs found 21 corrections — 13 were facts the user already held and would have given for free (settled rules it re-derived wrong, runtime behavior it asserted from a saved page). Asking first is cheaper than deriving.
 
 ### execute
 - **Summary**: Run tasks from plan, solo or with agent teams

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.6.11",
+  "version": "5.8.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/scripts/gsd-t-worktree-guard.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * gsd-t-worktree-guard.js — PreToolUse(Write|Edit)
+ *
+ * Stops two sessions from editing the SAME working tree at the same time.
+ *
+ * The problem it solves: a session opened in the main project folder edits files
+ * there; a second session opens in the same folder and does the same. Their
+ * uncommitted work interleaves in one tree, on one branch, and neither can commit
+ * or merge without dragging in the other's half-finished milestone. Telling each
+ * session "use a worktree" does not prevent it — nothing enforces the instruction.
+ *
+ * How it detects a live session, and why: every GSD-T session writes
+ * `.gsd-t/heartbeat-<session-id>.jsonl` INSIDE the tree it is working in, via the
+ * SessionStart/Stop/SessionEnd hooks. The file's location IS the claim (a session
+ * in a worktree writes into that worktree's own .gsd-t/), and its modification
+ * time is the liveness signal. No new bookkeeping — the file already exists.
+ *
+ * Liveness is a SHORT window (default 5 min). A working session writes constantly;
+ * one silent for longer is idle or closed. This matters more than it looks: a
+ * 2-hour window reads three closed sessions as live and fires on a user working
+ * alone, which trains them to disable the guard.
+ *
+ * Behaviour:
+ *   - alone in any tree               → silent, no guard (working in main alone is allowed)
+ *   - main tree, another session live → BLOCK with the exact worktree command to run
+ *   - inside a worktree               → silent (already isolated)
+ *
+ * Fail-open by design: a guard that cannot read its inputs must not block edits.
+ * It is a collision detector, not a correctness gate — a crash here would stop
+ * legitimate work for no safety benefit.
+ *
+ * Opt out per project: .gsd-t/worktree-guard-config.json {"enabled": false}
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const LIVE_WINDOW_MS = 5 * 60 * 1000;
+
+// Returns null when the hook payload cannot be read or parsed.
+//
+// This must NOT fall back to an empty object: `cwd` would then default to
+// process.cwd() and the guard would judge whatever directory it happened to be
+// launched from — deciding about the wrong repository entirely. Caught by the
+// fail-open test, which saw a deny emitted for garbage input.
+// Unreadable input means NO DECISION, never a decision about the wrong tree.
+function readHookInput() {
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (!raw || !raw.trim()) return null;
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function git(args, cwd) {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+// The MAIN working tree is the one whose .git is a directory. A linked worktree's
+// .git is a FILE containing a gitdir: pointer — that is the distinction git itself
+// uses, so it needs no parsing of `git worktree list` output.
+function isMainWorktree(root) {
+  try {
+    return fs.statSync(path.join(root, ".git")).isDirectory();
+  } catch (_) {
+    return false;
+  }
+}
+
+function guardEnabled(root) {
+  try {
+    const cfg = JSON.parse(
+      fs.readFileSync(path.join(root, ".gsd-t", "worktree-guard-config.json"), "utf8")
+    );
+    return cfg.enabled !== false;
+  } catch (_) {
+    return true; // absent/invalid config → guard on
+  }
+}
+
+// Sessions whose heartbeat is fresh, excluding this one.
+function liveSessions(root, selfSid, now) {
+  const dir = path.join(root, ".gsd-t");
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (_) {
+    return [];
+  }
+  const live = [];
+  for (const f of names) {
+    if (!f.startsWith("heartbeat-") || !f.endsWith(".jsonl")) continue;
+    const sid = f.slice("heartbeat-".length, -".jsonl".length);
+    if (selfSid && sid === selfSid) continue;
+    try {
+      const age = now - fs.statSync(path.join(dir, f)).mtimeMs;
+      if (age < LIVE_WINDOW_MS) live.push({ sid, ageMs: age });
+    } catch (_) { /* unreadable → not evidence of a live session */ }
+  }
+  return live.sort((a, b) => a.ageMs - b.ageMs);
+}
+
+function suggestWorktreeName(branch) {
+  const base = (branch || "work").replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+  return base || "work";
+}
+
+function main() {
+  const hook = readHookInput();
+  if (!hook) return; // no readable payload → no decision (see readHookInput)
+  const cwd = hook.cwd;
+  if (!cwd || typeof cwd !== "string") return; // no stated directory → nothing to judge
+
+  const root = git(["rev-parse", "--show-toplevel"], cwd);
+  if (!root) return; // not a git repo → nothing to guard
+
+  if (!isMainWorktree(root)) return; // already isolated in a worktree
+  if (!guardEnabled(root)) return;
+
+  const selfSid = hook.session_id || hook.sessionId || null;
+  const others = liveSessions(root, selfSid, Date.now());
+  if (others.length === 0) return; // alone → working in main is allowed
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], root) || "HEAD";
+  const project = path.basename(root);
+  const name = suggestWorktreeName(branch);
+  const wt = `${process.env.HOME}/Worktrees/${project}/${name}`;
+  const mins = Math.max(1, Math.round(others[0].ageMs / 60000));
+  const plural = others.length === 1 ? "session" : "sessions";
+
+  const reason = [
+    `Another GSD-T ${plural} (${others.length}) is working in this same folder right now — the most recent wrote ${mins} minute(s) ago.`,
+    ``,
+    `Editing here means two sessions share one working tree and one branch. Their uncommitted changes interleave, and neither can commit or merge without dragging in the other's half-finished work.`,
+    ``,
+    `Move to your own worktree first:`,
+    ``,
+    `  mkdir -p ${process.env.HOME}/Worktrees/${project}`,
+    `  git worktree add ${wt} -b ${name}-$(date +%H%M)`,
+    `  cd ${wt}`,
+    ``,
+    `If you already have uncommitted work in this folder, carry it across:`,
+    ``,
+    `  git stash push -u -m "moving to a worktree"`,
+    `  git worktree add ${wt} -b ${name}-$(date +%H%M)`,
+    `  cd ${wt} && git stash pop`,
+    ``,
+    `Working alone in the main folder is fine — this only fires when a second session is live.`,
+    `To turn it off for this project: .gsd-t/worktree-guard-config.json {"enabled": false}`,
+  ].join("\n");
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    }) + "\n"
+  );
+}
+
+try {
+  main();
+} catch (_) {
+  // Fail open — never block an edit because the guard itself broke.
+}

package/templates/CLAUDE-global.md

@@ -150,6 +150,8 @@ WHEN creating a worktree directly (git worktree add, isolation: "worktree", etc.
 - Clean up with `git worktree remove` when the branch/task is done — don't leave prunable stragglers.
 - **Exception**: harness-managed worktrees the Agent/Workflow runtime creates under the project's gitignored `.claude/worktrees/` path are the harness's own convention — leave those alone. This rule governs worktrees *you* create directly via Bash or the `isolation: "worktree"` option.
 
+**One session per working tree (M105 — enforced).** Two sessions editing the same folder interleave their uncommitted work on one branch: neither can commit or merge without dragging in or losing the other's half-finished milestone. A PreToolUse guard (`scripts/gsd-t-worktree-guard.js`) BLOCKS a Write/Edit in the main tree when another GSD-T session is live there, and prints the exact `git worktree add` command (including the stash-and-carry form when you already have uncommitted work). Liveness comes from the per-session `.gsd-t/heartbeat-<id>.jsonl` file — location is the claim, mtime is liveness, 5-minute window. It is SILENT when you are alone in the main tree (working there solo is fine), silent inside a worktree, and fails open. Opt out per project: `.gsd-t/worktree-guard-config.json` `{"enabled": false}`.
+
 # Destructive Action Guard (MANDATORY)
 
 **NEVER perform destructive or structural changes without explicit user approval.** This applies at ALL autonomy levels, including Level 3.
@@ -447,10 +449,12 @@ 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
+**Contract:** `.gsd-t/contracts/architects-oversight-contract.md` v1.1.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*.
 
+**§Stage 0 — GROUND BEFORE YOU ASSESS (runs first; contract §0).** A field audit of 16 real architect runs found 21 user corrections, and **13 of them were facts the user already held** — settled rules the architect re-derived and got wrong ("that rule was implemented last week"), and runtime behavior it asserted from a saved page instead of asking ("I believe you're wrong. When scrolling the feed…"). **Asking is cheaper than deriving.** So before the pass: read the code AND the standing rules (CLAUDE.md constraints, `[RULE]` guard maps, contracts, recent Decision Log); label every evidence item **LIVE or SNAPSHOT** (a runtime claim resting on a snapshot is unproven); then **interview the user** — lead by showing your read of *how it works today* as a plain-English flow for confirmation, echo back the rules you're treating as fixed, and ask only what code cannot answer. **Research** (how others solve this class of problem) runs only when you're not confident, and only AFTER the interview so it can't anchor the questions. Loop interview↔research, **max 3 cycles** (1-2 expected); still unsure at the cap → ask the user whether to halt or proceed with the uncertainty flagged. A run succeeded if the build it directed needed few follow-ups — not if the report read well.
+
 **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.)*