gsd-pi 2.8.1 → 2.8.3

package/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts

@@ -824,10 +824,12 @@ export class InteractiveMode {
 
 		// Try parent directories (package manager stores directory paths)
 		let current = p;
-		while (current.includes("/")) {
-			current = current.substring(0, current.lastIndexOf("/"));
-			const parent = metadata.get(current);
-			if (parent) return parent;
+		let parent = path.dirname(current);
+		while (parent !== current) {
+			const meta = metadata.get(parent);
+			if (meta) return meta;
+			current = parent;
+			parent = path.dirname(current);
 		}
 
 		return undefined;
@@ -3693,6 +3695,21 @@ export class InteractiveMode {
 							this.session.modelRegistry.authStorage.logout(providerId);
 							this.session.modelRegistry.refresh();
 							await this.updateAvailableProviderCount();
+
+							// Auto-switch model if current model belongs to the logged-out provider
+							const currentModel = this.session.model;
+							if (currentModel?.provider === providerId) {
+								try {
+									const available = this.session.modelRegistry.getAvailable();
+									const fallback = available.find((m) => m.provider !== providerId);
+									if (fallback) {
+										await this.session.setModel(fallback);
+									}
+								} catch {
+									// Model switch failed — user can manually switch via /model
+								}
+							}
+
 							this.showStatus(`Logged out of ${providerName}`);
 						} catch (error: unknown) {
 							this.showError(`Logout failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -3787,6 +3804,26 @@ export class InteractiveMode {
 			restoreEditor();
 			this.session.modelRegistry.refresh();
 			await this.updateAvailableProviderCount();
+
+			// Auto-switch model if current model has no valid API key
+			try {
+				const currentModel = this.session.model;
+				if (currentModel) {
+					const currentKey = await this.session.modelRegistry.getApiKey(currentModel);
+					if (!currentKey) {
+						const available = this.session.modelRegistry.getAvailable();
+						const newProviderModel = available.find((m) => m.provider === providerId);
+						if (newProviderModel) {
+							await this.session.setModel(newProviderModel);
+						} else if (available.length > 0) {
+							await this.session.setModel(available[0]);
+						}
+					}
+				}
+			} catch (error: unknown) {
+				// Model switch failed — user can manually switch via /model
+			}
+
 			this.showStatus(`Logged in to ${providerName}. Credentials saved to ${getAuthPath()}`);
 		} catch (error: unknown) {
 			restoreEditor();

package/packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts

@@ -119,8 +119,8 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 	 */
 	const createExtensionUIContext = (): ExtensionUIContext => ({
 		select: (title, options, opts) =>
-			createDialogPromise(opts, undefined, { method: "select", title, options, timeout: opts?.timeout }, (r) =>
-				"cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined,
+			createDialogPromise(opts, undefined, { method: "select", title, options, timeout: opts?.timeout, allowMultiple: opts?.allowMultiple }, (r) =>
+				"cancelled" in r && r.cancelled ? undefined : "values" in r ? r.values : "value" in r ? r.value : undefined,
 			),
 
 		confirm: (title, message, opts) =>

package/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts

@@ -210,7 +210,7 @@ export type RpcResponse =
 
 /** Emitted when an extension needs user input */
 export type RpcExtensionUIRequest =
-	| { type: "extension_ui_request"; id: string; method: "select"; title: string; options: string[]; timeout?: number }
+	| { type: "extension_ui_request"; id: string; method: "select"; title: string; options: string[]; timeout?: number; allowMultiple?: boolean }
 	| { type: "extension_ui_request"; id: string; method: "confirm"; title: string; message: string; timeout?: number }
 	| {
 			type: "extension_ui_request";
@@ -253,6 +253,7 @@ export type RpcExtensionUIRequest =
 /** Response to an extension UI request */
 export type RpcExtensionUIResponse =
 	| { type: "extension_ui_response"; id: string; value: string }
+	| { type: "extension_ui_response"; id: string; values: string[] }
 	| { type: "extension_ui_response"; id: string; confirmed: boolean }
 	| { type: "extension_ui_response"; id: string; cancelled: true };
 

package/packages/pi-coding-agent/src/utils/shell.ts

@@ -118,6 +118,17 @@ export function getShellConfig(): { shell: string; args: string[] } {
 	return cachedShellConfig;
 }
 
+/**
+ * On Windows + Git Bash, rewrite Windows-style NUL redirects to /dev/null.
+ * Git Bash doesn't recognize NUL as a device name and creates a literal file
+ * that is undeletable due to NUL being a reserved Windows device name.
+ * No-op on non-Windows platforms.
+ */
+export function sanitizeCommand(command: string): string {
+	if (process.platform !== "win32") return command;
+	return command.replace(/(\d*>>?) *\bNUL\b(?=\s|;|\||&|\)|$)/gi, "$1 /dev/null");
+}
+
 export function getShellEnv(): NodeJS.ProcessEnv {
 	const binDir = getBinDir();
 	const pathKey = Object.keys(process.env).find((key) => key.toLowerCase() === "path") ?? "PATH";

package/src/resources/extensions/ask-user-questions.ts

@@ -144,6 +144,46 @@ export default function AskUserQuestions(pi: ExtensionAPI) {
 			// Delegate to shared interview UI
 			const result = await showInterviewRound(params.questions, {}, ctx);
 
+			// RPC mode fallback: custom() returns undefined, so showInterviewRound
+			// may return undefined. Fall back to sequential ctx.ui.select() calls.
+			if (!result) {
+				const answers: Record<string, { answers: string[] }> = {};
+				for (const q of params.questions) {
+					const options = q.options.map((o) => o.label);
+					if (!q.allowMultiple) {
+						options.push(OTHER_OPTION_LABEL);
+					}
+					const selected = await ctx.ui.select(
+						`${q.header}: ${q.question}`,
+						options,
+						{ signal, ...(q.allowMultiple ? { allowMultiple: true } : {}) },
+					);
+					if (selected === undefined) {
+						return errorResult("ask_user_questions was cancelled", params.questions);
+					}
+					answers[q.id] = {
+						answers: Array.isArray(selected) ? selected : [selected],
+					};
+				}
+				const roundResult: RoundResult = {
+					endInterview: false,
+					answers: Object.fromEntries(
+						Object.entries(answers).map(([id, a]) => [
+							id,
+							{ selected: a.answers.length === 1 ? a.answers[0] : a.answers, notes: "" },
+						]),
+					),
+				};
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify({ answers }) }],
+					details: {
+						questions: params.questions,
+						response: roundResult,
+						cancelled: false,
+					} satisfies LocalResultDetails,
+				};
+			}
+
 			// Check if cancelled (empty answers = user exited)
 			const hasAnswers = Object.keys(result.answers).length > 0;
 			if (!hasAnswers) {

package/src/resources/extensions/bg-shell/index.ts

@@ -34,6 +34,7 @@ import {
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
 	getShellConfig,
+	sanitizeCommand,
 } from "@gsd/pi-coding-agent";
 import {
 	Text,
@@ -582,7 +583,7 @@ function startProcess(opts: StartOptions): BgProcess {
 	const env = { ...process.env, ...(opts.env || {}) };
 
 	const { shell, args: shellArgs } = getShellConfig();
-	const proc = spawn(shell, [...shellArgs, opts.command], {
+	const proc = spawn(shell, [...shellArgs, sanitizeCommand(opts.command)], {
 		cwd: opts.cwd,
 		stdio: ["pipe", "pipe", "pipe"],
 		env,

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

@@ -48,14 +48,14 @@ import {
   validateCompleteBoundary,
   formatValidationIssues,
 } from "./observability-validator.js";
-import { ensureGitignore } from "./gitignore.js";
+import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { runGSDDoctor, rebuildState } from "./doctor.js";
 import { snapshotSkills, clearSkillSnapshot } from "./skill-discovery.js";
 import {
   initMetrics, resetMetrics, snapshotUnitMetrics, getLedger,
   getProjectTotals, formatCost, formatTokenCount,
 } from "./metrics.js";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
 import {
@@ -152,6 +152,7 @@ let currentMilestoneId: string | null = null;
 
 /** Model the user had selected before auto-mode started */
 let originalModelId: string | null = null;
+let originalModelProvider: string | null = null;
 
 /** Progress-aware timeout supervision */
 let unitTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
@@ -257,6 +258,11 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
     ctx?.ui.notify("Auto-mode stopped.", "info");
   }
 
+  // Sync disk state so next resume starts from accurate state
+  if (basePath) {
+    try { await rebuildState(basePath); } catch { /* non-fatal */ }
+  }
+
   resetMetrics();
   active = false;
   paused = false;
@@ -272,10 +278,11 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   ctx?.ui.setFooter(undefined);
 
   // Restore the user's original model
-  if (pi && ctx && originalModelId) {
-    const original = ctx.modelRegistry.find("anthropic", originalModelId);
+  if (pi && ctx && originalModelId && originalModelProvider) {
+    const original = ctx.modelRegistry.find(originalModelProvider, originalModelId);
     if (original) await pi.setModel(original);
     originalModelId = null;
+    originalModelProvider = null;
   }
 
   cmdCtx = null;
@@ -381,6 +388,7 @@ export async function startAuto(
 
   // Ensure .gitignore has baseline patterns
   ensureGitignore(base);
+  untrackRuntimeFiles(base);
 
   // Bootstrap .gsd/ if it doesn't exist
   const gsdDir = join(base, ".gsd");
@@ -458,6 +466,7 @@ export async function startAuto(
   currentUnit = null;
   currentMilestoneId = state.activeMilestone?.id ?? null;
   originalModelId = ctx.model?.id ?? null;
+  originalModelProvider = ctx.model?.provider ?? null;
 
   // Initialize metrics — loads existing ledger from disk
   initMetrics(base);
@@ -1180,7 +1189,7 @@ async function dispatchNextUnit(
 
       // Research before roadmap if no research exists
       const researchFile = resolveMilestoneFile(basePath, mid, "RESEARCH");
-      const hasResearch = !!(researchFile && await loadFile(researchFile));
+      const hasResearch = !!researchFile;
 
       if (!hasResearch) {
         unitType = "research-milestone";
@@ -1197,13 +1206,13 @@ async function dispatchNextUnit(
       const sid = state.activeSlice!.id;
       const sTitle = state.activeSlice!.title;
       const researchFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
-      const hasResearch = !!(researchFile && await loadFile(researchFile));
+      const hasResearch = !!researchFile;
 
       if (!hasResearch) {
         // Skip slice research for S01 when milestone research already exists —
         // the milestone research already covers the same ground for the first slice.
         const milestoneResearchFile = resolveMilestoneFile(basePath, mid, "RESEARCH");
-        const hasMilestoneResearch = !!(milestoneResearchFile && await loadFile(milestoneResearchFile));
+        const hasMilestoneResearch = !!milestoneResearchFile;
         if (hasMilestoneResearch && sid === "S01") {
           unitType = "plan-slice";
           unitId = `${mid}/${sid}`;
@@ -1311,6 +1320,26 @@ async function dispatchNextUnit(
   }
   unitDispatchCount.set(dispatchKey, prevCount + 1);
   if (prevCount > 0) {
+    // Self-repair: if summary exists but checkbox not marked, fix it and re-derive
+    if (unitType === "execute-task") {
+      const status = await inspectExecuteTaskDurability(basePath, unitId);
+      if (status?.summaryExists && !status.taskChecked) {
+        const [mid, sid, tid] = unitId.split("/");
+        if (mid && sid && tid) {
+          const repaired = skipExecuteTask(basePath, mid, sid, tid, status, "self-repair", 0);
+          if (repaired) {
+            ctx.ui.notify(
+              `Self-repaired ${unitId}: summary existed but checkbox was unmarked. Marked [x] and advancing.`,
+              "warning",
+            );
+            unitDispatchCount.delete(dispatchKey);
+            await new Promise(r => setImmediate(r));
+            await dispatchNextUnit(ctx, pi);
+            return;
+          }
+        }
+      }
+    }
     ctx.ui.notify(
       `${unitType} ${unitId} didn't produce expected artifact. Retrying (${prevCount + 1}/${MAX_UNIT_DISPATCHES}).`,
       "warning",
@@ -1413,14 +1442,46 @@ async function dispatchNextUnit(
   // Try primary model, then fallbacks in order if setting fails
   const modelConfig = resolveModelWithFallbacksForUnit(unitType);
   if (modelConfig) {
-    const allModels = ctx.modelRegistry.getAll();
+    const availableModels = ctx.modelRegistry.getAvailable();
     const modelsToTry = [modelConfig.primary, ...modelConfig.fallbacks];
     let modelSet = false;
 
     for (const modelId of modelsToTry) {
-      const model = allModels.find(m => m.id === modelId);
+      // Support "provider/model" format for explicit provider targeting
+      const slashIdx = modelId.indexOf("/");
+      let model;
+      if (slashIdx !== -1) {
+        const provider = modelId.substring(0, slashIdx);
+        const id = modelId.substring(slashIdx + 1);
+        model = availableModels.find(
+          m => m.provider.toLowerCase() === provider.toLowerCase()
+            && m.id.toLowerCase() === id.toLowerCase(),
+        );
+      } else {
+        // For bare IDs, prefer the current session's provider, then first available match
+        const currentProvider = ctx.model?.provider;
+        const exactProviderMatch = availableModels.find(
+          m => m.id === modelId && m.provider === currentProvider,
+        );
+        const anyMatch = availableModels.find(m => m.id === modelId);
+        model = exactProviderMatch ?? anyMatch;
+
+        // Warn if the ID is ambiguous across providers
+        if (anyMatch && !exactProviderMatch) {
+          const providers = availableModels
+            .filter(m => m.id === modelId)
+            .map(m => m.provider);
+          if (providers.length > 1) {
+            ctx.ui.notify(
+              `Model ID "${modelId}" exists in multiple providers (${providers.join(", ")}). ` +
+              `Resolved to ${anyMatch.provider}. Use "provider/model" format for explicit targeting.`,
+              "warning",
+            );
+          }
+        }
+      }
       if (!model) {
-        ctx.ui.notify(`Model ${modelId} not found in registry, trying fallback.`, "warning");
+        ctx.ui.notify(`Model ${modelId} not found in available models, trying fallback.`, "warning");
         continue;
       }
 
@@ -1696,13 +1757,11 @@ async function buildResearchMilestonePrompt(mid: string, midTitle: string, base:
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
   const outputRelPath = relMilestoneFile(base, mid, "RESEARCH");
-  const outputAbsPath = resolveMilestoneFile(base, mid, "RESEARCH") ?? join(base, outputRelPath);
   return loadPrompt("research-milestone", {
     milestoneId: mid, milestoneTitle: midTitle,
     milestonePath: relMilestonePath(base, mid),
     contextPath: contextRel,
     outputPath: outputRelPath,
-    outputAbsPath,
     inlinedContext,
     ...buildSkillDiscoveryVars(),
   });
@@ -1730,7 +1789,6 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
   const outputRelPath = relMilestoneFile(base, mid, "ROADMAP");
-  const outputAbsPath = resolveMilestoneFile(base, mid, "ROADMAP") ?? join(base, outputRelPath);
   const secretsOutputPath = relMilestoneFile(base, mid, "SECRETS");
   return loadPrompt("plan-milestone", {
     milestoneId: mid, milestoneTitle: midTitle,
@@ -1738,7 +1796,6 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
     contextPath: contextRel,
     researchPath: researchRel,
     outputPath: outputRelPath,
-    outputAbsPath,
     secretsOutputPath,
     inlinedContext,
   });
@@ -1770,7 +1827,6 @@ async function buildResearchSlicePrompt(
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
   const outputRelPath = relSliceFile(base, mid, sid, "RESEARCH");
-  const outputAbsPath = resolveSliceFile(base, mid, sid, "RESEARCH") ?? join(base, outputRelPath);
   return loadPrompt("research-slice", {
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
     slicePath: relSlicePath(base, mid, sid),
@@ -1778,7 +1834,6 @@ async function buildResearchSlicePrompt(
     contextPath: contextRel,
     milestoneResearchPath: milestoneResearchRel,
     outputPath: outputRelPath,
-    outputAbsPath,
     inlinedContext,
     dependencySummaries: depContent,
     ...buildSkillDiscoveryVars(),
@@ -1807,16 +1862,12 @@ async function buildPlanSlicePrompt(
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
   const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
-  const outputAbsPath = resolveSliceFile(base, mid, sid, "PLAN") ?? join(base, outputRelPath);
-  const sliceAbsPath = resolveSlicePath(base, mid, sid) ?? join(base, relSlicePath(base, mid, sid));
   return loadPrompt("plan-slice", {
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
     slicePath: relSlicePath(base, mid, sid),
-    sliceAbsPath,
     roadmapPath: roadmapRel,
     researchPath: researchRel,
     outputPath: outputRelPath,
-    outputAbsPath,
     inlinedContext,
     dependencySummaries: depContent,
   });
@@ -1867,8 +1918,7 @@ async function buildExecuteTaskPrompt(
 
   const carryForwardSection = await buildCarryForwardSection(priorSummaries, base);
 
-  const sliceDirAbs = resolveSlicePath(base, mid, sid) ?? join(base, relSlicePath(base, mid, sid));
-  const taskSummaryAbsPath = join(sliceDirAbs, "tasks", `${tid}-SUMMARY.md`);
+  const taskSummaryPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`;
 
   return loadPrompt("execute-task", {
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle, taskId: tid, taskTitle: tTitle,
@@ -1880,7 +1930,7 @@ async function buildExecuteTaskPrompt(
     carryForwardSection,
     resumeSection,
     priorTaskLines: priorLines,
-    taskSummaryAbsPath,
+    taskSummaryPath,
   });
 }
 
@@ -1916,17 +1966,17 @@ async function buildCompleteSlicePrompt(
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
-  const sliceDirAbs = resolveSlicePath(base, mid, sid) ?? join(base, relSlicePath(base, mid, sid));
-  const sliceSummaryAbsPath = join(sliceDirAbs, `${sid}-SUMMARY.md`);
-  const sliceUatAbsPath = join(sliceDirAbs, `${sid}-UAT.md`);
+  const sliceRel = relSlicePath(base, mid, sid);
+  const sliceSummaryPath = `${sliceRel}/${sid}-SUMMARY.md`;
+  const sliceUatPath = `${sliceRel}/${sid}-UAT.md`;
 
   return loadPrompt("complete-slice", {
     milestoneId: mid, sliceId: sid, sliceTitle: sTitle,
-    slicePath: relSlicePath(base, mid, sid),
+    slicePath: sliceRel,
     roadmapPath: roadmapRel,
     inlinedContext,
-    sliceSummaryAbsPath,
-    sliceUatAbsPath,
+    sliceSummaryPath,
+    sliceUatPath,
   });
 }
 
@@ -1965,15 +2015,14 @@ async function buildCompleteMilestonePrompt(
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
-  const milestoneDirAbs = resolveMilestonePath(base, mid) ?? join(base, relMilestonePath(base, mid));
-  const milestoneSummaryAbsPath = join(milestoneDirAbs, `${mid}-SUMMARY.md`);
+  const milestoneSummaryPath = `${relMilestonePath(base, mid)}/${mid}-SUMMARY.md`;
 
   return loadPrompt("complete-milestone", {
     milestoneId: mid,
     milestoneTitle: midTitle,
     roadmapPath: roadmapRel,
     inlinedContext,
-    milestoneSummaryAbsPath,
+    milestoneSummaryPath,
   });
 }
 
@@ -2016,8 +2065,7 @@ async function buildReplanSlicePrompt(
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
-  const sliceDirAbs = resolveSlicePath(base, mid, sid) ?? join(base, relSlicePath(base, mid, sid));
-  const replanAbsPath = join(sliceDirAbs, `${sid}-REPLAN.md`);
+  const replanPath = `${relSlicePath(base, mid, sid)}/${sid}-REPLAN.md`;
 
   return loadPrompt("replan-slice", {
     milestoneId: mid,
@@ -2027,7 +2075,7 @@ async function buildReplanSlicePrompt(
     planPath: slicePlanRel,
     blockerTaskId,
     inlinedContext,
-    replanAbsPath,
+    replanPath,
   });
 }
 
@@ -2145,8 +2193,6 @@ async function buildRunUatPrompt(
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
-  const sliceDirAbs = resolveSlicePath(base, mid, sliceId) ?? join(base, relSlicePath(base, mid, sliceId));
-  const uatResultAbsPath = join(sliceDirAbs, `${sliceId}-UAT-RESULT.md`);
   const uatResultPath = relSliceFile(base, mid, sliceId, "UAT-RESULT");
   const uatType = extractUatType(uatContent) ?? "human-experience";
 
@@ -2154,7 +2200,6 @@ async function buildRunUatPrompt(
     milestoneId: mid,
     sliceId,
     uatPath,
-    uatResultAbsPath,
     uatResultPath,
     uatType,
     inlinedContext,
@@ -2181,9 +2226,7 @@ async function buildReassessRoadmapPrompt(
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
-  const assessmentRel = relSliceFile(base, mid, completedSliceId, "ASSESSMENT");
-  const sliceDirAbs = resolveSlicePath(base, mid, completedSliceId) ?? join(base, relSlicePath(base, mid, completedSliceId));
-  const assessmentAbsPath = join(sliceDirAbs, `${completedSliceId}-ASSESSMENT.md`);
+  const assessmentPath = relSliceFile(base, mid, completedSliceId, "ASSESSMENT");
 
   return loadPrompt("reassess-roadmap", {
     milestoneId: mid,
@@ -2191,8 +2234,7 @@ async function buildReassessRoadmapPrompt(
     completedSliceId,
     roadmapPath: roadmapRel,
     completedSliceSummaryPath: summaryRel,
-    assessmentPath: assessmentRel,
-    assessmentAbsPath,
+    assessmentPath,
     inlinedContext,
   });
 }
@@ -2790,6 +2832,23 @@ function verifyExpectedArtifact(unitType: string, unitId: string, base: string):
   if (!absPath) return true;
   if (!existsSync(absPath)) return false;
 
+  // execute-task must also have its checkbox marked [x] in the slice plan
+  if (unitType === "execute-task") {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const sid = parts[1];
+    const tid = parts[2];
+    if (mid && sid && tid) {
+      const planAbs = resolveSliceFile(base, mid, sid, "PLAN");
+      if (planAbs && existsSync(planAbs)) {
+        const planContent = readFileSync(planAbs, "utf-8");
+        const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const re = new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m");
+        if (!re.test(planContent)) return false;
+      }
+    }
+  }
+
   // complete-slice must also produce a UAT file
   if (unitType === "complete-slice") {
     const parts = unitId.split("/");
@@ -2814,7 +2873,7 @@ function verifyExpectedArtifact(unitType: string, unitId: string, base: string):
 export function writeBlockerPlaceholder(unitType: string, unitId: string, base: string, reason: string): string | null {
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
   if (!absPath) return null;
-  const dir = absPath.substring(0, absPath.lastIndexOf("/"));
+  const dir = dirname(absPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const content = [
     `# BLOCKER — auto-mode recovery failed`,

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -13,6 +13,61 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md
 
 ---
 
+## Semantics
+
+### Empty Arrays vs Omitted Fields
+
+**Empty arrays (`[]`) are equivalent to omitting the field entirely.** During validation, GSD deletes empty arrays from the preferences object (see `validatePreferences()` in `preferences.ts`):
+
+```typescript
+for (const key of ["always_use_skills", "prefer_skills", "avoid_skills", "custom_instructions"] as const) {
+  if (validated[key] && validated[key]!.length === 0) {
+    delete validated[key];
+  }
+}
+```
+
+These are functionally identical:
+
+```yaml
+# Explicit empty arrays — will be normalized away
+prefer_skills: []
+avoid_skills: []
+skill_rules: []
+
+# Omitted entirely — same result
+# (just don't write these fields)
+```
+
+**Recommendation:** Omit fields you don't need. Empty arrays add noise with no effect.
+
+### Global vs Project Preferences
+
+Preferences are loaded from two locations and merged:
+
+1. **Global:** `~/.gsd/preferences.md` — applies to all projects
+2. **Project:** `.gsd/preferences.md` — applies to the current project only
+
+**Merge behavior** (see `mergePreferences()` in `preferences.ts`):
+- **Scalar fields** (`skill_discovery`, `budget_ceiling`, etc.): Project wins if defined, otherwise global. Uses nullish coalescing (`??`).
+- **Array fields** (`always_use_skills`, `prefer_skills`, etc.): Concatenated via `mergeStringLists()` (global first, then project).
+- **Object fields** (`models`, `git`, `auto_supervisor`): Shallow merge via spread operator `{ ...base, ...override }`.
+
+For `models`, project settings override global at the phase level. If global has `planning: opus` and project has `planning: sonnet`, the project wins. But if project omits `research`, global's `research` setting is preserved.
+
+### Skill Discovery vs Skill Preferences
+
+These are **separate concerns**:
+
+| Field | What it controls | Code reference |
+|-------|-----------------|----------------|
+| `skill_discovery` | **Whether** GSD looks for relevant skills during research | `resolveSkillDiscoveryMode()` in `preferences.ts` |
+| `always_use_skills`, `prefer_skills`, `avoid_skills` | **Which** skills to use when they're found relevant | `renderPreferencesForSystemPrompt()` in `preferences.ts` |
+
+Setting `prefer_skills: []` does **not** disable skill discovery — it just means you have no preference overrides. Use `skill_discovery: off` to disable discovery entirely.
+
+---
+
 ## Field Guide
 
 - `version`: schema version. Start at `1`.
@@ -60,6 +115,27 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md
 - Use `skill_rules` for situational routing, not broad personality preferences.
 - Prefer skill names for stable built-in skills.
 - Prefer absolute paths for local personal skills.
+- **Omit fields you don't need** — empty arrays add noise with no effect.
+
+---
+
+## Minimal Example
+
+The cleanest preferences file only specifies what you actually want:
+
+```yaml
+---
+version: 1
+always_use_skills:
+  - debug-like-expert
+skill_discovery: suggest
+models:
+  planning: claude-opus-4-6
+  execution: claude-sonnet-4-6
+---
+```
+
+Everything else uses defaults. No `prefer_skills: []`, no `avoid_skills: []`, no `auto_supervisor: {}` — those are just noise.
 
 ---