gsd-pi 2.22.0 → 2.24.0

package/dist/resources/extensions/browser-tools/tools/pdf.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+export function registerPdfTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_save_pdf",
+		label: "Browser Save PDF",
+		description:
+			"Render current page as PDF artifact via Playwright's page.pdf(). " +
+			"Supports A4/Letter/custom page formats and optional background graphics. " +
+			"Writes to session artifacts directory. Chromium only.",
+		parameters: Type.Object({
+			filename: Type.Optional(
+				Type.String({ description: "Output filename (default: auto-generated from page title + timestamp)." }),
+			),
+			format: Type.Optional(
+				Type.String({
+					description:
+						"Page format: 'A4' (default), 'Letter', 'Legal', 'Tabloid', or custom like '8.5in x 11in'. " +
+						"Custom format uses CSS dimension syntax for width x height.",
+				}),
+			),
+			printBackground: Type.Optional(
+				Type.Boolean({ description: "Include background graphics (default: true)." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+
+				const url = p.url();
+				const title = await p.title().catch(() => "untitled");
+
+				// Resolve filename
+				const timestamp = deps.formatArtifactTimestamp(Date.now());
+				const safeName = deps.sanitizeArtifactName(params.filename || `${title}-${timestamp}`, `pdf-${timestamp}`);
+				const filename = safeName.endsWith(".pdf") ? safeName : `${safeName}.pdf`;
+
+				// Resolve format
+				const knownFormats = new Set(["A4", "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A5", "A6"]);
+				const formatInput = params.format ?? "A4";
+				let pdfOptions: Record<string, unknown> = {};
+
+				if (knownFormats.has(formatInput)) {
+					pdfOptions.format = formatInput;
+				} else {
+					// Custom format: parse "WIDTHin x HEIGHTin" or "WIDTHcm x HEIGHTcm" etc.
+					const customMatch = formatInput.match(/^(.+?)\s*[xX×]\s*(.+)$/);
+					if (customMatch) {
+						pdfOptions.width = customMatch[1]!.trim();
+						pdfOptions.height = customMatch[2]!.trim();
+					} else {
+						pdfOptions.format = "A4"; // fallback
+					}
+				}
+
+				pdfOptions.printBackground = params.printBackground ?? true;
+
+				// Generate PDF
+				await deps.ensureSessionArtifactDir();
+				const outputPath = deps.buildSessionArtifactPath(filename);
+				pdfOptions.path = outputPath;
+
+				await p.pdf(pdfOptions as any);
+
+				// Read file size
+				const { stat } = await import("node:fs/promises");
+				const fileStat = await stat(outputPath);
+				const sizeBytes = fileStat.size;
+				const sizeKB = (sizeBytes / 1024).toFixed(1);
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `PDF saved: ${outputPath}\nSize: ${sizeKB} KB\nFormat: ${formatInput}\nPage: ${title}\nURL: ${url}`,
+						},
+					],
+					details: { path: outputPath, sizeBytes, format: formatInput, pageUrl: url, pageTitle: title },
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `PDF generation failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/dist/resources/extensions/browser-tools/tools/state-persistence.ts

@@ -0,0 +1,202 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * State persistence tools — save/restore cookies, localStorage, sessionStorage.
+ */
+
+const STATE_DIR = ".gsd/browser-state";
+
+export function registerStatePersistenceTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	// -------------------------------------------------------------------------
+	// browser_save_state
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_save_state",
+		label: "Browser Save State",
+		description:
+			"Save cookies, localStorage, and sessionStorage to disk so authenticated sessions survive browser restarts. " +
+			"State files are written to .gsd/browser-state/ and should be gitignored (may contain auth tokens). " +
+			"Never displays secret values in output.",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({ description: "Name for the state file (default: 'default'). Used as the filename stem." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: ctx, page: p } = await deps.ensureBrowser();
+				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
+
+				const { mkdir, writeFile } = await import("node:fs/promises");
+				const path = await import("node:path");
+				const stateDir = path.resolve(process.cwd(), STATE_DIR);
+				await mkdir(stateDir, { recursive: true });
+
+				// 1. Playwright storageState: cookies + localStorage
+				const storageState = await ctx.storageState();
+
+				// 2. sessionStorage: must be extracted per-origin via page.evaluate
+				const sessionStorageData: Record<string, Record<string, string>> = {};
+				try {
+					const origin = new URL(p.url()).origin;
+					const ssData = await p.evaluate(() => {
+						const data: Record<string, string> = {};
+						for (let i = 0; i < sessionStorage.length; i++) {
+							const key = sessionStorage.key(i);
+							if (key) data[key] = sessionStorage.getItem(key) ?? "";
+						}
+						return data;
+					});
+					if (Object.keys(ssData).length > 0) {
+						sessionStorageData[origin] = ssData;
+					}
+				} catch {
+					// Page may not have a valid origin (about:blank, etc.)
+				}
+
+				const combined = {
+					storageState,
+					sessionStorage: sessionStorageData,
+					savedAt: new Date().toISOString(),
+					url: p.url(),
+				};
+
+				const filePath = path.join(stateDir, `${name}.json`);
+				await writeFile(filePath, JSON.stringify(combined, null, 2));
+
+				// Ensure .gitignore covers the state dir
+				const gitignorePath = path.resolve(process.cwd(), STATE_DIR, ".gitignore");
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+
+				const cookieCount = storageState.cookies?.length ?? 0;
+				const localStorageOrigins = storageState.origins?.length ?? 0;
+				const sessionStorageOrigins = Object.keys(sessionStorageData).length;
+
+				return {
+					content: [{
+						type: "text",
+						text: `State saved: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}`,
+					}],
+					details: {
+						path: filePath,
+						cookieCount,
+						localStorageOrigins,
+						sessionStorageOrigins,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Save state failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+
+	// -------------------------------------------------------------------------
+	// browser_restore_state
+	// -------------------------------------------------------------------------
+	pi.registerTool({
+		name: "browser_restore_state",
+		label: "Browser Restore State",
+		description:
+			"Restore cookies, localStorage, and sessionStorage from a previously saved state file. " +
+			"Injects cookies via context.addCookies() and storage via page.evaluate(). " +
+			"For full fidelity, restore before navigating to the target site.",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({ description: "Name of the state file to restore (default: 'default')." }),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { context: ctx, page: p } = await deps.ensureBrowser();
+				const name = deps.sanitizeArtifactName(params.name ?? "default", "default");
+
+				const { readFile } = await import("node:fs/promises");
+				const path = await import("node:path");
+				const filePath = path.join(process.cwd(), STATE_DIR, `${name}.json`);
+
+				let raw: string;
+				try {
+					raw = await readFile(filePath, "utf-8");
+				} catch {
+					return {
+						content: [{ type: "text", text: `State file not found: ${filePath}` }],
+						details: { error: "file_not_found", path: filePath },
+						isError: true,
+					};
+				}
+
+				const combined = JSON.parse(raw);
+				const storageState = combined.storageState;
+				const sessionStorageData: Record<string, Record<string, string>> = combined.sessionStorage ?? {};
+
+				// 1. Restore cookies
+				let cookieCount = 0;
+				if (storageState?.cookies?.length) {
+					await ctx.addCookies(storageState.cookies);
+					cookieCount = storageState.cookies.length;
+				}
+
+				// 2. Restore localStorage via page.evaluate
+				let localStorageOrigins = 0;
+				if (storageState?.origins?.length) {
+					for (const origin of storageState.origins) {
+						try {
+							await p.evaluate((items: Array<{ name: string; value: string }>) => {
+								for (const { name, value } of items) {
+									localStorage.setItem(name, value);
+								}
+							}, origin.localStorage ?? []);
+							localStorageOrigins++;
+						} catch {
+							// Origin mismatch — localStorage can only be set on matching origin
+						}
+					}
+				}
+
+				// 3. Restore sessionStorage via page.evaluate
+				let sessionStorageOrigins = 0;
+				for (const [_origin, data] of Object.entries(sessionStorageData)) {
+					try {
+						await p.evaluate((items: Record<string, string>) => {
+							for (const [key, value] of Object.entries(items)) {
+								sessionStorage.setItem(key, value);
+							}
+						}, data);
+						sessionStorageOrigins++;
+					} catch {
+						// Origin mismatch
+					}
+				}
+
+				return {
+					content: [{
+						type: "text",
+						text: `State restored from: ${filePath}\nCookies: ${cookieCount}\nlocalStorage origins: ${localStorageOrigins}\nsessionStorage origins: ${sessionStorageOrigins}\nSaved at: ${combined.savedAt ?? "unknown"}`,
+					}],
+					details: {
+						path: filePath,
+						cookieCount,
+						localStorageOrigins,
+						sessionStorageOrigins,
+						savedAt: combined.savedAt,
+						savedUrl: combined.url,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Restore state failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/dist/resources/extensions/browser-tools/tools/visual-diff.ts

@@ -0,0 +1,209 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Visual regression diffing — compare current page screenshot against a stored baseline.
+ */
+
+const BASELINE_DIR = ".gsd/browser-baselines";
+
+export function registerVisualDiffTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_visual_diff",
+		label: "Browser Visual Diff",
+		description:
+			"Compare current page screenshot against a stored baseline pixel-by-pixel. " +
+			"Returns similarity score (0–1), diff pixel count, and optionally generates a diff image highlighting changes. " +
+			"On first run with no baseline, saves the current screenshot as the baseline. " +
+			"Baselines are stored in .gsd/browser-baselines/ (gitignored, environment-specific).",
+		parameters: Type.Object({
+			name: Type.Optional(
+				Type.String({
+					description:
+						"Baseline name (default: auto-generated from URL + viewport). " +
+						"Use consistent names to compare the same view across runs.",
+				}),
+			),
+			selector: Type.Optional(
+				Type.String({
+					description: "CSS selector to scope comparison to a specific element instead of full viewport.",
+				}),
+			),
+			threshold: Type.Optional(
+				Type.Number({
+					description:
+						"Pixel matching threshold 0–1 (default: 0.1). " +
+						"Higher values are more tolerant of anti-aliasing and rendering differences.",
+				}),
+			),
+			updateBaseline: Type.Optional(
+				Type.Boolean({
+					description: "If true, overwrite the existing baseline with the current screenshot (default: false).",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const { mkdir, readFile, writeFile } = await import("node:fs/promises");
+				const pathMod = await import("node:path");
+
+				const baselineDir = pathMod.resolve(process.cwd(), BASELINE_DIR);
+				await mkdir(baselineDir, { recursive: true });
+
+				// Ensure .gitignore
+				const gitignorePath = pathMod.join(baselineDir, ".gitignore");
+				await writeFile(gitignorePath, "*\n!.gitignore\n").catch(() => {});
+
+				// Generate baseline name
+				const url = p.url();
+				const viewport = p.viewportSize();
+				const vpSuffix = viewport ? `${viewport.width}x${viewport.height}` : "unknown";
+				const autoName = deps.sanitizeArtifactName(
+					`${new URL(url).pathname.replace(/\//g, "-")}-${vpSuffix}`,
+					`baseline-${vpSuffix}`,
+				);
+				const name = deps.sanitizeArtifactName(params.name ?? autoName, autoName);
+
+				const baselinePath = pathMod.join(baselineDir, `${name}.png`);
+				const diffPath = pathMod.join(baselineDir, `${name}-diff.png`);
+
+				// Capture current screenshot as PNG (needed for pixel comparison)
+				let currentBuffer: Buffer;
+				if (params.selector) {
+					const locator = p.locator(params.selector).first();
+					currentBuffer = await locator.screenshot({ type: "png" });
+				} else {
+					currentBuffer = await p.screenshot({ type: "png", fullPage: false });
+				}
+
+				// Check if baseline exists
+				let baselineBuffer: Buffer | null = null;
+				try {
+					baselineBuffer = await readFile(baselinePath) as Buffer;
+				} catch {
+					// No baseline yet
+				}
+
+				if (!baselineBuffer || params.updateBaseline) {
+					// Save as new baseline
+					await writeFile(baselinePath, currentBuffer);
+					return {
+						content: [{
+							type: "text",
+							text: baselineBuffer
+								? `Baseline updated: ${baselinePath}\nSize: ${(currentBuffer.length / 1024).toFixed(1)} KB`
+								: `Baseline created (first run): ${baselinePath}\nSize: ${(currentBuffer.length / 1024).toFixed(1)} KB\nRe-run to compare against this baseline.`,
+						}],
+						details: {
+							baselinePath,
+							baselineCreated: !baselineBuffer,
+							baselineUpdated: !!baselineBuffer,
+							sizeBytes: currentBuffer.length,
+						},
+					};
+				}
+
+				// Perform pixel comparison using sharp for PNG decoding
+				const sharp = (await import("sharp")).default;
+
+				const baselineMeta = await sharp(baselineBuffer).metadata();
+				const currentMeta = await sharp(currentBuffer).metadata();
+
+				const bWidth = baselineMeta.width ?? 0;
+				const bHeight = baselineMeta.height ?? 0;
+				const cWidth = currentMeta.width ?? 0;
+				const cHeight = currentMeta.height ?? 0;
+
+				// If dimensions differ, report mismatch
+				if (bWidth !== cWidth || bHeight !== cHeight) {
+					return {
+						content: [{
+							type: "text",
+							text: `Dimension mismatch: baseline is ${bWidth}x${bHeight}, current is ${cWidth}x${cHeight}. Cannot compare.\nUse updateBaseline: true to reset.`,
+						}],
+						details: {
+							match: false,
+							dimensionMismatch: true,
+							baselineDimensions: { width: bWidth, height: bHeight },
+							currentDimensions: { width: cWidth, height: cHeight },
+						},
+					};
+				}
+
+				// Extract raw RGBA pixel data
+				const baselineRaw = await sharp(baselineBuffer).ensureAlpha().raw().toBuffer();
+				const currentRaw = await sharp(currentBuffer).ensureAlpha().raw().toBuffer();
+
+				const width = bWidth;
+				const height = bHeight;
+				const totalPixels = width * height;
+				const threshold = params.threshold ?? 0.1;
+
+				// Simple pixel-by-pixel comparison (avoiding pixelmatch dependency)
+				const diffData = Buffer.alloc(width * height * 4);
+				let diffPixels = 0;
+				const thresholdSq = threshold * threshold * 255 * 255 * 3;
+
+				for (let i = 0; i < totalPixels; i++) {
+					const offset = i * 4;
+					const dr = baselineRaw[offset] - currentRaw[offset];
+					const dg = baselineRaw[offset + 1] - currentRaw[offset + 1];
+					const db = baselineRaw[offset + 2] - currentRaw[offset + 2];
+					const distSq = dr * dr + dg * dg + db * db;
+
+					if (distSq > thresholdSq) {
+						diffPixels++;
+						// Mark diff pixels as red
+						diffData[offset] = 255;     // R
+						diffData[offset + 1] = 0;   // G
+						diffData[offset + 2] = 0;   // B
+						diffData[offset + 3] = 255; // A
+					} else {
+						// Dim unchanged pixels
+						diffData[offset] = currentRaw[offset] >> 1;
+						diffData[offset + 1] = currentRaw[offset + 1] >> 1;
+						diffData[offset + 2] = currentRaw[offset + 2] >> 1;
+						diffData[offset + 3] = 255;
+					}
+				}
+
+				const similarity = 1 - (diffPixels / totalPixels);
+				const match = diffPixels === 0;
+
+				// Save diff image
+				await sharp(diffData, { raw: { width, height, channels: 4 } })
+					.png()
+					.toFile(diffPath);
+
+				return {
+					content: [{
+						type: "text",
+						text: match
+							? `Visual diff: MATCH (100% similar)\nBaseline: ${baselinePath}`
+							: `Visual diff: ${(similarity * 100).toFixed(2)}% similar\nDiff pixels: ${diffPixels} of ${totalPixels} (${((diffPixels / totalPixels) * 100).toFixed(2)}%)\nDiff image: ${diffPath}\nBaseline: ${baselinePath}`,
+					}],
+					details: {
+						match,
+						similarity,
+						diffPixels,
+						totalPixels,
+						diffPercentage: (diffPixels / totalPixels) * 100,
+						dimensions: { width, height },
+						baselinePath,
+						diffImagePath: match ? undefined : diffPath,
+						threshold,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Visual diff failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/dist/resources/extensions/browser-tools/tools/zoom.ts

@@ -0,0 +1,104 @@
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { ToolDeps } from "../state.js";
+
+/**
+ * Region zoom / high-res capture — capture and upscale specific page regions.
+ */
+
+export function registerZoomTools(pi: ExtensionAPI, deps: ToolDeps): void {
+	pi.registerTool({
+		name: "browser_zoom_region",
+		label: "Browser Zoom Region",
+		description:
+			"Capture and optionally upscale a specific rectangular region of the page for detailed inspection. " +
+			"Useful for dense UIs where full-page screenshots have text too small to read. " +
+			"Returns the region as an inline image, same as browser_screenshot.",
+		parameters: Type.Object({
+			x: Type.Number({ description: "Left coordinate of the region in CSS pixels." }),
+			y: Type.Number({ description: "Top coordinate of the region in CSS pixels." }),
+			width: Type.Number({ description: "Width of the region in CSS pixels." }),
+			height: Type.Number({ description: "Height of the region in CSS pixels." }),
+			scale: Type.Optional(
+				Type.Number({
+					description: "Upscale factor (default: 2). Use 1 for native resolution, 2-4 for zoomed detail.",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const { page: p } = await deps.ensureBrowser();
+				const { x, y, width, height } = params;
+				const scale = params.scale ?? 2;
+
+				// Validate dimensions
+				if (width <= 0 || height <= 0) {
+					return {
+						content: [{ type: "text", text: "Width and height must be positive." }],
+						details: { error: "invalid_dimensions" },
+						isError: true,
+					};
+				}
+
+				// Capture the region using Playwright's clip option
+				const regionBuffer = await p.screenshot({
+					type: "png",
+					clip: { x, y, width, height },
+				});
+
+				let outputBuffer: Buffer = regionBuffer;
+				let outputMime = "image/png";
+
+				// Upscale if scale > 1
+				if (scale > 1) {
+					const sharp = (await import("sharp")).default;
+					const targetWidth = Math.round(width * scale);
+					const targetHeight = Math.round(height * scale);
+
+					outputBuffer = await sharp(regionBuffer)
+						.resize(targetWidth, targetHeight, {
+							kernel: "lanczos3",
+							fit: "fill",
+						})
+						.png()
+						.toBuffer();
+				}
+
+				const base64Data = outputBuffer.toString("base64");
+				const title = await p.title();
+				const url = p.url();
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Region capture: ${width}x${height} at (${x},${y})${scale > 1 ? ` upscaled ${scale}x to ${Math.round(width * scale)}x${Math.round(height * scale)}` : ""}\nPage: ${title}\nURL: ${url}`,
+						},
+						{
+							type: "image",
+							data: base64Data,
+							mimeType: outputMime,
+						},
+					],
+					details: {
+						region: { x, y, width, height },
+						scale,
+						outputDimensions: {
+							width: Math.round(width * scale),
+							height: Math.round(height * scale),
+						},
+						title,
+						url,
+					},
+				};
+			} catch (err: any) {
+				return {
+					content: [{ type: "text", text: `Region zoom failed: ${err.message}` }],
+					details: { error: err.message },
+					isError: true,
+				};
+			}
+		},
+	});
+}

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -41,6 +41,8 @@ export interface AutoDashboardData {
   profileDowngraded?: boolean;
   /** Number of pending captures awaiting triage (0 if none or file missing) */
   pendingCaptureCount: number;
+  /** Cross-process: another auto-mode session detected via auto.lock (PID, startedAt) */
+  remoteSession?: { pid: number; startedAt: string; unitType: string; unitId: string };
 }
 
 // ─── Unit Description Helpers ─────────────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-dispatch.ts

@@ -14,9 +14,11 @@ import type { GSDPreferences } from "./preferences.js";
 import type { UatType } from "./files.js";
 import { loadFile, extractUatType, loadActiveOverrides } from "./files.js";
 import {
-  resolveMilestoneFile, resolveSliceFile,
-  relSliceFile,
+  resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile,
+  relSliceFile, buildMilestoneFileName,
 } from "./paths.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import {
   buildResearchMilestonePrompt,
   buildPlanMilestonePrompt,
@@ -25,6 +27,7 @@ import {
   buildExecuteTaskPrompt,
   buildCompleteSlicePrompt,
   buildCompleteMilestonePrompt,
+  buildValidateMilestonePrompt,
   buildReplanSlicePrompt,
   buildRunUatPrompt,
   buildReassessRoadmapPrompt,
@@ -246,6 +249,20 @@ const DISPATCH_RULES: DispatchRule[] = [
       const sTitle = state.activeSlice!.title;
       const tid = state.activeTask.id;
       const tTitle = state.activeTask.title;
+
+      // Guard: refuse to dispatch execute-task when the task plan file is missing.
+      // This prevents the agent from running blind after a failed plan-slice that
+      // wrote S{sid}-PLAN.md but omitted the individual T{tid}-PLAN.md files.
+      // (See issue #739 — missing task plan caused runaway execution and EPIPE crash.)
+      const taskPlanPath = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+      if (!taskPlanPath || !existsSync(taskPlanPath)) {
+        return {
+          action: "stop",
+          reason: `Task plan ${tid}-PLAN.md is missing for ${mid}/${sid}/${tid}. Re-run plan-slice to regenerate task plans, or create the file manually and resume.`,
+          level: "error",
+        };
+      }
+
       return {
         action: "dispatch",
         unitType: "execute-task",
@@ -254,6 +271,38 @@ const DISPATCH_RULES: DispatchRule[] = [
       };
     },
   },
+  {
+    name: "validating-milestone → validate-milestone",
+    match: async ({ state, mid, midTitle, basePath, prefs }) => {
+      if (state.phase !== "validating-milestone") return null;
+      // Skip preference: write a minimal pass-through VALIDATION file
+      if (prefs?.phases?.skip_milestone_validation) {
+        const mDir = resolveMilestonePath(basePath, mid);
+        if (mDir) {
+          if (!existsSync(mDir)) mkdirSync(mDir, { recursive: true });
+          const validationPath = join(mDir, buildMilestoneFileName(mid, "VALIDATION"));
+          const content = [
+            "---",
+            "verdict: pass",
+            "remediation_round: 0",
+            "---",
+            "",
+            "# Milestone Validation (skipped by preference)",
+            "",
+            "Milestone validation was skipped via `skip_milestone_validation` preference.",
+          ].join("\n");
+          writeFileSync(validationPath, content, "utf-8");
+        }
+        return { action: "skip" };
+      }
+      return {
+        action: "dispatch",
+        unitType: "validate-milestone",
+        unitId: mid,
+        prompt: await buildValidateMilestonePrompt(mid, midTitle, basePath),
+      };
+    },
+  },
   {
     name: "completing-milestone → complete-milestone",
     match: async ({ state, mid, midTitle, basePath }) => {