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

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,
@@ -904,7 +905,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 +974,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 +1054,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/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);
 });