gsd-pi 0.3.1 → 0.3.3

package/dist/resource-loader.d.ts

@@ -15,8 +15,8 @@ import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
  */
 export declare function initResources(agentDir: string): void;
 /**
- * Constructs a DefaultResourceLoader with no additionalExtensionPaths.
- * Extensions are synced to agentDir by initResources() and pi auto-discovers
- * them from ~/.gsd/agent/extensions/ via its normal agentDir scan.
+ * Constructs a DefaultResourceLoader that loads extensions from both
+ * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
+ * This allows users to use extensions from either location.
  */
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -1,4 +1,5 @@
 import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+import { homedir } from 'node:os';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -45,10 +46,15 @@ export function initResources(agentDir) {
     }
 }
 /**
- * Constructs a DefaultResourceLoader with no additionalExtensionPaths.
- * Extensions are synced to agentDir by initResources() and pi auto-discovers
- * them from ~/.gsd/agent/extensions/ via its normal agentDir scan.
+ * Constructs a DefaultResourceLoader that loads extensions from both
+ * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
+ * This allows users to use extensions from either location.
  */
 export function buildResourceLoader(agentDir) {
-    return new DefaultResourceLoader({ agentDir });
+    const piAgentDir = join(homedir(), '.pi', 'agent');
+    const piExtensionsDir = join(piAgentDir, 'extensions');
+    return new DefaultResourceLoader({
+        agentDir,
+        additionalExtensionPaths: [piExtensionsDir],
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,8 @@
     "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",
+    "pi:uninstall-global": "node scripts/uninstall-pi-global.js",
     "sync-pkg-version": "node scripts/sync-pkg-version.cjs",
     "prepublishOnly": "npm run sync-pkg-version && npm run build"
   },

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")
@@ -731,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;
@@ -1602,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 {}
 
@@ -1744,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"),
@@ -1805,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/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 Shit 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`);

package/src/resources/extensions/gsd/guided-flow.ts

@@ -31,13 +31,14 @@ let pendingAutoStart: {
   pi: ExtensionAPI;
   basePath: string;
   milestoneId: string; // the milestone being discussed
+  step?: boolean; // preserve step mode through discuss → auto transition
 } | null = null;
 
 /** Called from agent_end to check if auto-mode should start after discuss */
 export function checkAutoStartAfterDiscuss(): boolean {
   if (!pendingAutoStart) return false;
 
-  const { ctx, pi, basePath, milestoneId } = pendingAutoStart;
+  const { ctx, pi, basePath, milestoneId, step } = pendingAutoStart;
 
   // Don't fire until the discuss phase has actually produced a context file
   // for the milestone being discussed. agent_end fires after every LLM turn,
@@ -47,7 +48,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
   if (!contextFile) return false; // no context yet — keep waiting
 
   pendingAutoStart = null;
-  startAuto(ctx, pi, basePath, false).catch(() => {});
+  startAuto(ctx, pi, basePath, false, { step }).catch(() => {});
   return true;
 }
 
@@ -435,7 +436,9 @@ export async function showSmartEntry(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
   basePath: string,
+  options?: { step?: boolean },
 ): Promise<void> {
+  const stepMode = options?.step;
 
   // ── Ensure git repo exists — GSD needs it for branch-per-slice ──────
   try {
@@ -501,7 +504,7 @@ export async function showSmartEntry(
 
     if (isFirst) {
       // First ever — skip wizard, just ask directly
-      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode };
       dispatchWorkflow(pi, buildDiscussPrompt(nextId,
         `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`,
         basePath
@@ -522,7 +525,7 @@ export async function showSmartEntry(
       });
 
       if (choice === "new_milestone") {
-        pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+        pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode };
         dispatchWorkflow(pi, buildDiscussPrompt(nextId,
           `New milestone ${nextId}.`,
           basePath
@@ -560,7 +563,7 @@ export async function showSmartEntry(
       const milestoneIds = findMilestoneIds(basePath);
       const nextId = `M${String(milestoneIds.length + 1).padStart(3, "0")}`;
 
-      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode };
       dispatchWorkflow(pi, buildDiscussPrompt(nextId,
         `New milestone ${nextId}.`,
         basePath