gsd-pi 2.10.12 → 2.12.0

package/dist/resources/extensions/gsd/tests/collect-from-manifest.test.ts

@@ -0,0 +1,469 @@
+/**
+ * Tests for S02 Enhanced Collection TUI functions:
+ * - collectSecretsFromManifest() orchestrator categorization and flow
+ * - showSecretsSummary() render output
+ * - collectOneSecret() guidance rendering
+ *
+ * These tests import functions that don't exist yet (T02/T03 will build them).
+ * They are expected to fail until implementation is complete.
+ *
+ * Uses dynamic imports so individual tests fail with clear messages
+ * instead of the entire file crashing at import time.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { SecretsManifest, SecretsManifestEntry } from "../types.ts";
+
+// Dynamic imports for files.ts functions to avoid cascading failure
+// when paths.js isn't available (files.ts statically imports paths.js)
+async function loadFilesExports(): Promise<{
+	formatSecretsManifest: (m: SecretsManifest) => string;
+	parseSecretsManifest: (content: string) => SecretsManifest;
+}> {
+	const mod = await import("../files.ts");
+	return {
+		formatSecretsManifest: mod.formatSecretsManifest,
+		parseSecretsManifest: mod.parseSecretsManifest,
+	};
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempDir(prefix: string): string {
+	const dir = join(tmpdir(), `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function makeManifest(entries: Partial<SecretsManifestEntry>[]): SecretsManifest {
+	return {
+		milestone: "M001",
+		generatedAt: "2026-03-12T00:00:00Z",
+		entries: entries.map((e) => ({
+			key: e.key ?? "TEST_KEY",
+			service: e.service ?? "TestService",
+			dashboardUrl: e.dashboardUrl ?? "",
+			guidance: e.guidance ?? [],
+			formatHint: e.formatHint ?? "",
+			status: e.status ?? "pending",
+			destination: e.destination ?? "dotenv",
+		})),
+	};
+}
+
+async function writeManifestFile(dir: string, manifest: SecretsManifest): Promise<string> {
+	const { formatSecretsManifest } = await loadFilesExports();
+	const milestoneDir = join(dir, ".gsd", "milestones", "M001");
+	mkdirSync(milestoneDir, { recursive: true });
+	const filePath = join(milestoneDir, "M001-SECRETS.md");
+	writeFileSync(filePath, formatSecretsManifest(manifest));
+	return filePath;
+}
+
+async function loadOrchestrator(): Promise<{
+	collectSecretsFromManifest: Function;
+	showSecretsSummary: Function;
+}> {
+	const mod = await import("../../get-secrets-from-user.ts");
+	if (typeof mod.collectSecretsFromManifest !== "function") {
+		throw new Error("collectSecretsFromManifest is not exported from get-secrets-from-user.ts — T03 will implement this");
+	}
+	if (typeof mod.showSecretsSummary !== "function") {
+		throw new Error("showSecretsSummary is not exported from get-secrets-from-user.ts — T03 will implement this");
+	}
+	return {
+		collectSecretsFromManifest: mod.collectSecretsFromManifest,
+		showSecretsSummary: mod.showSecretsSummary,
+	};
+}
+
+async function loadGuidanceExport(): Promise<{ collectOneSecretWithGuidance: Function }> {
+	const mod = await import("../../get-secrets-from-user.ts");
+	if (typeof mod.collectOneSecretWithGuidance !== "function") {
+		throw new Error("collectOneSecretWithGuidance is not exported from get-secrets-from-user.ts — T02 will implement this");
+	}
+	return { collectOneSecretWithGuidance: mod.collectOneSecretWithGuidance };
+}
+
+// ─── collectSecretsFromManifest: categorization ───────────────────────────────
+
+test("collectSecretsFromManifest: categorizes entries — pending keys need collection, existing keys are skipped", async () => {
+	const { collectSecretsFromManifest } = await loadOrchestrator();
+
+	const tmp = makeTempDir("manifest-collect");
+	const savedA = process.env.EXISTING_KEY_A;
+	try {
+		process.env.EXISTING_KEY_A = "already-set";
+
+		const manifest = makeManifest([
+			{ key: "EXISTING_KEY_A", status: "pending" },
+			{ key: "PENDING_KEY_B", status: "pending", guidance: ["Step 1: Go to dashboard", "Step 2: Click create key"] },
+			{ key: "SKIPPED_KEY_C", status: "skipped" },
+		]);
+		await writeManifestFile(tmp, manifest);
+
+		let callIndex = 0;
+		const mockCtx = {
+			cwd: tmp,
+			hasUI: true,
+			ui: {
+				custom: async (_factory: any) => {
+					callIndex++;
+					if (callIndex <= 1) return null; // summary screen dismiss
+					return "mock-secret-value"; // collect pending key
+				},
+			},
+		};
+
+		const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any);
+
+		// EXISTING_KEY_A should be in existingSkipped (it's in process.env)
+		assert.ok(result.existingSkipped?.includes("EXISTING_KEY_A"),
+			"EXISTING_KEY_A should be in existingSkipped");
+
+		// PENDING_KEY_B should have been collected (applied)
+		assert.ok(result.applied.includes("PENDING_KEY_B"),
+			"PENDING_KEY_B should be in applied");
+
+		// SKIPPED_KEY_C should remain skipped
+		assert.ok(result.skipped.includes("SKIPPED_KEY_C"),
+			"SKIPPED_KEY_C should be in skipped");
+	} finally {
+		delete process.env.EXISTING_KEY_A;
+		if (savedA !== undefined) process.env.EXISTING_KEY_A = savedA;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("collectSecretsFromManifest: existing keys are excluded from the collection list — not prompted", async () => {
+	const { collectSecretsFromManifest } = await loadOrchestrator();
+
+	const tmp = makeTempDir("manifest-collect-skip");
+	const savedA = process.env.ALREADY_SET_KEY;
+	try {
+		process.env.ALREADY_SET_KEY = "present";
+
+		const manifest = makeManifest([
+			{ key: "ALREADY_SET_KEY", status: "pending" },
+			{ key: "NEEDS_COLLECTION", status: "pending" },
+		]);
+		await writeManifestFile(tmp, manifest);
+
+		const collectedKeyNames: string[] = [];
+		let summaryShown = false;
+		const mockCtx = {
+			cwd: tmp,
+			hasUI: true,
+			ui: {
+				custom: async (factory: any) => {
+					// Intercept the factory to check what key is being collected
+					if (!summaryShown) {
+						summaryShown = true;
+						return null; // dismiss summary
+					}
+					collectedKeyNames.push("prompted");
+					return "mock-value";
+				},
+			},
+		};
+
+		const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any);
+
+		// ALREADY_SET_KEY should not have been prompted — only NEEDS_COLLECTION should
+		assert.ok(!result.applied.includes("ALREADY_SET_KEY"),
+			"ALREADY_SET_KEY should not be in applied (it was auto-skipped)");
+		assert.ok(result.existingSkipped?.includes("ALREADY_SET_KEY"),
+			"ALREADY_SET_KEY should be in existingSkipped");
+	} finally {
+		delete process.env.ALREADY_SET_KEY;
+		if (savedA !== undefined) process.env.ALREADY_SET_KEY = savedA;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+test("collectSecretsFromManifest: manifest statuses are updated after collection", async () => {
+	const { collectSecretsFromManifest } = await loadOrchestrator();
+
+	const tmp = makeTempDir("manifest-update");
+	try {
+		const manifest = makeManifest([
+			{ key: "KEY_TO_COLLECT", status: "pending" },
+			{ key: "KEY_TO_SKIP", status: "pending" },
+		]);
+		const manifestPath = await writeManifestFile(tmp, manifest);
+
+		let callIndex = 0;
+		const mockCtx = {
+			cwd: tmp,
+			hasUI: true,
+			ui: {
+				custom: async (_factory: any) => {
+					callIndex++;
+					if (callIndex <= 1) return null; // summary screen dismiss
+					if (callIndex === 2) return "secret-value"; // KEY_TO_COLLECT
+					return null; // KEY_TO_SKIP — user skips
+				},
+			},
+		};
+
+		await collectSecretsFromManifest(tmp, "M001", mockCtx as any);
+
+		// Read back the manifest file and verify statuses were updated
+		const { parseSecretsManifest } = await loadFilesExports();
+		const updatedContent = readFileSync(manifestPath, "utf8");
+		const updatedManifest = parseSecretsManifest(updatedContent);
+
+		const keyToCollect = updatedManifest.entries.find(e => e.key === "KEY_TO_COLLECT");
+		const keyToSkip = updatedManifest.entries.find(e => e.key === "KEY_TO_SKIP");
+
+		assert.equal(keyToCollect?.status, "collected",
+			"KEY_TO_COLLECT should have status 'collected' after providing a value");
+		assert.equal(keyToSkip?.status, "skipped",
+			"KEY_TO_SKIP should have status 'skipped' after user skipped it");
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});
+
+// ─── showSecretsSummary: render output ────────────────────────────────────────
+
+test("showSecretsSummary: produces lines with correct status glyphs for each entry status", async () => {
+	const { showSecretsSummary } = await loadOrchestrator();
+
+	const entries: SecretsManifestEntry[] = [
+		{ key: "PENDING_KEY", service: "Svc", dashboardUrl: "", guidance: [], formatHint: "", status: "pending", destination: "dotenv" },
+		{ key: "COLLECTED_KEY", service: "Svc", dashboardUrl: "", guidance: [], formatHint: "", status: "collected", destination: "dotenv" },
+		{ key: "SKIPPED_KEY", service: "Svc", dashboardUrl: "", guidance: [], formatHint: "", status: "skipped", destination: "dotenv" },
+	];
+
+	// showSecretsSummary renders a ctx.ui.custom screen. We capture the render output.
+	let renderFn: ((width: number) => string[]) | undefined;
+	const mockCtx = {
+		hasUI: true,
+		ui: {
+			custom: async (factory: any) => {
+				const mockTheme = {
+					fg: (_color: string, text: string) => text,
+					bold: (text: string) => text,
+				};
+				const mockTui = { requestRender: () => {}, terminal: { rows: 24, columns: 80 } };
+				const component = factory(mockTui, mockTheme, {}, () => {});
+				renderFn = component.render;
+				// Simulate immediate dismiss
+				component.handleInput("\x1b"); // escape
+			},
+		},
+	};
+
+	await showSecretsSummary(mockCtx as any, entries, []);
+
+	assert.ok(renderFn, "render function should have been captured from factory");
+	const lines = renderFn!(80);
+
+	// Verify each key appears in the output
+	const output = lines.join("\n");
+	assert.ok(output.includes("PENDING_KEY"), "should include PENDING_KEY");
+	assert.ok(output.includes("COLLECTED_KEY"), "should include COLLECTED_KEY");
+	assert.ok(output.includes("SKIPPED_KEY"), "should include SKIPPED_KEY");
+
+	// Verify we have at least one line per entry plus header/footer
+	assert.ok(lines.length >= 5, `should have at least 5 lines (got ${lines.length})`);
+});
+
+test("showSecretsSummary: existing keys shown with distinct status indicator", async () => {
+	const { showSecretsSummary } = await loadOrchestrator();
+
+	const entries: SecretsManifestEntry[] = [
+		{ key: "NEW_KEY", service: "Svc", dashboardUrl: "", guidance: [], formatHint: "", status: "pending", destination: "dotenv" },
+		{ key: "OLD_KEY", service: "Svc", dashboardUrl: "", guidance: [], formatHint: "", status: "collected", destination: "dotenv" },
+	];
+	const existingKeys = ["OLD_KEY"];
+
+	let renderFn: ((width: number) => string[]) | undefined;
+	const mockCtx = {
+		hasUI: true,
+		ui: {
+			custom: async (factory: any) => {
+				const mockTheme = {
+					fg: (_color: string, text: string) => text,
+					bold: (text: string) => text,
+				};
+				const mockTui = { requestRender: () => {}, terminal: { rows: 24, columns: 80 } };
+				const component = factory(mockTui, mockTheme, {}, () => {});
+				renderFn = component.render;
+				component.handleInput("\x1b");
+			},
+		},
+	};
+
+	await showSecretsSummary(mockCtx as any, entries, existingKeys);
+
+	assert.ok(renderFn, "render function should have been captured");
+	const lines = renderFn!(80);
+	const output = lines.join("\n");
+
+	assert.ok(output.includes("NEW_KEY"), "should include NEW_KEY");
+	assert.ok(output.includes("OLD_KEY"), "should include OLD_KEY");
+});
+
+// ─── collectOneSecret: guidance rendering ─────────────────────────────────────
+
+test("collectOneSecret: guidance lines appear in render output when guidance is provided", async () => {
+	const { collectOneSecretWithGuidance } = await loadGuidanceExport();
+
+	const guidanceSteps = [
+		"Navigate to https://platform.openai.com/api-keys",
+		"Click 'Create new secret key'",
+		"Copy the key value",
+	];
+
+	// Use the exported test helper to capture render output with guidance
+	let renderFn: ((width: number) => string[]) | undefined;
+	const mockCtx = {
+		hasUI: true,
+		ui: {
+			custom: async (factory: any) => {
+				const mockTheme = {
+					fg: (_color: string, text: string) => text,
+					bold: (text: string) => text,
+				};
+				const mockTui = { requestRender: () => {}, terminal: { rows: 24, columns: 80 } };
+				const component = factory(mockTui, mockTheme, {}, () => {});
+				renderFn = component.render;
+				component.handleInput("\x1b"); // escape to dismiss
+			},
+		},
+	};
+
+	await collectOneSecretWithGuidance(mockCtx, 0, 1, "OPENAI_API_KEY", "starts with sk-", guidanceSteps);
+
+	assert.ok(renderFn, "render function should have been captured");
+	const lines = renderFn!(80);
+	const output = lines.join("\n");
+
+	// Verify guidance steps appear in the output
+	assert.ok(output.includes("Navigate to"), "should include first guidance step");
+	assert.ok(output.includes("Create new secret key"), "should include second guidance step");
+	assert.ok(output.includes("Copy the key value"), "should include third guidance step");
+});
+
+test("collectOneSecret: guidance lines wrap long URLs instead of truncating", async () => {
+	const { collectOneSecretWithGuidance } = await loadGuidanceExport();
+
+	const longGuidance = [
+		"Navigate to https://platform.openai.com/account/api-keys and click 'Create new secret key'",
+	];
+
+	let renderFn: ((width: number) => string[]) | undefined;
+	const mockCtx = {
+		hasUI: true,
+		ui: {
+			custom: async (factory: any) => {
+				const mockTheme = {
+					fg: (_color: string, text: string) => text,
+					bold: (text: string) => text,
+				};
+				const mockTui = { requestRender: () => {}, terminal: { rows: 24, columns: 80 } };
+				const component = factory(mockTui, mockTheme, {}, () => {});
+				renderFn = component.render;
+				component.handleInput("\x1b");
+			},
+		},
+	};
+
+	await collectOneSecretWithGuidance(mockCtx, 0, 1, "TEST_KEY", undefined, longGuidance);
+
+	assert.ok(renderFn, "render function should have been captured");
+	// Render at narrow width to force wrapping
+	const lines = renderFn!(50);
+	const output = lines.join("\n");
+
+	// The full URL should be present (wrapped, not truncated)
+	assert.ok(output.includes("platform.openai.com"), "URL should not be truncated");
+	assert.ok(output.includes("Create new secret key"), "text after URL should not be truncated");
+});
+
+test("collectOneSecret: no guidance provided — render output has no guidance section", async () => {
+	const { collectOneSecretWithGuidance } = await loadGuidanceExport();
+
+	let renderFn: ((width: number) => string[]) | undefined;
+	const mockCtx = {
+		hasUI: true,
+		ui: {
+			custom: async (factory: any) => {
+				const mockTheme = {
+					fg: (_color: string, text: string) => text,
+					bold: (text: string) => text,
+				};
+				const mockTui = { requestRender: () => {}, terminal: { rows: 24, columns: 80 } };
+				const component = factory(mockTui, mockTheme, {}, () => {});
+				renderFn = component.render;
+				component.handleInput("\x1b");
+			},
+		},
+	};
+
+	// Call without guidance (undefined)
+	await collectOneSecretWithGuidance(mockCtx, 0, 1, "SOME_KEY", "hint text", undefined);
+
+	assert.ok(renderFn, "render function should have been captured");
+	const lines = renderFn!(80);
+	const output = lines.join("\n");
+
+	// Should include the key name and hint but no numbered guidance steps
+	assert.ok(output.includes("SOME_KEY"), "should include key name");
+	assert.ok(output.includes("hint text"), "should include hint");
+	// Should NOT have numbered step indicators (1., 2., etc.) for guidance
+	assert.ok(!output.match(/^\s*1\.\s/m), "should not have numbered guidance steps when no guidance provided");
+});
+
+// ─── collectSecretsFromManifest: returns structured result ────────────────────
+
+test("collectSecretsFromManifest: returns result with applied, skipped, and existingSkipped arrays", async () => {
+	const { collectSecretsFromManifest } = await loadOrchestrator();
+
+	const tmp = makeTempDir("manifest-result");
+	const savedKey = process.env.RESULT_TEST_EXISTING;
+	try {
+		process.env.RESULT_TEST_EXISTING = "already-here";
+
+		const manifest = makeManifest([
+			{ key: "RESULT_TEST_EXISTING", status: "pending" },
+			{ key: "RESULT_TEST_NEW", status: "pending" },
+		]);
+		await writeManifestFile(tmp, manifest);
+
+		let callIndex = 0;
+		const mockCtx = {
+			cwd: tmp,
+			hasUI: true,
+			ui: {
+				custom: async (_factory: any) => {
+					callIndex++;
+					if (callIndex <= 1) return null; // summary dismiss
+					return "secret-value"; // collect the pending key
+				},
+			},
+		};
+
+		const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any);
+
+		// Verify result shape
+		assert.ok(Array.isArray(result.applied), "result should have applied array");
+		assert.ok(Array.isArray(result.skipped), "result should have skipped array");
+		assert.ok(Array.isArray(result.existingSkipped), "result should have existingSkipped array");
+
+		assert.ok(result.existingSkipped.includes("RESULT_TEST_EXISTING"),
+			"existing key should be in existingSkipped");
+		assert.ok(result.applied.includes("RESULT_TEST_NEW"),
+			"collected key should be in applied");
+	} finally {
+		delete process.env.RESULT_TEST_EXISTING;
+		if (savedKey !== undefined) process.env.RESULT_TEST_EXISTING = savedKey;
+		rmSync(tmp, { recursive: true, force: true });
+	}
+});

package/dist/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -0,0 +1,200 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { createTestContext } from './test-helpers.ts';
+import { clearPathCache } from '../paths.ts';
+import { invalidateStateCache } from '../state.ts';
+
+// loadPrompt reads from ~/.gsd/agent/extensions/gsd/prompts/ (main checkout).
+// In a worktree the file may not exist there yet, so we resolve prompts
+// relative to this test file's location (the worktree copy).
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const worktreePromptsDir = join(__dirname, "..", "prompts");
+
+const { assertEq, assertTrue, report } = createTestContext();
+/**
+ * Load a prompt template from the worktree prompts directory
+ * and apply variable substitution (mirrors loadPrompt logic).
+ */
+function loadPromptFromWorktree(name: string, vars: Record<string, string> = {}): string {
+  const path = join(worktreePromptsDir, `${name}.md`);
+  let content = readFileSync(path, "utf-8");
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+  return content.trim();
+}
+
+// ─── Fixture Helpers ───────────────────────────────────────────────────────
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-complete-ms-test-"));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function writeRoadmap(base: string, mid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-ROADMAP.md`), content);
+}
+
+function writeMilestoneSummary(base: string, mid: string, content: string): void {
+  const dir = join(base, ".gsd", "milestones", mid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
+}
+
+function cleanup(base: string): void {
+  rmSync(base, { recursive: true, force: true });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+
+  // ─── Prompt Template Loading ───────────────────────────────────────────
+  console.log("\n=== complete-milestone prompt template exists ===");
+  {
+    let result: string;
+    let threw = false;
+    try {
+      result = loadPromptFromWorktree("complete-milestone", {
+        milestoneId: "M001",
+        milestoneTitle: "Test Milestone",
+        roadmapPath: ".gsd/milestones/M001/M001-ROADMAP.md",
+        inlinedContext: "test context block",
+      });
+    } catch (err) {
+      threw = true;
+      result = "";
+      console.error(`  ERROR: loadPrompt threw: ${err}`);
+    }
+
+    assertTrue(!threw, "loadPrompt does not throw for complete-milestone");
+    assertTrue(typeof result === "string" && result.length > 0, "loadPrompt returns a non-empty string");
+  }
+
+  // ─── Variable Substitution ─────────────────────────────────────────────
+  console.log("\n=== prompt variable substitution ===");
+  {
+    const prompt = loadPromptFromWorktree("complete-milestone", {
+      milestoneId: "M001",
+      milestoneTitle: "Integration Feature",
+      roadmapPath: ".gsd/milestones/M001/M001-ROADMAP.md",
+      inlinedContext: "--- inlined slice summaries and context ---",
+    });
+
+    assertTrue(prompt.includes("M001"), "prompt contains milestoneId 'M001'");
+    assertTrue(prompt.includes("Integration Feature"), "prompt contains milestoneTitle");
+    assertTrue(prompt.includes(".gsd/milestones/M001/M001-ROADMAP.md"), "prompt contains roadmapPath");
+    assertTrue(prompt.includes("--- inlined slice summaries and context ---"), "prompt contains inlinedContext");
+    assertTrue(!prompt.includes("{{milestoneId}}"), "no un-substituted {{milestoneId}}");
+    assertTrue(!prompt.includes("{{milestoneTitle}}"), "no un-substituted {{milestoneTitle}}");
+    assertTrue(!prompt.includes("{{roadmapPath}}"), "no un-substituted {{roadmapPath}}");
+    assertTrue(!prompt.includes("{{inlinedContext}}"), "no un-substituted {{inlinedContext}}");
+  }
+
+  // ─── Prompt Content Integrity ──────────────────────────────────────────
+  console.log("\n=== prompt content integrity ===");
+  {
+    const prompt = loadPromptFromWorktree("complete-milestone", {
+      milestoneId: "M002",
+      milestoneTitle: "Completion Workflow",
+      roadmapPath: ".gsd/milestones/M002/M002-ROADMAP.md",
+      inlinedContext: "context",
+    });
+
+    assertTrue(prompt.includes("Complete Milestone"), "prompt contains 'Complete Milestone' heading");
+    assertTrue(prompt.includes("success criter") || prompt.includes("success criteria"), "prompt mentions success criteria verification");
+    assertTrue(prompt.includes("milestone-summary") || prompt.includes("milestoneSummary"), "prompt references milestone summary artifact");
+    assertTrue(prompt.includes("Milestone M002 complete"), "prompt contains completion sentinel for M002");
+  }
+
+  // ─── diagnoseExpectedArtifact behavior ─────────────────────────────────
+  // Since diagnoseExpectedArtifact is not exported from auto.ts, we test
+  // the same logic by reimplementing the switch case for complete-milestone
+  // and verifying against known path patterns.
+  console.log("\n=== diagnoseExpectedArtifact logic for complete-milestone ===");
+  {
+    // Import the path helpers used by diagnoseExpectedArtifact
+    const { relMilestoneFile } = await import("../paths.ts");
+
+    // Simulate diagnoseExpectedArtifact("complete-milestone", "M001", base) logic
+    const base = createFixtureBase();
+    try {
+      writeRoadmap(base, "M001", `# M001\n\n## Slices\n- [x] **S01: Done** \`risk:low\` \`depends:[]\`\n  > After this: done\n`);
+
+      const unitType = "complete-milestone";
+      const unitId = "M001";
+      const parts = unitId.split("/");
+      const mid = parts[0]!;
+
+      // This is the exact logic from diagnoseExpectedArtifact for "complete-milestone"
+      const result = `${relMilestoneFile(base, mid, "SUMMARY")} (milestone summary)`;
+
+      assertTrue(typeof result === "string", "diagnose returns a string");
+      assertTrue(result.includes("SUMMARY"), "diagnose result mentions SUMMARY");
+      assertTrue(result.includes("milestone"), "diagnose result mentions milestone");
+      assertTrue(result.includes("M001"), "diagnose result includes the milestone ID");
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  // ─── deriveState integration: completing-milestone dispatches correctly ─
+  console.log("\n=== deriveState completing-milestone integration ===");
+  {
+    const { deriveState, isMilestoneComplete, invalidateStateCache } = await import("../state.ts");
+    const { parseRoadmap } = await import("../files.ts");
+
+    const base = createFixtureBase();
+    try {
+      writeRoadmap(base, "M001", `# M001: Integration Test
+
+**Vision:** Test completing-milestone flow.
+
+## Slices
+
+- [x] **S01: Slice One** \`risk:low\` \`depends:[]\`
+  > After this: done.
+
+- [x] **S02: Slice Two** \`risk:low\` \`depends:[S01]\`
+  > After this: done.
+`);
+
+      // Verify isMilestoneComplete returns true
+      const { loadFile } = await import("../files.ts");
+      const roadmapPath = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
+      const roadmapContent = await loadFile(roadmapPath);
+      const roadmap = parseRoadmap(roadmapContent!);
+      assertTrue(isMilestoneComplete(roadmap), "isMilestoneComplete returns true when all slices are [x]");
+
+      // Verify deriveState returns completing-milestone phase
+      const state = await deriveState(base);
+      assertEq(state.phase, "completing-milestone", "deriveState returns completing-milestone when all slices done, no summary");
+      assertEq(state.activeMilestone?.id, "M001", "active milestone is M001");
+      assertEq(state.activeSlice, null, "no active slice in completing-milestone");
+
+      // Now add the summary and verify it transitions to complete
+      writeMilestoneSummary(base, "M001", "# M001 Summary\n\nDone.");
+      clearPathCache();
+      invalidateStateCache();
+      const stateAfter = await deriveState(base);
+      assertEq(stateAfter.phase, "complete", "deriveState returns complete after summary exists");
+      assertEq(stateAfter.registry[0]?.status, "complete", "registry shows complete status");
+    } finally {
+      cleanup(base);
+    }
+  }
+
+  report();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});