gsd-pi 2.4.0 → 2.5.1

package/README.md

@@ -252,17 +252,18 @@ Branch-per-slice with squash merge. Fully automated.
 
 ```
 main:
-  feat(M001/S03): auth and session management
+  docs(M001/S04): workflow documentation and examples
+  fix(M001/S03): bug fixes and doc corrections
   feat(M001/S02): API endpoints and middleware
   feat(M001/S01): data model and type system
 
-gsd/M001/S01 (preserved):
+gsd/M001/S01 (deleted after merge):
   feat(S01/T03): file writer with round-trip fidelity
   feat(S01/T02): markdown parser for plan files
   feat(S01/T01): core types and interfaces
 ```
 
-One commit per slice on main. Per-task history preserved on branches. Git bisect works. Individual slices are revertable.
+One commit per slice on main. Squash commits are the permanent record — branches are deleted after merge. Git bisect works. Individual slices are revertable.
 
 ### Verification
 

package/dist/loader.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'url';
 import { dirname, resolve, join } from 'path';
-import { readFileSync } from 'fs';
-import { agentDir } from './app-paths.js';
+import { existsSync, readFileSync } from 'fs';
+import { agentDir, appRoot } from './app-paths.js';
+import { renderLogo } from './logo.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
 // This allows config.js to:
@@ -14,7 +15,24 @@ const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'pkg');
 process.env.PI_PACKAGE_DIR = pkgDir;
 process.env.PI_SKIP_VERSION_CHECK = '1'; // GSD ships its own update check — suppress pi's
 process.title = 'gsd';
-// First-launch branding is handled by the onboarding wizard (src/onboarding.ts)
+// Print branded banner on first launch (before ~/.gsd/ exists)
+if (!existsSync(appRoot)) {
+    const cyan = '\x1b[36m';
+    const green = '\x1b[32m';
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    const colorCyan = (s) => `${cyan}${s}${reset}`;
+    let version = '';
+    try {
+        const pkgJson = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
+        version = pkgJson.version ?? '';
+    }
+    catch { /* ignore */ }
+    process.stderr.write(renderLogo(colorCyan) +
+        '\n' +
+        `  Get Shit Done ${dim}v${version}${reset}\n` +
+        `  ${green}Welcome.${reset} Setting up your environment...\n\n`);
+}
 // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.gsd/agent/
 process.env.GSD_CODING_AGENT_DIR = agentDir;
 // NODE_PATH — make gsd's own node_modules available to extensions loaded via jiti.

package/dist/logo.d.ts

@@ -3,14 +3,14 @@
  *
  * Single source of truth — imported by:
  *   - scripts/postinstall.js (via dist/logo.js)
- *   - src/onboarding.ts (via ./logo.js)
+ *   - src/loader.ts (via ./logo.js)
  */
 /** Raw logo lines — no ANSI codes, no leading newline. */
-export declare const GSD_LOGO: string[];
+export declare const GSD_LOGO: readonly string[];
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. picocolors.cyan or `(s) => `\x1b[36m${s}\x1b[0m``
+ * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export declare function renderLogo(color: (s: string) => string): string;

package/dist/logo.js

@@ -3,7 +3,7 @@
  *
  * Single source of truth — imported by:
  *   - scripts/postinstall.js (via dist/logo.js)
- *   - src/onboarding.ts (via ./logo.js)
+ *   - src/loader.ts (via ./logo.js)
  */
 /** Raw logo lines — no ANSI codes, no leading newline. */
 export const GSD_LOGO = [
@@ -17,7 +17,7 @@ export const GSD_LOGO = [
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. picocolors.cyan or `(s) => `\x1b[36m${s}\x1b[0m``
+ * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export function renderLogo(color) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
   "scripts": {
     "build": "tsc && npm run copy-themes",
     "copy-themes": "node -e \"const{mkdirSync,cpSync}=require('fs');const{resolve}=require('path');const src=resolve(__dirname,'node_modules/@mariozechner/pi-coding-agent/dist/modes/interactive/theme');mkdirSync('pkg/dist/modes/interactive/theme',{recursive:true});cpSync(src,'pkg/dist/modes/interactive/theme',{recursive:true})\"",
-    "test": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test 'src/resources/extensions/gsd/tests/*.test.ts' 'src/resources/extensions/gsd/tests/*.test.mjs' 'src/tests/*.test.ts'",
+    "test": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/resources/extensions/gsd/tests/*.test.ts src/resources/extensions/gsd/tests/*.test.mjs src/tests/*.test.ts",
     "dev": "tsc --watch",
     "postinstall": "node scripts/postinstall.js",
     "pi:install-global": "node scripts/install-pi-global.js",

package/src/resources/GSD-WORKFLOW.md

@@ -548,7 +548,7 @@ If files disagree, **pause and surface to the user**:
 1. **Slice starts** → create branch `gsd/M001/S01` from main
 2. **Per-task commits** on the branch — atomic, descriptive, bisectable
 3. **Slice completes** → squash merge to main as one clean commit
-4. **Branch kept** — not deleted, available for per-task history
+4. **Branch deleted** — squash commit on main is the permanent record
 
 ### What Main Looks Like
 
@@ -566,21 +566,21 @@ One commit per slice. Individually revertable. Reads like a changelog.
 gsd/M001/S01:
   test(S01): round-trip tests passing
   feat(S01/T03): file writer with round-trip fidelity
-  checkpoint(S01/T03): pre-task
+  chore(S01/T03): auto-commit after task
   feat(S01/T02): markdown parser for plan files
-  checkpoint(S01/T02): pre-task
+  chore(S01/T02): auto-commit after task
   feat(S01/T01): core types and interfaces
-  checkpoint(S01/T01): pre-task
+  chore(S01/T01): auto-commit after task
 ```
 
 ### Commit Conventions
 
 | When | Format | Example |
 |------|--------|---------|
-| Before each task | `checkpoint(S01/T02): pre-task` | Safety net for `git reset` |
+| Auto-commit (dirty state) | `chore(S01/T02): auto-commit after task` | Automatic save of work in progress |
 | After task verified | `feat(S01/T02): <what was built>` | The real work |
 | Plan/docs committed | `docs(S01): add slice plan` | Bundled with first task |
-| Slice squash to main | `feat(M001/S01): <slice title>` | Clean one-liner on main |
+| Slice squash to main | `type(M001/S01): <slice title>` | Type inferred from title (`feat`, `fix`, `docs`, etc.) |
 
 Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`
 
@@ -601,7 +601,7 @@ Tasks completed:
 
 | Problem | Fix |
 |---------|-----|
-| Bad task | `git reset --hard` to checkpoint on the branch |
+| Bad task | `git reset --hard HEAD~1` to previous commit on the branch |
 | Bad slice | `git revert <squash commit>` on main |
 | UAT failure after merge | Fix tasks on `gsd/M001/S01-fix` branch, squash as `fix(M001/S01): <fix>` |
 

package/src/resources/extensions/get-secrets-from-user.ts

@@ -7,6 +7,7 @@
  */
 
 import { readFile, writeFile } from "node:fs/promises";
+import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
@@ -25,6 +26,8 @@ interface ToolResultDetails {
 	environment?: string;
 	applied: string[];
 	skipped: string[];
+	existingSkipped?: string[];
+	detectedDestination?: string;
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -91,6 +94,52 @@ async function writeEnvKey(filePath: string, key: string, value: string): Promis
 	await writeFile(filePath, content, "utf8");
 }
 
+// ─── Exported utilities ───────────────────────────────────────────────────────
+
+/**
+ * Check which keys already exist in the .env file or process.env.
+ * Returns the subset of `keys` that are already set.
+ * Handles ENOENT gracefully (still checks process.env).
+ * Empty-string values count as existing.
+ */
+export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise<string[]> {
+	let fileContent = "";
+	try {
+		fileContent = await readFile(envFilePath, "utf8");
+	} catch {
+		// ENOENT or other read error — proceed with empty content
+	}
+
+	const existing: string[] = [];
+	for (const key of keys) {
+		const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const regex = new RegExp(`^${escaped}\\s*=`, "m");
+		if (regex.test(fileContent) || key in process.env) {
+			existing.push(key);
+		}
+	}
+	return existing;
+}
+
+/**
+ * Detect the write destination based on project files in basePath.
+ * Priority: vercel.json → convex/ dir → fallback "dotenv".
+ */
+export function detectDestination(basePath: string): "dotenv" | "vercel" | "convex" {
+	if (existsSync(resolve(basePath, "vercel.json"))) {
+		return "vercel";
+	}
+	const convexPath = resolve(basePath, "convex");
+	try {
+		if (existsSync(convexPath) && statSync(convexPath).isDirectory()) {
+			return "convex";
+		}
+	} catch {
+		// stat error — treat as not found
+	}
+	return "dotenv";
+}
+
 // ─── Paged secure input UI ────────────────────────────────────────────────────
 
 /**
@@ -209,16 +258,17 @@ export default function secureEnv(pi: ExtensionAPI) {
 			"Never echo, log, or repeat secret values in your responses. Only report key names and applied/skipped status.",
 		],
 		parameters: Type.Object({
-			destination: Type.Union([
+			destination: Type.Optional(Type.Union([
 				Type.Literal("dotenv"),
 				Type.Literal("vercel"),
 				Type.Literal("convex"),
-			], { description: "Where to write the collected secrets" }),
+			], { description: "Where to write the collected secrets" })),
 			keys: Type.Array(
 				Type.Object({
 					key: Type.String({ description: "Env var name, e.g. OPENAI_API_KEY" }),
 					hint: Type.Optional(Type.String({ description: "Format hint shown to user, e.g. 'starts with sk-'" })),
 					required: Type.Optional(Type.Boolean()),
+					guidance: Type.Optional(Type.Array(Type.String(), { description: "Step-by-step guidance for finding this key" })),
 				}),
 				{ minItems: 1 },
 			),
@@ -240,6 +290,10 @@ export default function secureEnv(pi: ExtensionAPI) {
 				};
 			}
 
+			// Auto-detect destination when not provided
+			const destinationAutoDetected = params.destination == null;
+			const destination = params.destination ?? detectDestination(ctx.cwd);
+
 			const collected: CollectedSecret[] = [];
 
 			// Collect one key per page
@@ -255,7 +309,7 @@ export default function secureEnv(pi: ExtensionAPI) {
 			const errors: string[] = [];
 
 			// Apply to destination
-			if (params.destination === "dotenv") {
+			if (destination === "dotenv") {
 				const filePath = resolve(ctx.cwd, params.envFilePath ?? ".env");
 				for (const { key, value } of provided) {
 					try {
@@ -267,7 +321,7 @@ export default function secureEnv(pi: ExtensionAPI) {
 				}
 			}
 
-			if (params.destination === "vercel") {
+			if (destination === "vercel") {
 				const env = params.environment ?? "development";
 				for (const { key, value } of provided) {
 					try {
@@ -286,7 +340,7 @@ export default function secureEnv(pi: ExtensionAPI) {
 				}
 			}
 
-			if (params.destination === "convex") {
+			if (destination === "convex") {
 				for (const { key, value } of provided) {
 					try {
 						const result = await pi.exec("sh", [
@@ -305,14 +359,15 @@ export default function secureEnv(pi: ExtensionAPI) {
 			}
 
 			const details: ToolResultDetails = {
-				destination: params.destination,
+				destination,
 				environment: params.environment,
 				applied,
 				skipped,
+				...(destinationAutoDetected ? { detectedDestination: destination } : {}),
 			};
 
 			const lines = [
-				`destination: ${params.destination}${params.environment ? ` (${params.environment})` : ""}`,
+				`destination: ${destination}${destinationAutoDetected ? " (auto-detected)" : ""}${params.environment ? ` (${params.environment})` : ""}`,
 				...applied.map((k) => `✓ ${k}: applied`),
 				...skipped.map((k) => `• ${k}: skipped`),
 				...errors.map((e) => `✗ ${e}`),
@@ -329,7 +384,7 @@ export default function secureEnv(pi: ExtensionAPI) {
 			const count = Array.isArray(args.keys) ? args.keys.length : 0;
 			return new Text(
 				theme.fg("toolTitle", theme.bold("secure_env_collect ")) +
-				theme.fg("muted", `→ ${args.destination}`) +
+				theme.fg("muted", `→ ${args.destination ?? "auto"}`) +
 				theme.fg("dim", `  ${count} key${count !== 1 ? "s" : ""}`),
 				0, 0,
 			);

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

@@ -56,17 +56,18 @@ import {
 } from "./metrics.js";
 import { join } from "node:path";
 import { readdirSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import {
   autoCommitCurrentBranch,
   ensureSliceBranch,
   getCurrentBranch,
   getMainBranch,
-  getSliceBranchName,
   parseSliceBranch,
   switchToMain,
   mergeSliceToMain,
 } from "./worktree.ts";
+import { GitServiceImpl } from "./git-service.ts";
+import type { GitPreferences } from "./git-service.ts";
 import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
 import { showNextAction } from "../shared/next-action-ui.js";
@@ -93,6 +94,18 @@ function persistCompletedKey(base: string, key: string): void {
   }
 }
 
+/** Remove a stale completed unit key from disk. */
+function removePersistedKey(base: string, key: string): void {
+  const file = completedKeysPath(base);
+  try {
+    if (existsSync(file)) {
+      let keys: string[] = JSON.parse(readFileSync(file, "utf-8"));
+      keys = keys.filter(k => k !== key);
+      writeFileSync(file, JSON.stringify(keys), "utf-8");
+    }
+  } catch { /* non-fatal */ }
+}
+
 /** Load all completed unit keys from disk into the in-memory set. */
 function loadPersistedKeys(base: string, target: Set<string>): void {
   const file = completedKeysPath(base);
@@ -112,6 +125,7 @@ let stepMode = false;
 let verbose = false;
 let cmdCtx: ExtensionCommandContext | null = null;
 let basePath = "";
+let gitService: GitServiceImpl | null = null;
 
 /** Track total dispatches per unit to detect stuck loops (catches A→B→A→B patterns) */
 const unitDispatchCount = new Map<string, number>();
@@ -359,7 +373,8 @@ export async function startAuto(
   try {
     execSync("git rev-parse --git-dir", { cwd: base, stdio: "pipe" });
   } catch {
-    execSync("git init", { cwd: base, stdio: "pipe" });
+    const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
+    execFileSync("git", ["init", "-b", mainBranch], { cwd: base, stdio: "pipe" });
   }
 
   // Ensure .gitignore has baseline patterns
@@ -376,6 +391,9 @@ export async function startAuto(
     } catch { /* nothing to commit */ }
   }
 
+  // Initialize GitServiceImpl — basePath is set and git repo confirmed
+  gitService = new GitServiceImpl(basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+
   // Check for crash from previous session
   const crashLock = readCrashLock(base);
   if (crashLock) {
@@ -658,7 +676,7 @@ function peekNext(unitType: string, state: GSDState): string {
   const sid = state.activeSlice?.id ?? "";
   switch (unitType) {
     case "research-milestone": return "plan milestone roadmap";
-    case "plan-milestone": return "research first slice";
+    case "plan-milestone": return "plan or execute first slice";
     case "research-slice": return `plan ${sid}`;
     case "plan-slice": return "execute first task";
     case "execute-task": return `continue ${sid}`;
@@ -1005,14 +1023,35 @@ async function dispatchNextUnit(
             midTitle = state.activeMilestone?.title;
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+
+            // Safety net: if mergeSliceToMain failed to clean up (or the error
+            // came from switchToMain), ensure the working tree isn't left in a
+            // conflicted/dirty merge state. Without this, state derivation reads
+            // conflict-marker-filled files, produces a corrupt phase, and
+            // dispatch loops forever (see: merge-bug-fix).
+            try {
+              const { runGit } = await import("./git-service.ts");
+              const status = runGit(basePath, ["status", "--porcelain"], { allowFailure: true });
+              if (status && (status.includes("UU ") || status.includes("AA ") || status.includes("UD "))) {
+                runGit(basePath, ["reset", "--hard", "HEAD"], { allowFailure: true });
+                ctx.ui.notify(
+                  `Cleaned up conflicted merge state after failed squash-merge.`,
+                  "warning",
+                );
+              }
+            } catch { /* best-effort cleanup */ }
+
             ctx.ui.notify(
-              `Slice merge failed: ${message}`,
+              `Slice merge failed — stopping auto-mode. Fix conflicts manually and restart.\n${message}`,
               "error",
             );
-            // Re-derive state so dispatch can figure out what to do
-            state = await deriveState(basePath);
-            mid = state.activeMilestone?.id;
-            midTitle = state.activeMilestone?.title;
+            if (currentUnit) {
+              const modelId = ctx.model?.id ?? "unknown";
+              snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+              saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
+            }
+            await stopAuto(ctx, pi);
+            return;
           }
         }
       }
@@ -1140,9 +1179,19 @@ async function dispatchNextUnit(
       const hasResearch = !!(researchFile && await loadFile(researchFile));
 
       if (!hasResearch) {
-        unitType = "research-slice";
-        unitId = `${mid}/${sid}`;
-        prompt = await buildResearchSlicePrompt(mid, midTitle!, sid, sTitle, basePath);
+        // 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));
+        if (hasMilestoneResearch && sid === "S01") {
+          unitType = "plan-slice";
+          unitId = `${mid}/${sid}`;
+          prompt = await buildPlanSlicePrompt(mid, midTitle!, sid, sTitle, basePath);
+        } else {
+          unitType = "research-slice";
+          unitId = `${mid}/${sid}`;
+          prompt = await buildResearchSlicePrompt(mid, midTitle!, sid, sTitle, basePath);
+        }
       } else {
         unitType = "plan-slice";
         unitId = `${mid}/${sid}`;
@@ -1190,15 +1239,27 @@ async function dispatchNextUnit(
   // Idempotency: skip units already completed in a prior session.
   const idempotencyKey = `${unitType}/${unitId}`;
   if (completedKeySet.has(idempotencyKey)) {
-    ctx.ui.notify(
-      `Skipping ${unitType} ${unitId} — already completed in a prior session. Advancing.`,
-      "info",
-    );
-    // Yield to the event loop before re-dispatching to avoid tight recursion
-    // when many units are already completed (e.g., after crash recovery).
-    await new Promise(r => setImmediate(r));
-    await dispatchNextUnit(ctx, pi);
-    return;
+    // Cross-validate: does the expected artifact actually exist?
+    const artifactExists = verifyExpectedArtifact(unitType, unitId, basePath);
+    if (artifactExists) {
+      ctx.ui.notify(
+        `Skipping ${unitType} ${unitId} — already completed in a prior session. Advancing.`,
+        "info",
+      );
+      // Yield to the event loop before re-dispatching to avoid tight recursion
+      // when many units are already completed (e.g., after crash recovery).
+      await new Promise(r => setImmediate(r));
+      await dispatchNextUnit(ctx, pi);
+      return;
+    } else {
+      // Stale completion record — artifact missing. Remove and re-run.
+      completedKeySet.delete(idempotencyKey);
+      removePersistedKey(basePath, idempotencyKey);
+      ctx.ui.notify(
+        `Re-running ${unitType} ${unitId} — marked complete but expected artifact missing.`,
+        "warning",
+      );
+    }
   }
 
   // Stuck detection — tracks total dispatches per unit (not just consecutive repeats).
@@ -1234,20 +1295,26 @@ async function dispatchNextUnit(
     snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
     saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
 
-    // Persist completion to disk BEFORE updating memory — so a crash here is recoverable.
+    // Only mark the previous unit as completed if:
+    // 1. We're not about to re-dispatch the same unit (retry scenario)
+    // 2. The expected artifact actually exists on disk
     const closeoutKey = `${currentUnit.type}/${currentUnit.id}`;
-    persistCompletedKey(basePath, closeoutKey);
-    completedKeySet.add(closeoutKey);
-
-    completedUnits.push({
-      type: currentUnit.type,
-      id: currentUnit.id,
-      startedAt: currentUnit.startedAt,
-      finishedAt: Date.now(),
-    });
-    clearUnitRuntimeRecord(basePath, currentUnit.type, currentUnit.id);
-    unitDispatchCount.delete(`${currentUnit.type}/${currentUnit.id}`);
-    unitRecoveryCount.delete(`${currentUnit.type}/${currentUnit.id}`);
+    const incomingKey = `${unitType}/${unitId}`;
+    const artifactVerified = verifyExpectedArtifact(currentUnit.type, currentUnit.id, basePath);
+    if (closeoutKey !== incomingKey && artifactVerified) {
+      persistCompletedKey(basePath, closeoutKey);
+      completedKeySet.add(closeoutKey);
+
+      completedUnits.push({
+        type: currentUnit.type,
+        id: currentUnit.id,
+        startedAt: currentUnit.startedAt,
+        finishedAt: Date.now(),
+      });
+      clearUnitRuntimeRecord(basePath, currentUnit.type, currentUnit.id);
+      unitDispatchCount.delete(`${currentUnit.type}/${currentUnit.id}`);
+      unitRecoveryCount.delete(`${currentUnit.type}/${currentUnit.id}`);
+    }
   }
   currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
   writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
@@ -1588,6 +1655,7 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
 
   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,
     milestonePath: relMilestonePath(base, mid),
@@ -1595,6 +1663,7 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
     researchPath: researchRel,
     outputPath: outputRelPath,
     outputAbsPath,
+    secretsOutputPath,
     inlinedContext,
   });
 }
@@ -2587,6 +2656,15 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
       const dir = resolveSlicePath(base, mid, sid!);
       return dir ? join(dir, buildSliceFileName(sid!, "UAT-RESULT")) : null;
     }
+    case "execute-task": {
+      const tid = parts[2];
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir && tid ? join(dir, "tasks", buildTaskFileName(tid, "SUMMARY")) : null;
+    }
+    case "complete-slice": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "SUMMARY")) : null;
+    }
     case "complete-milestone": {
       const dir = resolveMilestonePath(base, mid);
       return dir ? join(dir, buildMilestoneFileName(mid, "SUMMARY")) : null;
@@ -2596,6 +2674,17 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
   }
 }
 
+/**
+ * Check whether the expected artifact for a unit exists on disk.
+ * Returns true if the artifact file exists, or if the unit type has no
+ * single verifiable artifact (e.g., replan-slice).
+ */
+function verifyExpectedArtifact(unitType: string, unitId: string, base: string): boolean {
+  const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
+  if (!absPath) return true;
+  return existsSync(absPath);
+}
+
 /**
  * Write a placeholder artifact so the pipeline can advance past a stuck unit.
  * Returns the relative path written, or null if the path couldn't be resolved.

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

@@ -40,6 +40,15 @@ Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md
   - `idle_timeout_minutes`: minutes of inactivity before the supervisor intervenes (default: 10).
   - `hard_timeout_minutes`: minutes before the supervisor forces termination (default: 30).
 
+- `git`: configures GSD's git behavior. All fields are optional — omit any to use defaults. Keys:
+  - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
+  - `push_branches`: boolean — push newly created slice branches to the remote. Default: `false`.
+  - `remote`: string — git remote name to push to. Default: `"origin"`.
+  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `false`.
+  - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a slice branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
+  - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
+  - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
+
 ---
 
 ## Best Practices
@@ -101,3 +110,22 @@ skill_rules:
       - find-skills
 ---
 ```
+
+---
+
+## Git Preferences Example
+
+```yaml
+---
+version: 1
+git:
+  auto_push: true
+  push_branches: true
+  remote: origin
+  snapshots: true
+  pre_merge_check: auto
+  commit_type: feat
+---
+```
+
+All git fields are optional. Omit any field to use the default behavior. Project-level preferences override global preferences on a per-field basis.