gsd-pi 0.3.0 → 0.3.3

package/src/resources/extensions/browser-tools/index.ts

@@ -8,7 +8,7 @@
  *  - Every action returns feedback (accessibility snapshot, screenshots on navigate)
  *  - Errors include visual debugging (screenshots on failure, surfaced JS errors)
  *  - Smart waits (domcontentloaded + best-effort settle, not blocking networkidle)
- *  - 2x DPI screenshots for readable text
+ *  - Screenshots capped at 1568px max dimension (Anthropic API limit safety)
  *  - JPEG for viewport screenshots (smaller), PNG for element crops (transparency)
  *  - Auto-handles JS dialogs (alert/confirm/prompt) to prevent page freezes
  *  - Auto-switches to new tabs (popups, target="_blank")
@@ -343,7 +343,10 @@ async function ensureBrowser(): Promise<{ browser: Browser; context: BrowserCont
 	// Lazy import so playwright is only loaded when actually needed
 	const { chromium } = await import("playwright");
 
-	browser = await chromium.launch({ headless: false });
+	const launchOptions: Record<string, unknown> = { headless: false };
+	const customPath = process.env.BROWSER_PATH;
+	if (customPath) launchOptions.executablePath = customPath;
+	browser = await chromium.launch(launchOptions);
 	context = await browser.newContext({
 		deviceScaleFactor: 2,
 		viewport: { width: 1280, height: 800 },
@@ -728,11 +731,75 @@ async function postActionSummary(p: Page, target?: Page | Frame): Promise<string
 	}
 }
 
+// Anthropic API rejects images > 2000px in multi-image requests.
+// Cap at 1568px (recommended optimal size) to stay well within limits.
+const MAX_SCREENSHOT_DIM = 1568;
+
+/**
+ * If either dimension of the image buffer exceeds MAX_SCREENSHOT_DIM,
+ * downscale proportionally using the browser's canvas (zero dependencies).
+ * Returns the original buffer unchanged if already within limits.
+ */
+async function constrainScreenshot(
+	page: Page,
+	buffer: Buffer,
+	mimeType: string,
+	quality: number,
+): Promise<Buffer> {
+	let width: number;
+	let height: number;
+
+	if (mimeType === "image/png") {
+		width = buffer.readUInt32BE(16);
+		height = buffer.readUInt32BE(20);
+	} else {
+		width = 0;
+		height = 0;
+		for (let i = 0; i < buffer.length - 8; i++) {
+			if (buffer[i] === 0xff && (buffer[i + 1] === 0xc0 || buffer[i + 1] === 0xc2)) {
+				height = buffer.readUInt16BE(i + 5);
+				width = buffer.readUInt16BE(i + 7);
+				break;
+			}
+		}
+	}
+
+	if (width <= MAX_SCREENSHOT_DIM && height <= MAX_SCREENSHOT_DIM) {
+		return buffer;
+	}
+
+	const b64 = buffer.toString("base64");
+	const result = await page.evaluate(
+		async ({ b64, mime, maxDim, q }) => {
+			const img = new Image();
+			await new Promise<void>((resolve, reject) => {
+				img.onload = () => resolve();
+				img.onerror = reject;
+				img.src = `data:${mime};base64,${b64}`;
+			});
+			const scale = Math.min(maxDim / img.width, maxDim / img.height);
+			const w = Math.round(img.width * scale);
+			const h = Math.round(img.height * scale);
+			const canvas = document.createElement("canvas");
+			canvas.width = w;
+			canvas.height = h;
+			const ctx = canvas.getContext("2d")!;
+			ctx.drawImage(img, 0, 0, w, h);
+			return canvas.toDataURL(mime, q / 100);
+		},
+		{ b64, mime: mimeType, maxDim: MAX_SCREENSHOT_DIM, q: quality },
+	);
+
+	const resizedB64 = result.split(",")[1];
+	return Buffer.from(resizedB64, "base64");
+}
+
 /** Capture a JPEG screenshot for error debugging. Returns base64 or null. */
 async function captureErrorScreenshot(p: Page | null): Promise<{ data: string; mimeType: string } | null> {
     if (!p) return null;
     try {
-        const buf = await p.screenshot({ type: "jpeg", quality: 60 });
+        let buf = await p.screenshot({ type: "jpeg", quality: 60, scale: "css" });
+        buf = await constrainScreenshot(p, buf, "image/jpeg", 60);
         return { data: buf.toString("base64"), mimeType: "image/jpeg" };
     } catch {
         return null;
@@ -1599,7 +1666,8 @@ export default function (pi: ExtensionAPI) {
 
 				let screenshotContent: any[] = [];
 				try {
-					const buf = await p.screenshot({ type: "jpeg", quality: 80 });
+					let buf = await p.screenshot({ type: "jpeg", quality: 80, scale: "css" });
+					buf = await constrainScreenshot(p, buf, "image/jpeg", 80);
 					screenshotContent = [{ type: "image", data: buf.toString("base64"), mimeType: "image/jpeg" }];
 				} catch {}
 
@@ -1741,7 +1809,8 @@ export default function (pi: ExtensionAPI) {
 				// Include screenshot like navigate does
 				let screenshotContent: any[] = [];
 				try {
-					const buf = await p.screenshot({ type: "jpeg", quality: 80 });
+					let buf = await p.screenshot({ type: "jpeg", quality: 80, scale: "css" });
+					buf = await constrainScreenshot(p, buf, "image/jpeg", 80);
 					screenshotContent = [{
 						type: "image",
 						data: buf.toString("base64"),
@@ -1802,23 +1871,27 @@ export default function (pi: ExtensionAPI) {
 
 				let screenshotBuffer: Buffer;
 				let mimeType: string;
+				const quality = params.quality ?? 80;
 
 				if (params.selector) {
 					// Element screenshots: keep PNG (may have transparency)
 					const locator = p.locator(params.selector).first();
-					screenshotBuffer = await locator.screenshot({ type: "png" });
+					screenshotBuffer = await locator.screenshot({ type: "png", scale: "css" });
 					mimeType = "image/png";
 				} else {
 					// Viewport/fullpage: use JPEG (3-5x smaller, fine for AI analysis)
-					const quality = params.quality ?? 80;
 					screenshotBuffer = await p.screenshot({
 						fullPage: params.fullPage ?? false,
 						type: "jpeg",
 						quality,
+						scale: "css",
 					});
 					mimeType = "image/jpeg";
 				}
 
+				// Downscale if dimensions exceed API limit (1568px max)
+				screenshotBuffer = await constrainScreenshot(p, screenshotBuffer, mimeType, quality);
+
 				const base64Data = screenshotBuffer.toString("base64");
 				const title = await p.title();
 				const url = p.url();

package/src/resources/extensions/github/gh-api.ts

@@ -6,20 +6,44 @@
  * Falls back to raw REST API with GITHUB_TOKEN env var.
  */
 
-import { execSync } from "node:child_process";
+import { execSync, spawnSync, type SpawnSyncReturns } from "node:child_process";
 
 // ─── Auth detection ───────────────────────────────────────────────────────────
 
 let _useGhCli: boolean | null = null;
 
-function hasGhCli(): boolean {
+let ghSpawnImpl = (args: string[], input?: string, cwd?: string): SpawnSyncReturns<string> =>
+	spawnSync("gh", args, {
+		cwd,
+		encoding: "utf8",
+		stdio: ["pipe", "pipe", "pipe"],
+		input,
+	});
+
+function ghSpawn(args: string[], input?: string, cwd?: string): SpawnSyncReturns<string> {
+	return ghSpawnImpl(args, input, cwd);
+}
+
+export function resetGhCliDetectionForTests(): void {
+	_useGhCli = null;
+	ghSpawnImpl = (args: string[], input?: string, cwd?: string): SpawnSyncReturns<string> =>
+		spawnSync("gh", args, {
+			cwd,
+			encoding: "utf8",
+			stdio: ["pipe", "pipe", "pipe"],
+			input,
+		});
+}
+
+export function setGhSpawnForTests(fn: (args: string[], input?: string, cwd?: string) => SpawnSyncReturns<string>): void {
+	ghSpawnImpl = fn;
+	_useGhCli = null;
+}
+
+export function hasGhCli(): boolean {
 	if (_useGhCli !== null) return _useGhCli;
-	try {
-		execSync("gh auth status", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
-		_useGhCli = true;
-	} catch {
-		_useGhCli = false;
-	}
+	const result = ghSpawn(["auth", "token"]);
+	_useGhCli = result.status === 0 && !result.error && !!result.stdout?.trim();
 	return _useGhCli;
 }
 
@@ -120,11 +144,6 @@ export async function ghApi<T = unknown>(
 	return fetchApi<T>(endpoint, method, options.params, options.body, token);
 }
 
-function shellEscape(s: string): string {
-	// Single-quote wrapping, escaping any existing single quotes
-	return "'" + s.replace(/'/g, "'\\''") + "'";
-}
-
 function ghCliApi<T>(
 	endpoint: string,
 	method: string,
@@ -132,39 +151,36 @@ function ghCliApi<T>(
 	body?: Record<string, unknown>,
 	cwd?: string,
 ): T {
-	const parts = ["gh", "api", shellEscape(endpoint), "--method", method];
+	const args = ["api", endpoint, "--method", method];
 
 	if (params) {
 		for (const [key, val] of Object.entries(params)) {
 			if (val === undefined) continue;
 			if (Array.isArray(val)) {
 				for (const v of val) {
-					parts.push("-f", shellEscape(`${key}[]=${v}`));
+					args.push("-f", `${key}[]=${v}`);
 				}
 			} else {
-				parts.push("-f", shellEscape(`${key}=${String(val)}`));
+				args.push("-f", `${key}=${String(val)}`);
 			}
 		}
 	}
 
 	if (body) {
-		parts.push("--input", "-");
+		args.push("--input", "-");
 	}
 
-	try {
-		const result = execSync(parts.join(" "), {
-			cwd: cwd ?? process.cwd(),
-			encoding: "utf8",
-			stdio: ["pipe", "pipe", "pipe"],
-			input: body ? JSON.stringify(body) : undefined,
-		});
-		if (!result.trim()) return {} as T;
-		return JSON.parse(result) as T;
-	} catch (e: unknown) {
-		const err = e as { stderr?: string; stdout?: string; message?: string };
-		const msg = err.stderr?.trim() || err.stdout?.trim() || err.message || String(e);
-		throw new Error(`gh api error: ${msg}`);
+	const result = ghSpawn(args, body ? JSON.stringify(body) : undefined, cwd ?? process.cwd());
+
+	const stdout = result.stdout?.trim() ?? "";
+	const stderr = result.stderr?.trim() ?? "";
+
+	if (result.status !== 0) {
+		throw new Error(`gh api error: ${stderr || stdout || result.error?.message || `exit code ${result.status}`}`);
 	}
+
+	if (!stdout) return {} as T;
+	return JSON.parse(stdout) as T;
 }
 
 async function fetchApi<T>(

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

@@ -18,7 +18,7 @@ import type {
 
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
@@ -36,7 +36,6 @@ import {
   clearUnitRuntimeRecord,
   formatExecuteTaskRecoveryStatus,
   inspectExecuteTaskDurability,
-  recordUnitProgress,
   readUnitRuntimeRecord,
   writeUnitRuntimeRecord,
 } from "./unit-runtime.js";
@@ -49,6 +48,7 @@ import {
   formatValidationIssues,
 } from "./observability-validator.js";
 import { ensureGitignore } from "./gitignore.js";
+import { runGSDDoctor, rebuildState } from "./doctor.js";
 import { snapshotSkills, clearSkillSnapshot } from "./skill-discovery.js";
 import {
   initMetrics, resetMetrics, snapshotUnitMetrics, getLedger,
@@ -65,11 +65,13 @@ import {
 } from "./worktree.ts";
 import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/ui.js";
+import { showNextAction } from "../shared/next-action-ui.js";
 
 // ─── State ────────────────────────────────────────────────────────────────────
 
 let active = false;
 let paused = false;
+let stepMode = false;
 let verbose = false;
 let cmdCtx: ExtensionCommandContext | null = null;
 let basePath = "";
@@ -102,6 +104,7 @@ let idleWatchdogHandle: ReturnType<typeof setInterval> | null = null;
 export interface AutoDashboardData {
   active: boolean;
   paused: boolean;
+  stepMode: boolean;
   startTime: number;
   elapsed: number;
   currentUnit: { type: string; id: string; startedAt: number } | null;
@@ -118,6 +121,7 @@ export function getAutoDashboardData(): AutoDashboardData {
   return {
     active,
     paused,
+    stepMode,
     startTime: autoStartTime,
     elapsed: (active || paused) ? Date.now() - autoStartTime : 0,
     currentUnit: currentUnit ? { ...currentUnit } : null,
@@ -138,6 +142,10 @@ export function isAutoPaused(): boolean {
   return paused;
 }
 
+export function isStepMode(): boolean {
+  return stepMode;
+}
+
 function clearUnitTimeout(): void {
   if (unitTimeoutHandle) {
     clearTimeout(unitTimeoutHandle);
@@ -174,6 +182,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   resetMetrics();
   active = false;
   paused = false;
+  stepMode = false;
   lastUnit = null;
   currentUnit = null;
   currentMilestoneId = null;
@@ -208,8 +217,9 @@ export async function pauseAuto(ctx?: ExtensionContext, _pi?: ExtensionAPI): Pro
   // — all needed for resume and dashboard display
   ctx?.ui.setStatus("gsd-auto", "paused");
   ctx?.ui.setWidget("gsd-progress", undefined);
+  const resumeCmd = stepMode ? "/gsd next" : "/gsd auto";
   ctx?.ui.notify(
-    "Auto-mode paused (Escape). Type to interact, or /gsd auto to resume.",
+    `${stepMode ? "Step" : "Auto"}-mode paused (Escape). Type to interact, or ${resumeCmd} to resume.`,
     "info",
   );
 }
@@ -219,19 +229,24 @@ export async function startAuto(
   pi: ExtensionAPI,
   base: string,
   verboseMode: boolean,
+  options?: { step?: boolean },
 ): Promise<void> {
+  const requestedStepMode = options?.step ?? false;
+
   // If resuming from paused state, just re-activate and dispatch next unit.
   // The conversation is still intact — no need to reinitialize everything.
   if (paused) {
     paused = false;
     active = true;
     verbose = verboseMode;
+    // Allow switching between step/auto on resume
+    stepMode = requestedStepMode;
     cmdCtx = ctx;
     basePath = base;
     // Re-initialize metrics in case ledger was lost during pause
     if (!getLedger()) initMetrics(base);
-    ctx.ui.setStatus("gsd-auto", "auto");
-    ctx.ui.notify("Auto-mode resumed.", "info");
+    ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
+    ctx.ui.notify(stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
     await dispatchNextUnit(ctx, pi);
     return;
   }
@@ -287,7 +302,7 @@ export async function startAuto(
   // No active work at all — start a new milestone via the discuss flow.
   if (!state.activeMilestone || state.phase === "complete") {
     const { showSmartEntry } = await import("./guided-flow.js");
-    await showSmartEntry(ctx, pi, base);
+    await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
     return;
   }
 
@@ -299,13 +314,14 @@ export async function startAuto(
     const hasContext = !!(contextFile && await loadFile(contextFile));
     if (!hasContext) {
       const { showSmartEntry } = await import("./guided-flow.js");
-      await showSmartEntry(ctx, pi, base);
+      await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
       return;
     }
     // Has context, no roadmap — auto-mode will research + plan it
   }
 
   active = true;
+  stepMode = requestedStepMode;
   verbose = verboseMode;
   cmdCtx = ctx;
   basePath = base;
@@ -325,12 +341,13 @@ export async function startAuto(
     snapshotSkills();
   }
 
-  ctx.ui.setStatus("gsd-auto", "auto");
+  ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
+  const modeLabel = stepMode ? "Step-mode" : "Auto-mode";
   const pendingCount = state.registry.filter(m => m.status !== 'complete').length;
   const scopeMsg = pendingCount > 1
     ? `Will loop through ${pendingCount} milestones.`
     : "Will loop until milestone complete.";
-  ctx.ui.notify(`Auto-mode started. ${scopeMsg}`, "info");
+  ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
 
   // Dispatch the first unit
   await dispatchNextUnit(ctx, pi);
@@ -360,11 +377,141 @@ export async function handleAgentEnd(
     } catch {
       // Non-fatal
     }
+
+    // Post-hook: fix mechanical bookkeeping the LLM may have skipped.
+    // 1. Doctor handles: checkbox marking, stub summaries/UATs.
+    // 2. STATE.md is always rebuilt from disk state (purely derived, no LLM needed).
+    // This is more reliable than prompt instructions for mechanical tasks.
+    // Scope to slice level (M001/S01) so doctor checks all tasks within the slice.
+    try {
+      const scopeParts = currentUnit.id.split("/").slice(0, 2);
+      const doctorScope = scopeParts.join("/");
+      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope });
+      if (report.fixesApplied.length > 0) {
+        ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
+      }
+    } catch {
+      // Non-fatal — doctor failure should never block dispatch
+    }
+    try {
+      await rebuildState(basePath);
+      autoCommitCurrentBranch(basePath, currentUnit.type, currentUnit.id);
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // In step mode, pause and show a wizard instead of immediately dispatching
+  if (stepMode) {
+    await showStepWizard(ctx, pi);
+    return;
   }
 
   await dispatchNextUnit(ctx, pi);
 }
 
+// ─── Step Mode Wizard ─────────────────────────────────────────────────────
+
+/**
+ * Show the step-mode wizard after a unit completes.
+ * Derives the next unit from disk state and presents it to the user.
+ * If the user confirms, dispatches the next unit. If not, pauses.
+ */
+async function showStepWizard(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (!cmdCtx) return;
+
+  const state = await deriveState(basePath);
+  const mid = state.activeMilestone?.id;
+
+  // Build summary of what just completed
+  const justFinished = currentUnit
+    ? `${unitVerb(currentUnit.type)} ${currentUnit.id}`
+    : "previous unit";
+
+  // If no active milestone or everything is complete, stop
+  if (!mid || state.phase === "complete") {
+    await stopAuto(ctx, pi);
+    return;
+  }
+
+  // Peek at what's next by examining state
+  const nextDesc = describeNextUnit(state);
+
+  const choice = await showNextAction(cmdCtx, {
+    title: `GSD — ${justFinished} complete`,
+    summary: [
+      `${mid}: ${state.activeMilestone?.title ?? mid}`,
+      ...(state.activeSlice ? [`${state.activeSlice.id}: ${state.activeSlice.title}`] : []),
+    ],
+    actions: [
+      {
+        id: "continue",
+        label: nextDesc.label,
+        description: nextDesc.description,
+        recommended: true,
+      },
+      {
+        id: "auto",
+        label: "Switch to auto",
+        description: "Continue without pausing between steps.",
+      },
+      {
+        id: "status",
+        label: "View status",
+        description: "Open the dashboard.",
+      },
+    ],
+    notYetMessage: "Run /gsd next when ready to continue.",
+  });
+
+  if (choice === "continue") {
+    await dispatchNextUnit(ctx, pi);
+  } else if (choice === "auto") {
+    stepMode = false;
+    ctx.ui.setStatus("gsd-auto", "auto");
+    ctx.ui.notify("Switched to auto-mode.", "info");
+    await dispatchNextUnit(ctx, pi);
+  } else if (choice === "status") {
+    // Show status then re-show the wizard
+    const { fireStatusViaCommand } = await import("./commands.js");
+    await fireStatusViaCommand(ctx as ExtensionCommandContext);
+    await showStepWizard(ctx, pi);
+  } else {
+    // "not_yet" — pause
+    await pauseAuto(ctx, pi);
+  }
+}
+
+/**
+ * Describe what the next unit will be, based on current state.
+ */
+function describeNextUnit(state: GSDState): { label: string; description: string } {
+  const sid = state.activeSlice?.id;
+  const sTitle = state.activeSlice?.title;
+  const tid = state.activeTask?.id;
+  const tTitle = state.activeTask?.title;
+
+  switch (state.phase) {
+    case "pre-planning":
+      return { label: "Research & plan milestone", description: "Scout the landscape and create the roadmap." };
+    case "planning":
+      return { label: `Plan ${sid}: ${sTitle}`, description: "Research and decompose into tasks." };
+    case "executing":
+      return { label: `Execute ${tid}: ${tTitle}`, description: "Run the next task in a fresh session." };
+    case "summarizing":
+      return { label: `Complete ${sid}: ${sTitle}`, description: "Write summary, UAT, and merge to main." };
+    case "replanning-slice":
+      return { label: `Replan ${sid}: ${sTitle}`, description: "Blocker found — replan the slice." };
+    case "completing-milestone":
+      return { label: "Complete milestone", description: "Write milestone summary." };
+    default:
+      return { label: "Continue", description: "Execute the next step." };
+  }
+}
+
 // ─── Progress Widget ──────────────────────────────────────────────────────
 
 function unitVerb(unitType: string): string {
@@ -465,7 +612,8 @@ function updateProgressWidget(
           ? theme.fg("accent", GLYPH.statusActive)
           : theme.fg("dim", GLYPH.statusPending);
         const elapsed = formatAutoElapsed();
-        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))}  ${theme.fg("success", "AUTO")}`;
+        const modeTag = stepMode ? "NEXT" : "AUTO";
+        const headerLeft = `${pad}${dot} ${theme.fg("accent", theme.bold("GSD"))}  ${theme.fg("success", modeTag)}`;
         const headerRight = elapsed ? theme.fg("dim", elapsed) : "";
         lines.push(rightAlign(headerLeft, headerRight, width));
 
@@ -985,6 +1133,17 @@ async function dispatchNextUnit(
     if (!runtime) return;
     if (Date.now() - runtime.lastProgressAt < idleTimeoutMs) return;
 
+    // Before triggering recovery, check if the agent is actually producing
+    // work on disk.  `git status --porcelain` is cheap and catches any
+    // staged/unstaged/untracked changes the agent made since lastProgressAt.
+    if (detectWorkingTreeActivity(basePath)) {
+      writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnit.startedAt, {
+        lastProgressAt: Date.now(),
+        lastProgressKind: "filesystem-activity",
+      });
+      return;
+    }
+
     if (currentUnit) {
       const modelId = ctx.model?.id ?? "unknown";
       snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
@@ -2136,6 +2295,25 @@ export function skipExecuteTask(
   return true;
 }
 
+/**
+ * Detect whether the agent is producing work on disk by checking git for
+ * any working-tree changes (staged, unstaged, or untracked). Returns true
+ * if there are uncommitted changes — meaning the agent is actively working,
+ * even though it hasn't signaled progress through runtime records.
+ */
+function detectWorkingTreeActivity(cwd: string): boolean {
+  try {
+    const out = execSync("git status --porcelain", {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    return out.toString().trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolve the expected artifact for a non-execute-task unit to an absolute path.
  * Returns null for unit types that don't produce a single file (execute-task,

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

@@ -10,8 +10,8 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
-import { showSmartEntry, showQueue, showDiscuss } from "./guided-flow.js";
-import { startAuto, stopAuto, isAutoActive, isAutoPaused } from "./auto.js";
+import { showQueue, showDiscuss } from "./guided-flow.js";
+import { startAuto, stopAuto, isAutoActive, isAutoPaused, isStepMode } from "./auto.js";
 import {
   getGlobalGSDPreferencesPath,
   getLegacyGlobalGSDPreferencesPath,
@@ -52,10 +52,10 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Stuff Done: /gsd auto|stop|status|queue|prefs|doctor|migrate",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|doctor|migrate",
 
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate"];
+      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate"];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
@@ -112,6 +112,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "next" || trimmed.startsWith("next ")) {
+        const verboseMode = trimmed.includes("--verbose");
+        await startAuto(ctx, pi, process.cwd(), verboseMode, { step: true });
+        return;
+      }
+
       if (trimmed === "auto" || trimmed.startsWith("auto ")) {
         const verboseMode = trimmed.includes("--verbose");
         await startAuto(ctx, pi, process.cwd(), verboseMode);
@@ -143,12 +149,13 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       if (trimmed === "") {
-        await showSmartEntry(ctx, pi, process.cwd());
+        // Bare /gsd defaults to step mode
+        await startAuto(ctx, pi, process.cwd(), false, { step: true });
         return;
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status], /gsd doctor [audit|fix|heal] [M###/S##], or /gsd migrate <path>.`,
+        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status], /gsd doctor [audit|fix|heal] [M###/S##], or /gsd migrate <path>.`,
         "warning",
       );
     },

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

@@ -147,6 +147,13 @@ async function updateStateFile(basePath: string, fixesApplied: string[]): Promis
   fixesApplied.push(`updated ${path}`);
 }
 
+/** Rebuild STATE.md from current disk state. Exported for auto-mode post-hooks. */
+export async function rebuildState(basePath: string): Promise<void> {
+  const state = await deriveState(basePath);
+  const path = resolveGsdRootFile(basePath, "STATE");
+  await saveFile(path, buildStateMarkdown(state));
+}
+
 async function ensureSliceSummaryStub(basePath: string, milestoneId: string, sliceId: string, fixesApplied: string[]): Promise<void> {
   const path = join(resolveSlicePath(basePath, milestoneId, sliceId) ?? relSlicePath(basePath, milestoneId, sliceId), `${sliceId}-SUMMARY.md`);
   const absolute = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY") ?? join(resolveSlicePath(basePath, milestoneId, sliceId)!, `${sliceId}-SUMMARY.md`);