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

package/dist/help-text.js

@@ -32,7 +32,7 @@ const SUBCOMMAND_HELP = {
     install: [
         'Usage: gsd install <source> [-l, --local]',
         '',
-        'Install a package/extension source and run declared lifecycle hooks.',
+        'Install a package/extension source and run post-install validation (dependency checks, setup).',
         '',
         'Examples:',
         '  gsd install npm:@foo/bar',

package/dist/loader.js

@@ -26,6 +26,40 @@ if (firstArg === '--help' || firstArg === '-h') {
     printHelp(gsdVersion);
     process.exit(0);
 }
+// ---------------------------------------------------------------------------
+// Runtime dependency checks — fail fast with clear diagnostics before any
+// heavy imports. Reads minimum Node version from the engines field in
+// package.json (already parsed above) and verifies git is available.
+// ---------------------------------------------------------------------------
+{
+    const MIN_NODE_MAJOR = 22;
+    const red = '\x1b[31m';
+    const bold = '\x1b[1m';
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    // -- Node version --
+    const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+    if (nodeMajor < MIN_NODE_MAJOR) {
+        process.stderr.write(`\n${red}${bold}Error:${reset} GSD requires Node.js >= ${MIN_NODE_MAJOR}.0.0\n` +
+            `       You are running Node.js ${process.versions.node}\n\n` +
+            `${dim}Install a supported version:${reset}\n` +
+            `  nvm install ${MIN_NODE_MAJOR}   ${dim}# if using nvm${reset}\n` +
+            `  fnm install ${MIN_NODE_MAJOR}   ${dim}# if using fnm${reset}\n` +
+            `  brew install node@${MIN_NODE_MAJOR} ${dim}# macOS Homebrew${reset}\n\n`);
+        process.exit(1);
+    }
+    // -- git --
+    try {
+        const { execFileSync } = await import('child_process');
+        execFileSync('git', ['--version'], { stdio: 'ignore' });
+    }
+    catch {
+        process.stderr.write(`\n${red}${bold}Error:${reset} GSD requires git but it was not found on PATH.\n\n` +
+            `${dim}Install git:${reset}\n` +
+            `  https://git-scm.com/downloads\n\n`);
+        process.exit(1);
+    }
+}
 import { agentDir, appRoot } from './app-paths.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';

package/dist/resources/extensions/gsd/auto/phases.js

@@ -17,6 +17,7 @@ import { PROJECT_FILES } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { join } from "node:path";
 import { existsSync, cpSync } from "node:fs";
+import { logWarning } from "../workflow-logger.js";
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 /**
  * Generate and write an HTML milestone report snapshot.
@@ -102,8 +103,8 @@ export async function runPreDispatch(ic, loopState) {
             return { action: "break", reason: "health-gate-failed" };
         }
     }
-    catch {
-        // Non-fatal
+    catch (e) {
+        logWarning("engine", "Pre-dispatch health gate threw unexpectedly", { error: String(e) });
     }
     // Sync project root artifacts into worktree
     if (s.originalBasePath &&
@@ -157,7 +158,8 @@ export async function runPreDispatch(ic, loopState) {
                 await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
                 return { action: "break", reason: "merge-conflict" };
             }
-            // Non-conflict errors — log and continue
+            // Non-conflict merge errors — log and continue
+            logWarning("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId, error: String(mergeErr) });
         }
         // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         deps.invalidateAllCaches();
@@ -190,7 +192,9 @@ export async function runPreDispatch(ic, loopState) {
             }
             atomicWriteSync(completedKeysPath, JSON.stringify([], null, 2));
         }
-        catch { /* non-fatal */ }
+        catch (e) {
+            logWarning("engine", "Failed to archive completed-units on milestone transition", { error: String(e) });
+        }
         // Rebuild STATE.md immediately so it reflects the new active milestone.
         // This bypasses the 30-second throttle in the normal rebuild path —
         // milestone transitions are rare and important enough to warrant an
@@ -198,8 +202,8 @@ export async function runPreDispatch(ic, loopState) {
         try {
             await deps.rebuildState(s.basePath);
         }
-        catch {
-            // Non-fatal — STATE.md will be rebuilt on the next regular cycle
+        catch (e) {
+            logWarning("engine", "STATE.md rebuild failed after milestone transition", { error: String(e) });
         }
     }
     if (mid) {
@@ -644,8 +648,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                     (requirementsContent?.length ?? 0) +
                     (projectContent?.length ?? 0);
         }
-        catch {
-            // Non-fatal
+        catch (e) {
+            logWarning("engine", "Baseline char count measurement failed", { error: String(e) });
         }
     }
     // Cache-optimize prompt section ordering
@@ -654,7 +658,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     catch (reorderErr) {
         const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
-        process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
+        logWarning("engine", "Prompt reorder failed", { error: msg });
     }
     // Select and apply model (with tier escalation on retry — normal units only)
     const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, sidecarItem ? undefined : { isRetry, previousTier });
@@ -789,7 +793,9 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
             const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
             atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
         }
-        catch { /* non-fatal: disk flush failure */ }
+        catch (e) {
+            logWarning("engine", "Failed to flush completed-units to disk", { error: String(e) });
+        }
         deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
         s.unitDispatchCount.delete(`${unitType}/${unitId}`);
         s.unitRecoveryCount.delete(`${unitType}/${unitId}`);

package/dist/resources/extensions/gsd/auto/run-unit.js

@@ -6,6 +6,7 @@
 import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
 import { _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
 import { debugLog } from "../debug-logger.js";
+import { logWarning } from "../workflow-logger.js";
 /**
  * Execute a single unit: create a new session, send the prompt, and await
  * the agent_end promise. Returns a UnitResult describing what happened.
@@ -66,7 +67,9 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             process.chdir(s.basePath);
         }
     }
-    catch { /* non-fatal — chdir may fail if dir was removed */ }
+    catch (e) {
+        logWarning("engine", "Failed to chdir to basePath before dispatch", { basePath: s.basePath, error: String(e) });
+    }
     // ── Send the prompt ──
     debugLog("runUnit", { phase: "send-message", unitType, unitId });
     pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
@@ -90,8 +93,8 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             cmdCtxAny.clearQueue();
         }
     }
-    catch {
-        // Non-fatal — clearQueue may not be available in all contexts
+    catch (e) {
+        logWarning("engine", "clearQueue failed after unit completion", { error: String(e) });
     }
     return result;
 }

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -17,6 +17,7 @@ import { createWorktree, removeWorktree, resolveGitDir, worktreePath, } from "./
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeCheckoutTheirs, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, } from "./native-git-bridge.js";
 // ─── Module State ──────────────────────────────────────────────────────────
@@ -615,7 +616,7 @@ export function createAutoWorktree(basePath, milestoneId) {
     const hookError = runWorktreePostCreateHook(basePath, info.path);
     if (hookError) {
         // Non-fatal — log but don't prevent worktree usage
-        console.error(`[GSD] ${hookError}`);
+        logWarning("reconcile", hookError, { worktree: info.name });
     }
     const previousCwd = process.cwd();
     try {
@@ -690,9 +691,9 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     // backslashes (#1436), leaving ~1 GB+ orphaned directories.
     const wtDir = worktreePath(originalBasePath, milestoneId);
     if (existsSync(wtDir)) {
-        console.error(`[GSD] WARNING: Worktree directory still exists after teardown: ${wtDir}\n` +
-            `  This is likely an orphaned directory consuming disk space.\n` +
-            `  Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`);
+        logWarning("reconcile", `Worktree directory still exists after teardown: ${wtDir}. ` +
+            `This is likely an orphaned directory consuming disk space. ` +
+            `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId });
         // Attempt a direct filesystem removal as a fallback
         try {
             rmSync(wtDir, { recursive: true, force: true });

package/dist/resources/extensions/gsd/auto.js

@@ -82,11 +82,10 @@ const s = new AutoSession();
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 export function shouldUseWorktreeIsolation() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    if (prefs?.isolation === "none")
-        return false;
-    if (prefs?.isolation === "branch")
-        return false;
-    return true; // default: worktree
+    if (prefs?.isolation === "worktree")
+        return true;
+    // Default is false — worktree isolation requires explicit opt-in
+    return false;
 }
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
 /** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -4,6 +4,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.
  * The alias description and promptGuidelines direct the LLM to prefer the canonical name.
@@ -45,7 +46,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error saving decision: ${msg}` }],
                 details: { operation: "save_decision", error: msg },
@@ -142,7 +143,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error updating requirement: ${msg}` }],
                 details: { operation: "update_requirement", id: params.id, error: msg },
@@ -235,7 +236,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error saving artifact: ${msg}` }],
                 details: { operation: "save_summary", error: msg },
@@ -394,7 +395,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error planning milestone: ${msg}` }],
                 details: { operation: "plan_milestone", error: msg },
@@ -483,7 +484,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error planning slice: ${msg}` }],
                 details: { operation: "plan_slice", error: msg },
@@ -556,7 +557,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error planning task: ${msg}` }],
                 details: { operation: "plan_task", error: msg },
@@ -622,7 +623,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error completing task: ${msg}` }],
                 details: { operation: "complete_task", error: msg },
@@ -696,7 +697,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error completing slice: ${msg}` }],
                 details: { operation: "complete_slice", error: msg },
@@ -788,7 +789,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error completing milestone: ${msg}` }],
                 details: { operation: "complete_milestone", error: msg },
@@ -804,6 +805,7 @@ export function registerDbTools(pi) {
         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({
@@ -819,6 +821,7 @@ export function registerDbTools(pi) {
             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,
     };
@@ -854,7 +857,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error validating milestone: ${msg}` }],
                 details: { operation: "validate_milestone", error: msg },
@@ -919,7 +922,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error replanning slice: ${msg}` }],
                 details: { operation: "replan_slice", error: msg },
@@ -992,7 +995,7 @@ export function registerDbTools(pi) {
         }
         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", text: `Error reassessing roadmap: ${msg}` }],
                 details: { operation: "reassess_roadmap", error: msg },

package/dist/resources/extensions/gsd/db-writer.js

@@ -12,6 +12,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 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';
@@ -200,7 +201,7 @@ export async function nextDecisionId() {
         return `D${String(next).padStart(3, '0')}`;
     }
     catch (err) {
-        process.stderr.write(`gsd-db: nextDecisionId failed: ${err.message}\n`);
+        logError('manifest', 'nextDecisionId failed', { fn: 'nextDecisionId', error: String(err.message) });
         return 'D001';
     }
 }
@@ -269,7 +270,7 @@ export async function saveDecisionToDb(fields, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            process.stderr.write(`gsd-db: saveDecisionToDb — disk write failed, rolling back DB row: ${diskErr.message}\n`);
+            logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String(diskErr.message) });
             adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
             throw diskErr;
         }
@@ -281,7 +282,7 @@ export async function saveDecisionToDb(fields, basePath) {
         return { id };
     }
     catch (err) {
-        process.stderr.write(`gsd-db: saveDecisionToDb failed: ${err.message}\n`);
+        logError('manifest', 'saveDecisionToDb failed', { fn: 'saveDecisionToDb', error: String(err.message) });
         throw err;
     }
 }
@@ -333,7 +334,7 @@ export async function updateRequirementInDb(id, updates, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            process.stderr.write(`gsd-db: updateRequirementInDb — disk write failed, reverting DB row: ${diskErr.message}\n`);
+            logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String(diskErr.message) });
             db.upsertRequirement(existing);
             throw diskErr;
         }
@@ -344,7 +345,7 @@ export async function updateRequirementInDb(id, updates, basePath) {
         clearParseCache();
     }
     catch (err) {
-        process.stderr.write(`gsd-db: updateRequirementInDb failed: ${err.message}\n`);
+        logError('manifest', 'updateRequirementInDb failed', { fn: 'updateRequirementInDb', error: String(err.message) });
         throw err;
     }
 }
@@ -371,8 +372,7 @@ export async function saveArtifactToDb(opts, basePath) {
             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;
             }
@@ -391,7 +391,7 @@ export async function saveArtifactToDb(opts, basePath) {
                 await saveFile(fullPath, opts.content);
             }
             catch (diskErr) {
-                process.stderr.write(`gsd-db: saveArtifactToDb — disk write failed, rolling back DB row: ${diskErr.message}\n`);
+                logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String(diskErr.message) });
                 const rollbackAdapter = db._getAdapter();
                 rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
                 throw diskErr;
@@ -404,7 +404,7 @@ export async function saveArtifactToDb(opts, basePath) {
         clearParseCache();
     }
     catch (err) {
-        process.stderr.write(`gsd-db: saveArtifactToDb failed: ${err.message}\n`);
+        logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String(err.message) });
         throw err;
     }
 }

package/dist/resources/extensions/gsd/doctor-checks.js

@@ -17,7 +17,7 @@ import { getAllWorktreeHealth } from "./worktree-health.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "worktree") {
+export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {
         return; // Not a git repo — skip all git health checks

package/dist/resources/extensions/gsd/doctor.js

@@ -332,8 +332,8 @@ export async function runGSDDoctor(basePath, options) {
     // Git health checks — timed
     const t0git = Date.now();
     const isolationMode = 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;
     // Runtime health checks — timed

package/dist/resources/extensions/gsd/gsd-db.js

@@ -56,7 +56,11 @@ function loadProvider() {
     catch {
         // unavailable
     }
-    process.stderr.write("gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3)\n");
+    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).${versionHint}\n`);
 }
 function normalizeRow(row) {
     if (row == null)

package/dist/resources/extensions/gsd/preferences-types.js

@@ -13,7 +13,7 @@ export const MODE_DEFAULTS = {
             push_branches: false,
             pre_merge_check: false,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: false,
     },
@@ -23,7 +23,7 @@ export const MODE_DEFAULTS = {
             push_branches: true,
             pre_merge_check: true,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: true,
     },

package/dist/resources/extensions/gsd/preferences.js

@@ -393,15 +393,19 @@ export function resolvePreDispatchHooks() {
 // ─── Isolation & Parallel ─────────────────────────────────────────────────────
 /**
  * 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() {
     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) {
     return {

package/dist/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/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -72,6 +72,10 @@ export async function handleCompleteMilestone(params, basePath) {
     if (!params.title || typeof params.title !== "string" || params.title.trim() === "") {
         return { error: "title is required and must be a non-empty string" };
     }
+    // ── Verify that verification passed ─────────────────────────────────────
+    if (params.verificationPassed !== true) {
+        return { error: "verification did not pass — milestone completion blocked. verificationPassed must be explicitly set to true after all verification steps succeed" };
+    }
     // ── Verify all slices are complete ───────────────────────────────────────
     const slices = getMilestoneSlices(params.milestoneId);
     if (slices.length === 0) {