gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts

@@ -15,6 +15,9 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { registerDbTools } from "../bootstrap/db-tools.ts";
 import { Value } from "@sinclair/typebox/value";
+import AjvModule from "ajv";
+
+const Ajv = (AjvModule as any).default || AjvModule;
 
 // ─── Mock PI ──────────────────────────────────────────────────────────────────
 
@@ -47,6 +50,37 @@ function getOptionalProps(tool: any): string[] {
   return allProps.filter((p: string) => !required.has(p));
 }
 
+// ─── gsd_summary_save: OpenAI requires top-level object schema ──────────────
+
+test("gsd_summary_save — parameters are a top-level object schema", () => {
+  const tool = getTool("gsd_summary_save");
+  assert.ok(tool, "gsd_summary_save must be registered");
+
+  assert.strictEqual(tool.parameters.type, "object", "OpenAI function parameters require a top-level object schema");
+  assert.ok(!("anyOf" in tool.parameters), "top-level anyOf is rejected by OpenAI function schema validation");
+
+  const required = new Set(getRequiredProps(tool));
+  assert.ok(required.has("artifact_type"), "artifact_type must be required");
+  assert.ok(required.has("content"), "content must be required");
+  assert.ok(!required.has("milestone_id"), "milestone_id must remain optional for root artifacts");
+});
+
+test("gsd_summary_save — validates UAT assessment params", () => {
+  const tool = getTool("gsd_summary_save");
+  assert.ok(tool, "gsd_summary_save must be registered");
+
+  const ajv = new Ajv({ strict: false });
+  const validate = ajv.compile(tool.parameters);
+  const valid = validate({
+    milestone_id: "M001",
+    slice_id: "S01",
+    artifact_type: "ASSESSMENT",
+    content: "---\nverdict: PASS\n---\n# UAT Assessment\n",
+  });
+
+  assert.strictEqual(valid, true, `UAT assessment params should validate but got errors: ${JSON.stringify(validate.errors)}`);
+});
+
 // ─── gsd_slice_complete: enrichment arrays must be optional ──────────────────
 
 test("gsd_slice_complete — enrichment arrays are optional", () => {

package/src/resources/extensions/gsd/tests/unit-context-manifest.test.ts

@@ -15,6 +15,7 @@ import {
   type SkillsPolicy,
   type UnitContextManifest,
 } from "../unit-context-manifest.ts";
+import { ALLOWED_PLANNING_DISPATCH_AGENTS } from "../bootstrap/write-gate.ts";
 
 // ─── Coverage: every known unit type has a manifest ──────────────────────
 
@@ -231,6 +232,11 @@ test('planning-dispatch mode is reserved for slice-level decomposition and compl
     "refine-slice",
     "complete-slice",
     "complete-milestone",
+    // Deep planning mode: research-project orchestrates 4 parallel research
+    // subagents (stack/features/architecture/pitfalls). Subagent dispatch is
+    // the unit's core mechanism — without it, the unit cannot do its job.
+    "research-project",
+    "validate-milestone",
   ]);
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     const mode = (manifest as { tools: { mode: string } }).tools.mode;
@@ -256,6 +262,10 @@ test('planning-dispatch manifests declare non-empty allowedSubagents lists', ()
         typeof agent === "string" && agent.length > 0,
         `manifest "${unitType}" has empty/invalid allowedSubagents entry: ${JSON.stringify(agent)}`,
       );
+      assert.ok(
+        ALLOWED_PLANNING_DISPATCH_AGENTS.has(agent),
+        `manifest "${unitType}" allows "${agent}", but the runtime planning-dispatch registry will hard-block it`,
+      );
     }
   }
 });

package/src/resources/extensions/gsd/tests/unit-runtime.test.ts

@@ -253,5 +253,46 @@ console.log("\n=== must-haves: substring matching (no backtick tokens) ===");
   assert.ok(diag.includes("2 of 3"), "mh-substr: diagnostic includes '2 of 3'");
 }
 
+console.log("\n=== per-record lock: stale .lock is reclaimed, list ignores .lock files ===");
+{
+  const { utimesSync, existsSync: lockExists } = await import("node:fs");
+  const { listUnitRuntimeRecords } = await import("../unit-runtime.ts");
+
+  // (1) Stale .lock should not block a new writer.
+  const lockBase = mkdtempSync(join(tmpdir(), "gsd-runtime-lock-test-"));
+  try {
+    const unitsDir = join(lockBase, ".gsd", "runtime", "units");
+    mkdirSync(unitsDir, { recursive: true });
+    const recordPath = join(unitsDir, "execute-task-M001-S01-T01.json");
+    const lockPath = recordPath + ".lock";
+    writeFileSync(lockPath, "");
+    const staleTime = new Date(Date.now() - 60_000);
+    utimesSync(lockPath, staleTime, staleTime);
+
+    const written = writeUnitRuntimeRecord(lockBase, "execute-task", "M001/S01/T01", 1000, { phase: "dispatched" });
+    assert.deepStrictEqual(written.phase, "dispatched", "stale-lock path should not block writers");
+
+    const readBack = readUnitRuntimeRecord(lockBase, "execute-task", "M001/S01/T01");
+    assert.ok(readBack !== null, "record persisted after stealing stale lock");
+    assert.equal(lockExists(lockPath), false, "lock file released after write completes");
+  } finally {
+    rmSync(lockBase, { recursive: true, force: true });
+  }
+
+  // (2) Orphaned .lock files must not be returned by listUnitRuntimeRecords.
+  const listBase = mkdtempSync(join(tmpdir(), "gsd-runtime-list-test-"));
+  try {
+    writeUnitRuntimeRecord(listBase, "execute-task", "M002/S01/T01", 1000, { phase: "dispatched" });
+    const unitsDir = join(listBase, ".gsd", "runtime", "units");
+    writeFileSync(join(unitsDir, "execute-task-M002-S01-T01.json.lock"), "");
+
+    const records = listUnitRuntimeRecords(listBase);
+    assert.equal(records.length, 1, "listUnitRuntimeRecords filters .lock files (only the .json record)");
+    assert.equal(records[0].unitId, "M002/S01/T01");
+  } finally {
+    rmSync(listBase, { recursive: true, force: true });
+  }
+}
+
 rmSync(mhBase, { recursive: true, force: true });
 rmSync(base, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts

@@ -16,6 +16,7 @@ import type { GSDState, Phase } from "../types.ts";
 import {
   ensurePlanV2Graph,
   hasFinalizedMilestoneContext,
+  isEmptyPlanV2GraphResult,
   isMissingFinalizedContextResult,
 } from "../uok/plan-v2.ts";
 
@@ -113,6 +114,30 @@ test("guided flow routes recoverable missing finalized context to discuss-milest
   );
 });
 
+test("guided flow checks pending deep setup before plan-v2 gate", () => {
+  const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
+  const showSmartEntryIdx = source.indexOf("export async function showSmartEntry");
+  assert.notEqual(showSmartEntryIdx, -1);
+  const deepIdx = source.indexOf("hasPendingDeepStage(prefs, basePath)", showSmartEntryIdx);
+  const planIdx = source.indexOf("runPlanV2Gate(ctx, basePath, state)", showSmartEntryIdx);
+  assert.ok(
+    deepIdx > -1 && planIdx > -1 && deepIdx < planIdx,
+    "foreground deep setup must run before plan-v2 can fail-close guided /gsd",
+  );
+  assert.ok(
+    source.includes("loadEffectiveGSDPreferences(basePath)?.preferences"),
+    "guided plan-v2 gate must load preferences from the target project root",
+  );
+});
+
+test("auto pre-dispatch uses resolved plan-v2 defaults", () => {
+  const source = readFileSync(join(gsdDir, "auto", "phases.ts"), "utf-8");
+  assert.ok(
+    source.includes("uokFlags.planV2 && shouldRunPlanV2Gate(state.phase)"),
+    "auto-mode should honor resolveUokFlags defaults, not only explicit uok.plan_v2.enabled",
+  );
+});
+
 test("plan-v2 gate fails closed for execution phase when finalized context is missing", () => {
   const basePath = createBasePath();
   seedGraphRows();
@@ -204,4 +229,27 @@ test("plan-v2 ensure rejects empty executable graph", () => {
   const compiled = ensurePlanV2Graph(basePath, buildState("executing"));
   assert.equal(compiled.ok, false);
   assert.match(compiled.reason ?? "", /compiled graph is empty/i);
+  assert.equal(isEmptyPlanV2GraphResult(compiled), true);
+});
+
+test("plan-v2 allows empty graph for milestone terminal phases", () => {
+  const basePath = createBasePath();
+  writeMilestoneFile(basePath, "CONTEXT", "Finalized context.");
+
+  insertMilestone({ id: MILESTONE_ID, title: "Milestone", status: "active" });
+  insertSlice({
+    id: SLICE_ID,
+    milestoneId: MILESTONE_ID,
+    title: "Slice",
+    status: "complete",
+    sequence: 1,
+  });
+
+  const validating = ensurePlanV2Graph(basePath, buildState("validating-milestone"));
+  assert.equal(validating.ok, true);
+  assert.equal(validating.nodeCount, 0);
+
+  const completing = ensurePlanV2Graph(basePath, buildState("completing-milestone"));
+  assert.equal(completing.ok, true);
+  assert.equal(completing.nodeCount, 0);
 });

package/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts

@@ -85,7 +85,7 @@ describe("handleValidateMilestone write ordering (#2725)", () => {
     assert.doesNotMatch(validationMd, /## Verification Class Compliance/);
   });
 
-  it("rolls back DB row when disk write fails", async () => {
+  it("keeps DB row and reports stale projection when disk write fails", async () => {
     base = makeTmpBase();
     const dbPath = join(base, ".gsd", "gsd.db");
     openDatabase(dbPath);
@@ -101,16 +101,15 @@ describe("handleValidateMilestone write ordering (#2725)", () => {
 
     const result = await handleValidateMilestone(VALID_PARAMS, base);
 
-    // Should return error
-    assert.ok("error" in result, "should return error when disk write fails");
-    assert.ok(result.error.includes("disk render failed"));
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+    assert.equal(result.stale, true, "result should report stale projection");
 
-    // DB row should have been rolled back (deleted)
     const adapter = _getAdapter()!;
     const row = adapter.prepare(
-      `SELECT * FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`,
-    ).get();
-    assert.equal(row, undefined, "assessment row should be deleted after disk-write rollback");
+      `SELECT status FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`,
+    ).get() as { status: string } | undefined;
+    assert.ok(row, "assessment row should remain committed");
+    assert.equal(row!.status, "pass");
   });
 
   it("persists milestone validation gate_runs rows when UOK gates are enabled", async () => {

package/src/resources/extensions/gsd/tests/validate-milestone.test.ts

@@ -394,7 +394,7 @@ test("dispatch rule skips when skip_milestone_validation preference is set", asy
   }
 });
 
-test("dispatch rule fails closed for failure-path SUMMARY when DB milestone is not complete (#4658)", async () => {
+test("dispatch rule ignores failure-path SUMMARY projection when DB milestone is not complete (#4658 superseded)", async () => {
   const state: GSDState = {
     activeMilestone: { id: "M001", title: "Test" },
     activeSlice: null,
@@ -422,17 +422,14 @@ test("dispatch rule fails closed for failure-path SUMMARY when DB milestone is n
       prefs: undefined,
     };
     const result = await resolveDispatch(ctx);
-    assert.equal(result.action, "stop");
-    if (result.action === "stop") {
-      assert.equal(result.level, "warning");
-      assert.match(result.reason, /failure-path SUMMARY/i);
-    }
+    assert.equal(result.action, "dispatch");
+    assert.equal(getMilestone("M001")?.status, "active");
   } finally {
     cleanup(base);
   }
 });
 
-test("dispatch rule reconciles DB for successful stale SUMMARY (#4658)", async () => {
+test("dispatch rule does not reconcile DB from successful stale SUMMARY projection (#4658 superseded)", async () => {
   const state: GSDState = {
     activeMilestone: { id: "M001", title: "Test" },
     activeSlice: null,
@@ -473,15 +470,15 @@ test("dispatch rule reconciles DB for successful stale SUMMARY (#4658)", async (
       prefs: undefined,
     };
     const result = await resolveDispatch(ctx);
-    assert.equal(result.action, "skip");
+    assert.equal(result.action, "dispatch");
     const milestone = getMilestone("M001");
-    assert.equal(milestone?.status, "complete");
+    assert.equal(milestone?.status, "active");
   } finally {
     cleanup(base);
   }
 });
 
-test("dispatch rule fails closed for ambiguous stale SUMMARY (#4658)", async () => {
+test("dispatch rule ignores ambiguous stale SUMMARY projection (#4658 superseded)", async () => {
   const state: GSDState = {
     activeMilestone: { id: "M001", title: "Test" },
     activeSlice: null,
@@ -509,11 +506,8 @@ test("dispatch rule fails closed for ambiguous stale SUMMARY (#4658)", async ()
       prefs: undefined,
     };
     const result = await resolveDispatch(ctx);
-    assert.equal(result.action, "stop");
-    if (result.action === "stop") {
-      assert.equal(result.level, "warning");
-      assert.match(result.reason, /ambiguous SUMMARY/i);
-    }
+    assert.equal(result.action, "dispatch");
+    assert.equal(getMilestone("M001")?.status, "active");
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts

@@ -19,7 +19,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { verifyExpectedArtifact } from "../auto-recovery.ts";
-import { closeDatabase, isDbAvailable } from "../gsd-db.ts";
+import { closeDatabase, insertMilestone, insertSlice, insertTask, isDbAvailable, openDatabase } from "../gsd-db.ts";
 
 /** Scaffold .gsd/milestones/M001/slices/S01/ with tasks/ and a T01-SUMMARY.md. */
 function scaffoldProject(t: { after: (fn: () => void) => void }): {
@@ -151,3 +151,54 @@ test("#3607: execute-task legacy branch — wrong task id in checkbox does not m
     "checkbox for a different task id must not count as T01 completion",
   );
 });
+
+test("execute-task DB lag branch — pending DB status can verify from checked plan plus summary", (t) => {
+  closeDatabase();
+  const { base, planPath } = scaffoldProject(t);
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  assert.equal(isDbAvailable(), true, "DB must be open to hit the DB-lag branch");
+
+  insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Implement feature", status: "pending" });
+
+  writeFileSync(
+    planPath,
+    [
+      "# S01 plan",
+      "",
+      "- [x] **T01: Implement feature**",
+    ].join("\n"),
+  );
+
+  assert.equal(
+    verifyExpectedArtifact("execute-task", "M001/S01/T01", base),
+    true,
+    "checked plan entry plus summary should verify while DB reconcile catches up",
+  );
+});
+
+test("execute-task DB lag branch — summary without checked plan still fails", (t) => {
+  closeDatabase();
+  const { base, planPath } = scaffoldProject(t);
+  openDatabase(join(base, ".gsd", "gsd.db"));
+
+  insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Implement feature", status: "pending" });
+
+  writeFileSync(
+    planPath,
+    [
+      "# S01 plan",
+      "",
+      "- [ ] **T01: Implement feature**",
+    ].join("\n"),
+  );
+
+  assert.equal(
+    verifyExpectedArtifact("execute-task", "M001/S01/T01", base),
+    false,
+    "pending DB status plus summary is insufficient without a checked task checkbox",
+  );
+});

package/src/resources/extensions/gsd/tests/workflow-logger-wiring.test.ts

@@ -205,17 +205,22 @@ test("readTransaction logs ROLLBACK failures as split-brain signal", () => {
   );
 });
 
-// ─── Runtime: state.ts and workflow-projections.ts log silent bailouts ─────
+// ─── Runtime: startup/projection diagnostics stay explicit ─────────────────
 
-test("state.ts logs roadmap read failures instead of silently continuing", () => {
-  const stateSrc = readFileSync(
-    join(import.meta.dirname, "..", "state.ts"),
+test("auto-start initializes the DB without implicit markdown migration", () => {
+  const autoStartSrc = readFileSync(
+    join(import.meta.dirname, "..", "auto-start.ts"),
     "utf-8",
   );
+  assert.doesNotMatch(
+    autoStartSrc,
+    /migrateFromMarkdown|md-importer/,
+    "auto-start must not import markdown into the runtime DB implicitly",
+  );
   assert.match(
-    stateSrc,
-    /logWarning\("state",\s*"reconcileDiskToDb: roadmap read failed/,
-    "state.ts reconcileDiskToDb should log roadmap read failures",
+    autoStartSrc,
+    /failed to initialize project database/,
+    "DB initialization failures should still be logged",
   );
 });
 

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -15,7 +15,7 @@ test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport"
   assert.equal(result, true);
 });
 
-test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is ready", () => {
+test("shouldAutoPrepareWorkflowMcp stays disabled for non-Claude active provider even when claude-code is ready", () => {
   const result = shouldAutoPrepareWorkflowMcp({
     model: { provider: "openai", baseUrl: "https://api.openai.com" },
     modelRegistry: {
@@ -24,10 +24,10 @@ test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is rea
     },
   });
 
-  assert.equal(result, true);
+  assert.equal(result, false);
 });
 
-test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is registered", () => {
+test("shouldAutoPrepareWorkflowMcp stays disabled for non-Claude active provider even when claude-code is registered", () => {
   const result = shouldAutoPrepareWorkflowMcp({
     model: { provider: "openai", baseUrl: "https://api.openai.com" },
     modelRegistry: {
@@ -36,7 +36,7 @@ test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is reg
     },
   });
 
-  assert.equal(result, true);
+  assert.equal(result, false);
 });
 
 test("shouldAutoPrepareWorkflowMcp stays disabled when neither transport nor provider readiness match", () => {

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -30,6 +30,17 @@ function readSrc(file: string): string {
   return readFileSync(join(gsdDir, file), "utf-8");
 }
 
+function listTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) out.push(...listTsFiles(full));
+    else if (entry.endsWith(".ts")) out.push(full);
+  }
+  return out;
+}
+
 function extractElicitPayload(request: unknown): ElicitPayload {
   const payload = (request as { params?: unknown }).params ?? request;
   return payload as ElicitPayload;
@@ -43,6 +54,33 @@ test("auto execute-task requires legacy completion alias until prompt contract i
   assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_complete_task"]);
 });
 
+test("deep project setup units declare required workflow MCP tools", () => {
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("discuss-project"), [
+    "ask_user_questions",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("discuss-requirements"), [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("research-decision"), [
+    "ask_user_questions",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("discuss-project"), [
+    "ask_user_questions",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("discuss-requirements"), [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("research-decision"), [
+    "ask_user_questions",
+  ]);
+});
+
 test("detectWorkflowMcpLaunchConfig prefers explicit env override", () => {
   const launch = detectWorkflowMcpLaunchConfig("/tmp/project", {
     GSD_WORKFLOW_MCP_NAME: "workflow-tools",
@@ -62,12 +100,29 @@ test("detectWorkflowMcpLaunchConfig prefers explicit env override", () => {
   });
   assert.equal(launch?.env?.FOO, "bar");
   assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd");
+  assert.equal(launch?.env?.GSD_BIN_PATH, "/tmp/gsd");
   assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
 });
 
+test("detectWorkflowMcpLaunchConfig normalizes explicit workflow MCP env CLI aliases", () => {
+  const binOnly = detectWorkflowMcpLaunchConfig("/tmp/project", {
+    GSD_WORKFLOW_MCP_COMMAND: "node",
+    GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_BIN_PATH: "/tmp/gsd-bin" }),
+  });
+  assert.equal(binOnly?.env?.GSD_CLI_PATH, "/tmp/gsd-bin");
+  assert.equal(binOnly?.env?.GSD_BIN_PATH, "/tmp/gsd-bin");
+
+  const cliOnly = detectWorkflowMcpLaunchConfig("/tmp/project", {
+    GSD_WORKFLOW_MCP_COMMAND: "node",
+    GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd-cli" }),
+  });
+  assert.equal(cliOnly?.env?.GSD_CLI_PATH, "/tmp/gsd-cli");
+  assert.equal(cliOnly?.env?.GSD_BIN_PATH, "/tmp/gsd-cli");
+});
+
 test("buildWorkflowMcpServers mirrors explicit launch config", () => {
   const servers = buildWorkflowMcpServers("/tmp/project", {
     GSD_WORKFLOW_MCP_COMMAND: "node",
@@ -135,6 +190,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server from GSD_BIN_PAT
     env: launch?.env,
   });
   assert.equal(launch?.env?.GSD_CLI_PATH, devCliPath);
+  assert.equal(launch?.env?.GSD_BIN_PATH, devCliPath);
   assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, worktreeRoot);
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
@@ -149,6 +205,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the
   assert.equal(launch?.command, process.execPath);
   assert.equal(launch?.cwd, "/tmp/project");
   assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd-loader.js");
+  assert.equal(launch?.env?.GSD_BIN_PATH, "/tmp/gsd-loader.js");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
@@ -166,6 +223,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the
   assert.equal(launch?.command, process.execPath);
   assert.equal(launch?.cwd, "/tmp/project");
   assert.equal(launch?.env?.GSD_CLI_PATH, undefined);
+  assert.equal(launch?.env?.GSD_BIN_PATH, undefined);
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
@@ -464,11 +522,20 @@ test("usesWorkflowMcpTransport matches local externalCli providers", () => {
   assert.equal(usesWorkflowMcpTransport("oauth", "local://custom"), false);
 });
 
-test("supportsStructuredQuestions stays enabled on workflow MCP transports when ask_user_questions is available", () => {
+test("supportsStructuredQuestions disables local workflow MCP questions unless explicitly enabled", () => {
   assert.equal(
     supportsStructuredQuestions(["ask_user_questions"], {
       authMode: "externalCli",
       baseUrl: "local://claude-code",
+      env: {},
+    }),
+    false,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["mcp__gsd-workflow__ask_user_questions"], {
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "1" } as NodeJS.ProcessEnv,
     }),
     true,
   );
@@ -716,3 +783,15 @@ test("workflow transport error guidance includes /gsd mcp init hint", () => {
   const src = readSrc("workflow-mcp.ts");
   assert.match(src, /Please run \/gsd mcp init \./);
 });
+
+test("buildWorkflowMcpServers is only imported by tests or Claude Code MCP boundary code", () => {
+  const offenders: string[] = [];
+  for (const file of listTsFiles(gsdDir)) {
+    const rel = file.slice(gsdDir.length + 1).replace(/\\/g, "/");
+    if (rel === "workflow-mcp.ts" || rel.startsWith("tests/")) continue;
+    const src = readFileSync(file, "utf-8");
+    if (/\bimport\b[\s\S]*\bbuildWorkflowMcpServers\b/.test(src)) offenders.push(rel);
+  }
+
+  assert.deepEqual(offenders, []);
+});