gsd-pi 2.45.0-dev.6b9da3e → 2.45.0-dev.fdcf73c

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -6,6 +6,7 @@ import { findMilestoneIds, nextMilestoneId, claimReservedId, getReservedMileston
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { StringEnum } from "@gsd/pi-ai";
+import { logError } from "../workflow-logger.js";
 
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
@@ -52,7 +53,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: gsd_decision_save tool failed: ${msg}\n`);
+      logError("tool", `gsd_decision_save tool failed: ${msg}`, { tool: "gsd_decision_save", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
         details: { operation: "save_decision", error: msg } as any,
@@ -143,7 +144,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: gsd_requirement_update tool failed: ${msg}\n`);
+      logError("tool", `gsd_requirement_update tool failed: ${msg}`, { tool: "gsd_requirement_update", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
         details: { operation: "update_requirement", id: params.id, error: msg } as any,
@@ -239,7 +240,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: gsd_summary_save tool failed: ${msg}\n`);
+      logError("tool", `gsd_summary_save tool failed: ${msg}`, { tool: "gsd_summary_save", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
         details: { operation: "save_summary", error: msg } as any,
@@ -402,7 +403,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: plan_milestone tool failed: ${msg}\n`);
+      logError("tool", `plan_milestone tool failed: ${msg}`, { tool: "gsd_plan_milestone", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error planning milestone: ${msg}` }],
         details: { operation: "plan_milestone", error: msg } as any,
@@ -495,7 +496,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: plan_slice tool failed: ${msg}\n`);
+      logError("tool", `plan_slice tool failed: ${msg}`, { tool: "gsd_plan_slice", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error planning slice: ${msg}` }],
         details: { operation: "plan_slice", error: msg } as any,
@@ -572,7 +573,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: plan_task tool failed: ${msg}\n`);
+      logError("tool", `plan_task tool failed: ${msg}`, { tool: "gsd_plan_task", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error planning task: ${msg}` }],
         details: { operation: "plan_task", error: msg } as any,
@@ -642,7 +643,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: complete_task tool failed: ${msg}\n`);
+      logError("tool", `complete_task tool failed: ${msg}`, { tool: "gsd_task_complete", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error completing task: ${msg}` }],
         details: { operation: "complete_task", error: msg } as any,
@@ -723,7 +724,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: complete_slice tool failed: ${msg}\n`);
+      logError("tool", `complete_slice tool failed: ${msg}`, { tool: "gsd_slice_complete", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error completing slice: ${msg}` }],
         details: { operation: "complete_slice", error: msg } as any,
@@ -834,7 +835,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: complete_milestone tool failed: ${msg}\n`);
+      logError("tool", `complete_milestone tool failed: ${msg}`, { tool: "gsd_complete_milestone", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error completing milestone: ${msg}` }],
         details: { operation: "complete_milestone", error: msg } as any,
@@ -852,6 +853,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_complete_milestone when all slices in a milestone are finished and the milestone needs to be recorded.",
       "All slices in the milestone must have status 'complete' — the handler validates this before proceeding.",
+      "verificationPassed must be explicitly set to true — the handler rejects completion if verification did not pass.",
       "On success, returns summaryPath where the MILESTONE-SUMMARY.md was written.",
     ],
     parameters: Type.Object({
@@ -867,6 +869,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       lessonsLearned: Type.Array(Type.String(), { description: "Lessons learned during the milestone" }),
       followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
       deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
+      verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }),
     }),
     execute: milestoneCompleteExecute,
   };
@@ -904,7 +907,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: validate_milestone tool failed: ${msg}\n`);
+      logError("tool", `validate_milestone tool failed: ${msg}`, { tool: "gsd_validate_milestone", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error validating milestone: ${msg}` }],
         details: { operation: "validate_milestone", error: msg } as any,
@@ -973,7 +976,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: replan_slice tool failed: ${msg}\n`);
+      logError("tool", `replan_slice tool failed: ${msg}`, { tool: "gsd_replan_slice", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error replanning slice: ${msg}` }],
         details: { operation: "replan_slice", error: msg } as any,
@@ -1053,7 +1056,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`gsd-db: reassess_roadmap tool failed: ${msg}\n`);
+      logError("tool", `reassess_roadmap tool failed: ${msg}`, { tool: "gsd_reassess_roadmap", error: String(err) });
       return {
         content: [{ type: "text" as const, text: `Error reassessing roadmap: ${msg}` }],
         details: { operation: "reassess_roadmap", error: msg } as any,

package/src/resources/extensions/gsd/db-writer.ts

@@ -14,6 +14,7 @@ import type { Decision, Requirement } from './types.js';
 import { resolveGsdRootFile } from './paths.js';
 import { saveFile } from './files.js';
 import { GSDError, GSD_STALE_STATE, GSD_IO_ERROR } from './errors.js';
+import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
@@ -221,7 +222,7 @@ export async function nextDecisionId(): Promise<string> {
     const next = maxNum + 1;
     return `D${String(next).padStart(3, '0')}`;
   } catch (err) {
-    process.stderr.write(`gsd-db: nextDecisionId failed: ${(err as Error).message}\n`);
+    logError('manifest', 'nextDecisionId failed', { fn: 'nextDecisionId', error: String((err as Error).message) });
     return 'D001';
   }
 }
@@ -311,9 +312,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      process.stderr.write(
-        `gsd-db: saveDecisionToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
-      );
+      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) });
       adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
       throw diskErr;
     }
@@ -325,7 +324,7 @@ export async function saveDecisionToDb(
 
     return { id };
   } catch (err) {
-    process.stderr.write(`gsd-db: saveDecisionToDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String((err as Error).message) });
     throw err;
   }
 }
@@ -388,9 +387,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      process.stderr.write(
-        `gsd-db: updateRequirementInDb — disk write failed, reverting DB row: ${(diskErr as Error).message}\n`,
-      );
+      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) });
       db.upsertRequirement(existing);
       throw diskErr;
     }
@@ -400,7 +397,7 @@ export async function updateRequirementInDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    process.stderr.write(`gsd-db: updateRequirementInDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'updateRequirementInDb failed', { fn: 'updateRequirementInDb', error: String((err as Error).message) });
     throw err;
   }
 }
@@ -444,10 +441,7 @@ export async function saveArtifactToDb(
       const existingSize = statSync(fullPath).size;
       const newSize = Buffer.byteLength(opts.content, 'utf-8');
       if (existingSize > 0 && newSize < existingSize * 0.5) {
-        process.stderr.write(
-          `gsd-db: saveArtifactToDb — new content (${newSize}B) is <50% of existing file ` +
-          `(${existingSize}B) at ${opts.path}. Preserving disk file to prevent data loss.\n`,
-        );
+        logWarning('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
         dbContent = readFileSync(fullPath, 'utf-8');
         skipDiskWrite = true;
       }
@@ -467,9 +461,7 @@ export async function saveArtifactToDb(
       try {
         await saveFile(fullPath, opts.content);
       } catch (diskErr) {
-        process.stderr.write(
-          `gsd-db: saveArtifactToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
-        );
+        logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String((diskErr as Error).message) });
         const rollbackAdapter = db._getAdapter();
         rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
         throw diskErr;
@@ -481,7 +473,7 @@ export async function saveArtifactToDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    process.stderr.write(`gsd-db: saveArtifactToDb failed: ${(err as Error).message}\n`);
+    logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String((err as Error).message) });
     throw err;
   }
 }

package/src/resources/extensions/gsd/doctor-checks.ts

@@ -25,7 +25,7 @@ export async function checkGitHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
   shouldFix: (code: DoctorIssueCode) => boolean,
-  isolationMode: "none" | "worktree" | "branch" = "worktree",
+  isolationMode: "none" | "worktree" | "branch" = "none",
 ): Promise<void> {
   // Degrade gracefully if not a git repo
   if (!nativeIsRepo(basePath)) {

package/src/resources/extensions/gsd/doctor.ts

@@ -360,8 +360,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // Git health checks — timed
   const t0git = Date.now();
   const isolationMode: "none" | "worktree" | "branch" = options?.isolationMode ??
-    (prefs?.preferences?.git?.isolation === "none" ? "none" :
-    prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree");
+    (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
+    prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
   const gitMs = Date.now() - t0git;
 

package/src/resources/extensions/gsd/gsd-db.ts

@@ -78,8 +78,12 @@ function loadProvider(): void {
     // unavailable
   }
 
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  const versionHint = nodeMajor < 22
+    ? ` GSD requires Node >= 22.0.0 (current: v${process.versions.node}). Upgrade Node to fix this.`
+    : "";
   process.stderr.write(
-    "gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3)\n",
+    `gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3).${versionHint}\n`,
   );
 }
 

package/src/resources/extensions/gsd/journal.ts

@@ -32,7 +32,12 @@ export type JournalEventType =
   | "milestone-transition"
   | "stuck-detected"
   | "sidecar-dequeue"
-  | "iteration-end";
+  | "iteration-end"
+  | "worktree-enter"
+  | "worktree-create-failed"
+  | "worktree-skip"
+  | "worktree-merge-start"
+  | "worktree-merge-failed";
 
 /** A single structured event in the journal. */
 export interface JournalEntry {

package/src/resources/extensions/gsd/preferences-types.ts

@@ -34,7 +34,7 @@ export const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
       push_branches: false,
       pre_merge_check: false,
       merge_strategy: "squash",
-      isolation: "worktree",
+      isolation: "none",
     },
     unique_milestone_ids: false,
   },
@@ -44,7 +44,7 @@ export const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
       push_branches: true,
       pre_merge_check: true,
       merge_strategy: "squash",
-      isolation: "worktree",
+      isolation: "none",
     },
     unique_milestone_ids: true,
   },

package/src/resources/extensions/gsd/preferences.ts

@@ -497,13 +497,17 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
 
 /**
  * Resolve the effective git isolation mode from preferences.
- * Returns "worktree" (default), "branch", or "none".
+ * Returns "none" (default), "worktree", or "branch".
+ *
+ * Default is "none" so GSD works out of the box without preferences.md.
+ * Worktree isolation requires explicit opt-in because it depends on git
+ * branch infrastructure that must be set up before use.
  */
 export function getIsolationMode(): "none" | "worktree" | "branch" {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-  if (prefs?.isolation === "none") return "none";
+  if (prefs?.isolation === "worktree") return "worktree";
   if (prefs?.isolation === "branch") return "branch";
-  return "worktree"; // default
+  return "none"; // default — no isolation, work on current branch
 }
 
 export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -17,18 +17,31 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. In that case, do NOT mark the milestone as passing verification — document the gap clearly in the summary and state that implementation is missing.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. Record this as a **verification failure**.
+4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
+5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
 6. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+
+### Verification Gate — STOP if verification failed
+
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 7.**
+
+**Failure path** (verification failed):
+- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT update `.gsd/PROJECT.md` to reflect completion.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
+- Write a clear summary of what failed and why to help the next attempt.
+- Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
+
+**Success path** (all verifications passed — continue with steps 7–11):
+
+7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`, `verificationPassed: true`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
 8. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 6.
 9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
 10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 11. Do not commit manually — the system auto-commits your changes after this unit completes.
+- Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met or no code changes exist, document it clearly in the summary and do not mark the milestone as passing verification.
+**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run.
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
-
-When done, say: "Milestone {{milestoneId}} complete."

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

@@ -115,6 +115,102 @@ describe("complete-milestone", () => {
     assert.ok(prompt.includes("Milestone M002 complete"), "prompt contains completion sentinel for M002");
   });
 
+  test("prompt contains verification gate that blocks completion on failure", () => {
+    const prompt = loadPromptFromWorktree("complete-milestone", {
+      workingDirectory: "/tmp/test-project",
+      milestoneId: "M001",
+      milestoneTitle: "Gate Test",
+      roadmapPath: ".gsd/milestones/M001/M001-ROADMAP.md",
+      inlinedContext: "context",
+    });
+
+    // Verification gate section must exist
+    assert.ok(
+      prompt.includes("Verification Gate"),
+      "prompt contains 'Verification Gate' section",
+    );
+
+    // Failure path must block gsd_complete_milestone
+    assert.ok(
+      prompt.includes("Do NOT call `gsd_complete_milestone`"),
+      "failure path explicitly blocks calling the completion tool",
+    );
+
+    // Failure path must have its own sentinel distinct from success
+    assert.ok(
+      prompt.includes("verification FAILED"),
+      "failure path outputs a FAILED sentinel",
+    );
+
+    // verificationPassed parameter must be referenced
+    assert.ok(
+      prompt.includes("verificationPassed"),
+      "prompt references verificationPassed parameter",
+    );
+  });
+
+  test("handleCompleteMilestone rejects when verificationPassed is false", async () => {
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    try {
+      const result = await handleCompleteMilestone({
+        milestoneId: "M001",
+        title: "Test Milestone",
+        oneLiner: "Test",
+        narrative: "Test narrative",
+        successCriteriaResults: "None met",
+        definitionOfDoneResults: "Incomplete",
+        requirementOutcomes: "None validated",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        verificationPassed: false,
+      }, base);
+
+      assert.ok("error" in result, "returns error when verificationPassed is false");
+      assert.ok(
+        (result as { error: string }).error.includes("verification did not pass"),
+        "error message mentions verification did not pass",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  test("handleCompleteMilestone rejects when verificationPassed is omitted", async () => {
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    try {
+      // Simulate omitted verificationPassed (undefined coerced via any)
+      const params: any = {
+        milestoneId: "M001",
+        title: "Test Milestone",
+        oneLiner: "Test",
+        narrative: "Test narrative",
+        successCriteriaResults: "Results",
+        definitionOfDoneResults: "Done results",
+        requirementOutcomes: "Outcomes",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        // verificationPassed intentionally omitted
+      };
+      const result = await handleCompleteMilestone(params, base);
+
+      assert.ok("error" in result, "returns error when verificationPassed is omitted");
+      assert.ok(
+        (result as { error: string }).error.includes("verification did not pass"),
+        "error message mentions verification did not pass",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
   test("diagnoseExpectedArtifact logic for complete-milestone", async () => {
     // Import the path helpers used by diagnoseExpectedArtifact
     const { relMilestoneFile } = await import("../paths.ts");

package/src/resources/extensions/gsd/tests/merge-conflict-stops-loop.test.ts

@@ -27,7 +27,7 @@ console.log("\n=== #2330: Merge conflict stops auto loop ===");
 const methodStart = resolverSrc.indexOf("Worktree-mode merge:");
 assertTrue(methodStart > 0, "worktree-resolver has _mergeWorktreeMode method");
 
-const methodBody = resolverSrc.slice(methodStart, methodStart + 5000);
+const methodBody = resolverSrc.slice(methodStart, methodStart + 6000);
 const rethrowsConflict =
   methodBody.includes("MergeConflictError") &&
   methodBody.includes("throw err");

package/src/resources/extensions/gsd/tests/none-mode-gates.test.ts

@@ -70,18 +70,20 @@ try {
 }
 });
 
-// Test 4: shouldUseWorktreeIsolation returns true for no prefs (default)
+// Test 4: shouldUseWorktreeIsolation returns false for no prefs (default: none)
+// Worktree isolation requires explicit opt-in — default is "none" so GSD
+// works out of the box without preferences.md (#2480).
 // Skip if global prefs exist — they override the default and this test
 // cannot control ~/.gsd/preferences.md.
 
-test('shouldUseWorktreeIsolation returns true for no prefs (default)', () => {
+test('shouldUseWorktreeIsolation returns false for no prefs (default: none)', () => {
   const globalPrefsExist = existsSync(join(homedir(), ".gsd", "preferences.md"))
     || existsSync(join(homedir(), ".gsd", "PREFERENCES.md"));
   if (!globalPrefsExist) {
     try {
       removeRunnerPreferences(); // ensure no prefs file
       invalidateAllCaches();
-      assert.deepStrictEqual(shouldUseWorktreeIsolation(), true, "shouldUseWorktreeIsolation() with no prefs (default worktree)");
+      assert.deepStrictEqual(shouldUseWorktreeIsolation(), false, "shouldUseWorktreeIsolation() with no prefs (default none)");
     } finally {
       invalidateAllCaches();
     }
@@ -89,6 +91,21 @@ test('shouldUseWorktreeIsolation returns true for no prefs (default)', () => {
   }
 });
 
+// Test 5: getIsolationMode returns "none" when no preferences.md exists (#2480)
+test('getIsolationMode returns "none" with no prefs (default)', () => {
+  const globalPrefsExist = existsSync(join(homedir(), ".gsd", "preferences.md"))
+    || existsSync(join(homedir(), ".gsd", "PREFERENCES.md"));
+  if (!globalPrefsExist) {
+    try {
+      removeRunnerPreferences();
+      invalidateAllCaches();
+      assert.deepStrictEqual(getIsolationMode(), "none", "getIsolationMode() with no prefs defaults to none");
+    } finally {
+      invalidateAllCaches();
+    }
+  }
+});
+
 test('getIsolationMode returns "none" with none prefs', () => {
 try {
   writeRunnerPreferences("none");
@@ -100,6 +117,28 @@ try {
 }
 });
 
+test('getIsolationMode returns "worktree" with worktree prefs', () => {
+try {
+  writeRunnerPreferences("worktree");
+  invalidateAllCaches();
+  assert.deepStrictEqual(getIsolationMode(), "worktree", "getIsolationMode() with worktree prefs");
+} finally {
+  removeRunnerPreferences();
+  invalidateAllCaches();
+}
+});
+
+test('getIsolationMode returns "branch" with branch prefs', () => {
+try {
+  writeRunnerPreferences("branch");
+  invalidateAllCaches();
+  assert.deepStrictEqual(getIsolationMode(), "branch", "getIsolationMode() with branch prefs");
+} finally {
+  removeRunnerPreferences();
+  invalidateAllCaches();
+}
+});
+
 test('getActiveAutoWorktreeContext returns null at baseline', () => {
 assert.deepStrictEqual(getActiveAutoWorktreeContext(), null, "getActiveAutoWorktreeContext() returns null without enterAutoWorktree()");
 });

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -41,18 +41,16 @@ test("git.merge_to_main produces deprecation warning", () => {
 });
 
 
-test("getIsolationMode defaults to worktree when preferences have no isolation setting", () => {
+test("getIsolationMode defaults to none when preferences have no isolation setting", () => {
   // Validate the default via validatePreferences: when no isolation is set,
-  // preferences.git.isolation is undefined, and getIsolationMode returns "worktree".
-  // We test the function's logic by verifying its documented default.
+  // preferences.git.isolation is undefined, and getIsolationMode returns "none".
+  // Default changed from "worktree" to "none" so GSD works out of the box
+  // without preferences.md (#2480).
   const { preferences } = validatePreferences({});
   assert.equal(preferences.git?.isolation, undefined, "no isolation in empty prefs");
-  // The function returns "worktree" when prefs?.git?.isolation is not "none" or "branch"
-  // This is a compile-time-verifiable truth from the function body — test it directly
-  // by constructing the same conditions getIsolationMode checks.
   const isolation = preferences.git?.isolation;
-  const expected = isolation === "none" ? "none" : isolation === "branch" ? "branch" : "worktree";
-  assert.equal(expected, "worktree", "default isolation mode is worktree");
+  const expected = isolation === "worktree" ? "worktree" : isolation === "branch" ? "branch" : "none";
+  assert.equal(expected, "none", "default isolation mode is none");
 });
 
 // ── Mode defaults ────────────────────────────────────────────────────────────
@@ -63,7 +61,7 @@ test("solo mode applies correct defaults", () => {
   assert.equal(result.git?.push_branches, false);
   assert.equal(result.git?.pre_merge_check, false);
   assert.equal(result.git?.merge_strategy, "squash");
-  assert.equal(result.git?.isolation, "worktree");
+  assert.equal(result.git?.isolation, "none");
   assert.equal(result.unique_milestone_ids, false);
 });