gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/auto-start-bootstrap-await-3420.test.ts

@@ -0,0 +1,141 @@
+/**
+ * auto-start-bootstrap-await-3420.test.ts — Regression test for #3420.
+ *
+ * Bug: In bootstrapAutoSession, when state.phase === "pre-planning" and no
+ * context file exists, showSmartEntry is called to dispatch a discuss workflow.
+ * showSmartEntry calls dispatchWorkflow which calls pi.sendMessage() — a
+ * fire-and-forget call that returns immediately. The LLM discussion runs
+ * asynchronously in a separate turn.
+ *
+ * The bug: after showSmartEntry returns (before the LLM has run), the code
+ * immediately calls invalidateAllCaches() + deriveState() + checks postState.
+ * Since the discussion hasn't run yet, postState.phase is still "pre-planning"
+ * and the context check fails, producing the warning:
+ *   "Discussion completed but milestone context is still missing. Run /gsd to try again."
+ *
+ * The discussion never ran — the warning fires immediately.
+ *
+ * Fix: bootstrapAutoSession must return false (release lock) after showSmartEntry
+ * dispatches the workflow. The checkAutoStartAfterDiscuss callback in guided-flow.ts
+ * already handles re-entering auto-mode when the discussion completes.
+ *
+ * This test verifies the fix by asserting that the pre-planning !hasContext block
+ * does NOT contain a postState phase check after showSmartEntry — it must
+ * return false immediately to let the async dispatch complete.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const sourcePath = join(import.meta.dirname, "..", "auto-start.ts");
+const source = readFileSync(sourcePath, "utf-8");
+
+test("bootstrapAutoSession: pre-planning no-context path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the pre-planning block that handles the case where context is missing.
+  // This block dispatches showSmartEntry which is async (fire-and-forget via pi.sendMessage).
+  // After the dispatch, checking postState.phase immediately is premature — the
+  // LLM discussion hasn't run yet. The block should return false instead.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(
+    !!prePlanningNoContextBlock,
+    "auto-start.ts must have the pre-planning handler block before needs-discussion",
+  );
+
+  const block = prePlanningNoContextBlock![1];
+
+  // The block must call showSmartEntry when !hasContext
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "pre-planning !hasContext block must call showSmartEntry to dispatch the discuss workflow",
+  );
+
+  // FAILING ASSERTION (before fix): after showSmartEntry, the block must NOT
+  // immediately check postState.phase — that check fires before the LLM runs.
+  // Instead, it must return false (release lock) so the async dispatch can complete.
+  // The warning "Discussion completed but milestone context is still missing"
+  // fires prematurely when this postState check exists.
+  assert.ok(
+    !block.includes("Discussion completed but milestone context is still missing"),
+    "pre-planning !hasContext block must NOT check postState.phase immediately after showSmartEntry — " +
+    "the dispatch is async (pi.sendMessage is fire-and-forget) and the discussion hasn't run yet; " +
+    "return false instead so checkAutoStartAfterDiscuss can re-enter auto-mode after discussion completes (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: complete/no-milestone path does NOT check postState immediately after showSmartEntry (#3420)", () => {
+  // Find the complete/no-milestone block
+  const completeBlock = source.match(
+    /\/\/ No active work — start a new milestone via discuss flow\s*\n\s*if\s*\(!state\.activeMilestone\s*\|\|\s*state\.phase\s*===\s*"complete"\s*\)([\s\S]*?)\/\/ Active milestone exists but has no roadmap/,
+  );
+  assert.ok(
+    !!completeBlock,
+    "auto-start.ts must have the complete/no-milestone handler block",
+  );
+
+  const block = completeBlock![1];
+
+  // The block must call showSmartEntry
+  assert.ok(
+    block.includes("showSmartEntry"),
+    "complete/no-milestone block must call showSmartEntry",
+  );
+
+  // After showSmartEntry dispatches, checking postState.phase is premature —
+  // the LLM hasn't had a turn yet. The block should return false.
+  // Specifically, the "no milestone context was written" warning fires too early.
+  assert.ok(
+    !block.includes("Discussion completed but no milestone context was written"),
+    "complete/no-milestone block must NOT check postState.phase immediately after showSmartEntry dispatch — " +
+    "return false instead so the async LLM turn can complete (#3420)",
+  );
+});
+
+test("bootstrapAutoSession: showSmartEntry in pre-planning path is followed by releaseLockAndReturn, not postState check (#3420)", () => {
+  // After the fix, the pre-planning !hasContext branch should call showSmartEntry
+  // and then immediately return releaseLockAndReturn() — not check postState.
+  const prePlanningNoContextBlock = source.match(
+    /\/\/ Active milestone exists but has no roadmap\s*\n\s*if\s*\(\s*state\.phase\s*===\s*"pre-planning"\s*\)([\s\S]*?)\/\/ Active milestone has CONTEXT-DRAFT/,
+  );
+  assert.ok(!!prePlanningNoContextBlock, "pre-planning handler block found");
+
+  const block = prePlanningNoContextBlock![1];
+
+  // After the fix, the !hasContext branch ends with releaseLockAndReturn
+  assert.ok(
+    block.includes("releaseLockAndReturn"),
+    "pre-planning !hasContext block must call releaseLockAndReturn() after showSmartEntry dispatch (#3420)",
+  );
+
+  // The showSmartEntry call must appear before releaseLockAndReturn
+  const showSmartEntryIdx = block.indexOf("showSmartEntry");
+  const releaseLockIdx = block.indexOf("releaseLockAndReturn");
+  assert.ok(
+    showSmartEntryIdx > -1 && releaseLockIdx > -1,
+    "both showSmartEntry and releaseLockAndReturn must appear in the block",
+  );
+  assert.ok(
+    showSmartEntryIdx < releaseLockIdx,
+    "showSmartEntry must appear before releaseLockAndReturn in pre-planning !hasContext block",
+  );
+
+  // There must be NO invalidateAllCaches between showSmartEntry and releaseLockAndReturn
+  // (invalidateAllCaches + deriveState after showSmartEntry is the buggy premature check)
+  const afterShowSmartEntry = block.substring(showSmartEntryIdx);
+  const cacheInvalidateIdx = afterShowSmartEntry.indexOf("invalidateAllCaches");
+  const releaseFromShowIdx = afterShowSmartEntry.indexOf("releaseLockAndReturn");
+
+  // If invalidateAllCaches appears, it must appear AFTER releaseLockAndReturn
+  // (which is impossible since releaseLockAndReturn returns) — so invalidateAllCaches
+  // must not appear at all between showSmartEntry and the end of the !hasContext block.
+  if (cacheInvalidateIdx !== -1) {
+    assert.ok(
+      cacheInvalidateIdx > releaseFromShowIdx,
+      "invalidateAllCaches must NOT appear between showSmartEntry and releaseLockAndReturn — " +
+      "this is the premature postState check that causes #3420",
+    );
+  }
+});

package/src/resources/extensions/gsd/tests/auto-start-clean-runtime-db-gated.test.ts

@@ -0,0 +1,63 @@
+// GSD-2 auto-start regression test: cleanStaleRuntimeUnits is DB-gated (#4663)
+//
+// Source-level structural check that the stale-runtime-cleanup predicate in
+// auto-start.ts consults DB status when available instead of treating a
+// SUMMARY-file on disk as proof of milestone completion. Pairs with #4658 /
+// PR #4660 fix in auto-dispatch + auto-recovery.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "auto-start.ts");
+
+describe("auto-start cleanStaleRuntimeUnits DB gating (#4663)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("imports isClosedStatus for DB-status check", () => {
+    assert.match(
+      source,
+      /import\s*\{\s*isClosedStatus\s*\}\s*from\s*["']\.\/status-guards/,
+    );
+  });
+
+  test("cleanStaleRuntimeUnits is called after openProjectDbIfPresent", () => {
+    const openDbIdx = source.indexOf("await openProjectDbIfPresent(base)");
+    assert.ok(openDbIdx > -1, "openProjectDbIfPresent should be called in auto-start");
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(", openDbIdx);
+    assert.ok(
+      cleanIdx > -1,
+      "cleanStaleRuntimeUnits must run AFTER openProjectDbIfPresent so predicate can consult DB",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate consults DB status when available", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    assert.match(
+      snippet,
+      /isDbAvailable\(\)/,
+      "predicate must branch on DB availability",
+    );
+    assert.match(
+      snippet,
+      /isClosedStatus\(/,
+      "predicate must check DB status via isClosedStatus",
+    );
+  });
+
+  test("cleanStaleRuntimeUnits predicate still falls back to SUMMARY-file when DB unavailable", () => {
+    const cleanIdx = source.indexOf("cleanStaleRuntimeUnits(");
+    assert.ok(cleanIdx > -1);
+    const snippet = source.slice(cleanIdx, cleanIdx + 600);
+    assert.match(
+      snippet,
+      /resolveMilestoneFile\(base,\s*mid,\s*["']SUMMARY["']\)/,
+      "legacy FS-fallback branch should still use SUMMARY file presence",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts

@@ -52,9 +52,7 @@ test("bootstrapAutoSession checks manual session override before preferences", (
     "manual override and preference fallback must be resolved before building startModelSnapshot",
   );
 
-  // The validated preferred model must still appear as one of the snapshot
-  // sources so PREFERENCES.md continues to win over a stale settings.json
-  // default for built-in providers.
+  // Preferred model should still be part of fallback resolution.
   const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 400);
   assert.ok(
     snapshotBlock.includes("validatedPreferredModel") || snapshotBlock.includes("preferredModel"),
@@ -62,6 +60,22 @@ test("bootstrapAutoSession checks manual session override before preferences", (
   );
 });
 
+test("bootstrapAutoSession prioritizes current session model over PREFERENCES.md default", () => {
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
+  assert.ok(snapshotIdx > -1, "auto-start.ts should build startModelSnapshot");
+
+  const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 500);
+  const currentIdx = snapshotBlock.indexOf("currentSessionModel");
+  const preferredIdx = snapshotBlock.indexOf("validatedPreferredModel");
+
+  assert.ok(currentIdx > -1, "startModelSnapshot should include currentSessionModel");
+  assert.ok(preferredIdx > -1, "startModelSnapshot should include validatedPreferredModel");
+  assert.ok(
+    currentIdx < preferredIdx,
+    "startModelSnapshot should prefer currentSessionModel before validatedPreferredModel",
+  );
+});
+
 test("bootstrapAutoSession prefers session model over PREFERENCES.md when provider is custom (#4122)", () => {
   // Custom providers (Ollama, vLLM, OpenAI-compatible proxies) live in
   // ~/.gsd/agent/models.json, not PREFERENCES.md.  When the user picks one
@@ -111,3 +125,19 @@ test("bootstrapAutoSession validates preferred model against live registry auth
   const warningIdx = source.indexOf("is not configured; falling back to session default");
   assert.ok(warningIdx > -1, "auto-start.ts should warn when preferred model is unconfigured");
 });
+
+test("bootstrapAutoSession snapshots and persists thinking level for auto-mode lifecycle", () => {
+  const captureIdx = source.indexOf("const startThinkingSnapshot = pi.getThinkingLevel()");
+  assert.ok(captureIdx > -1, "auto-start.ts should snapshot thinking level at bootstrap start");
+
+  const originalThinkingIdx = source.indexOf("s.originalThinkingLevel = startThinkingSnapshot ?? null");
+  assert.ok(originalThinkingIdx > -1, "auto-start.ts should store originalThinkingLevel from snapshot");
+
+  const autoThinkingIdx = source.indexOf("s.autoModeStartThinkingLevel = startThinkingSnapshot ?? null");
+  assert.ok(autoThinkingIdx > -1, "auto-start.ts should store autoModeStartThinkingLevel from snapshot");
+
+  assert.ok(
+    captureIdx < originalThinkingIdx && captureIdx < autoThinkingIdx,
+    "thinking snapshot must be captured before session state assignment",
+  );
+});

package/src/resources/extensions/gsd/tests/auto-thinking-restore.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8");
+const phasesSrc = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
+
+test("stopAuto restores original thinking level", () => {
+  assert.ok(
+    autoSrc.includes("if (pi && s.originalThinkingLevel)"),
+    "auto.ts should conditionally restore original thinking level in stopAuto",
+  );
+  assert.ok(
+    autoSrc.includes("pi.setThinkingLevel(s.originalThinkingLevel)"),
+    "auto.ts should call pi.setThinkingLevel with originalThinkingLevel",
+  );
+});
+
+test("runUnitPhase threads captured thinking level into selectAndApplyModel", () => {
+  const callIdx = phasesSrc.indexOf("deps.selectAndApplyModel(");
+  assert.ok(callIdx > -1, "phases.ts should call selectAndApplyModel");
+  const callBlock = phasesSrc.slice(callIdx, callIdx + 600);
+  assert.ok(
+    callBlock.includes("s.autoModeStartThinkingLevel"),
+    "runUnitPhase should pass autoModeStartThinkingLevel to selectAndApplyModel",
+  );
+});
+
+test("hook model override preserves captured thinking level", () => {
+  const hookIdx = phasesSrc.indexOf("const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
+  assert.ok(hookIdx > -1, "phases.ts should include hook model override handling");
+  const hookBlock = phasesSrc.slice(hookIdx, hookIdx + 600);
+  assert.ok(
+    hookBlock.includes("pi.setThinkingLevel(s.autoModeStartThinkingLevel)"),
+    "hook model override should re-apply captured thinking level after setModel",
+  );
+});

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -144,3 +144,26 @@ describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", (
     );
   });
 });
+
+describe("#4365: tool_execution_start hook must pass toolName to markToolStart", () => {
+  test("tool_execution_start handler passes event.toolName to markToolStart", () => {
+    // The tool_execution_start handler must forward toolName so that
+    // hasInteractiveToolInFlight() can correctly identify ask_user_questions
+    // and prevent the idle watchdog from firing during interactive tool calls.
+    const startMarker = 'pi.on("tool_execution_start", async (event) => {';
+    const endMarker = 'pi.on("tool_execution_end", async (event) => {';
+    const toolExecutionStartSection = registerHooksSrc.slice(
+      registerHooksSrc.indexOf(startMarker),
+      registerHooksSrc.indexOf(endMarker),
+    );
+
+    assert.ok(
+      toolExecutionStartSection.length > 0,
+      "Could not locate tool_execution_start handler section",
+    );
+    assert.ok(
+      toolExecutionStartSection.includes("markToolStart(event.toolCallId, event.toolName)"),
+      "tool_execution_start handler must pass event.toolName to markToolStart so hasInteractiveToolInFlight() works correctly",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/blocked-models.test.ts

@@ -0,0 +1,98 @@
+// GSD — Tests for persistent blocked-models store (issue #4513)
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  blockModel,
+  isModelBlocked,
+  loadBlockedModels,
+} from "../blocked-models.ts";
+
+function mkBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-blocked-models-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+test("blocked-models: round-trip write and read", () => {
+  const base = mkBase();
+  try {
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), false);
+    blockModel(base, "openai-codex", "gpt-5.1-codex-max", "not supported for ChatGPT account");
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), true);
+
+    const entries = loadBlockedModels(base);
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].provider, "openai-codex");
+    assert.equal(entries[0].id, "gpt-5.1-codex-max");
+    assert.ok(entries[0].blockedAt > 0);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: case-insensitive lookup", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "OpenAI-Codex", "GPT-5.1-Codex-Max", "reason");
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), true);
+    assert.equal(isModelBlocked(base, "OPENAI-CODEX", "GPT-5.1-CODEX-MAX"), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: dedupes repeated blocks", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "first");
+    blockModel(base, "openai-codex", "gpt-5", "second");
+    blockModel(base, "openai-codex", "gpt-5", "third");
+    assert.equal(loadBlockedModels(base).length, 1);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: corrupted JSON recovers to empty", () => {
+  const base = mkBase();
+  try {
+    const path = join(base, ".gsd", "runtime", "blocked-models.json");
+    mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+    writeFileSync(path, "{not valid json", "utf-8");
+
+    assert.equal(loadBlockedModels(base).length, 0);
+    assert.equal(isModelBlocked(base, "any", "model"), false);
+
+    // A subsequent write should still succeed (overwrites the corrupt file).
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.equal(loadBlockedModels(base).length, 1);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: returns false for missing provider or id", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.equal(isModelBlocked(base, undefined, "gpt-5"), false);
+    assert.equal(isModelBlocked(base, "openai-codex", undefined), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: file created under .gsd/runtime/", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.ok(existsSync(join(base, ".gsd", "runtime", "blocked-models.json")));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/bundled-skill-triggers.test.ts

@@ -0,0 +1,54 @@
+// GSD-2 — BUNDLED_SKILL_TRIGGERS regression test
+//
+// Guards the skill-trigger table in system-context.ts against accidental
+// regression. Every entry must have a non-empty trigger + skill, and the
+// skills added in PR #4505 must remain present.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { BUNDLED_SKILL_TRIGGERS } from '../bootstrap/system-context.ts';
+
+test('BUNDLED_SKILL_TRIGGERS: every entry has a non-empty trigger and skill', () => {
+  assert.ok(BUNDLED_SKILL_TRIGGERS.length > 0, 'table should not be empty');
+  for (const { trigger, skill } of BUNDLED_SKILL_TRIGGERS) {
+    assert.ok(trigger && trigger.trim().length > 0, `trigger missing for skill="${skill}"`);
+    assert.ok(skill && skill.trim().length > 0, `skill missing for trigger="${trigger}"`);
+  }
+});
+
+test('BUNDLED_SKILL_TRIGGERS: PR #4505 bundled skills are present', () => {
+  const expected = [
+    'review',
+    'test',
+    'lint',
+    'make-interfaces-feel-better',
+    'accessibility',
+    'grill-me',
+    'design-an-interface',
+    'tdd',
+    'write-milestone-brief',
+    'decompose-into-slices',
+    'spike-wrap-up',
+    'verify-before-complete',
+    'create-mcp-server',
+    'write-docs',
+    'forensics',
+    'handoff',
+    'security-review',
+    'api-design',
+    'dependency-upgrade',
+    'observability',
+  ];
+  const registered = new Set(BUNDLED_SKILL_TRIGGERS.map(e => e.skill));
+  for (const skill of expected) {
+    assert.ok(registered.has(skill), `expected bundled skill "${skill}" to be registered`);
+  }
+});
+
+test('BUNDLED_SKILL_TRIGGERS: skill ids are unique', () => {
+  const seen = new Set<string>();
+  for (const { skill } of BUNDLED_SKILL_TRIGGERS) {
+    assert.ok(!seen.has(skill), `duplicate skill registration: ${skill}`);
+    seen.add(skill);
+  }
+});

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -0,0 +1,186 @@
+/**
+ * clean-root-preflight.test.ts — Regression tests for #2909.
+ *
+ * Tests that preflightCleanRoot warns + stashes on dirty trees,
+ * is a no-op on clean trees, and that postflightPopStash restores
+ * stashed changes after a merge.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { preflightCleanRoot, postflightPopStash } from "../clean-root-preflight.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-preflight-test-")));
+  run("git init", dir);
+  run("git config user.email test@example.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+// ── Clean tree: fast-path returns immediately without stashing ─────────────
+
+test("preflightCleanRoot — clean tree returns stashPushed=false and emits no notifications", () => {
+  const repo = createTempRepo();
+  try {
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M001", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, false, "stashPushed must be false for clean tree");
+    assert.equal(result.summary, "", "summary must be empty for clean tree");
+    assert.equal(notifications.length, 0, "no notifications on clean tree");
+
+    // Verify no stash was created
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "no stash entry on clean tree");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Dirty tree: warns, stashes, returns stashPushed=true ──────────────────
+
+test("preflightCleanRoot — dirty tree warns user and auto-stashes", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty an existing tracked file
+    writeFileSync(join(repo, "README.md"), "# locally modified\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M002", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true when tree was dirty");
+    assert.ok(result.summary.length > 0, "summary must be non-empty when stash was pushed");
+
+    // A warning notification must have been emitted before stashing
+    assert.ok(
+      notifications.some(n => n.level === "warning" && n.msg.includes("M002")),
+      "warning notification must mention the milestone ID",
+    );
+
+    // Working tree must now be clean (stash pushed)
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+
+    // The stash entry must exist
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash"), "stash entry must be named gsd-preflight-stash");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Untracked files are also stashed ─────────────────────────────────────
+
+test("preflightCleanRoot — untracked file triggers stash with --include-untracked", () => {
+  const repo = createTempRepo();
+  try {
+    // Add an untracked file
+    writeFileSync(join(repo, "untracked.ts"), "export const x = 1;\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M003", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true for untracked file");
+
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── postflightPopStash: restores stashed changes ──────────────────────────
+
+test("postflightPopStash — restores stashed changes and emits info notification", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty the working tree
+    writeFileSync(join(repo, "README.md"), "# stash me\n");
+
+    const preNotifications: Array<{ msg: string; level: string }> = [];
+    const preflight = preflightCleanRoot(repo, "M004", (msg, level) => {
+      preNotifications.push({ msg, level });
+    });
+    assert.equal(preflight.stashPushed, true, "preflight must have stashed");
+
+    // Simulate the merge (just a no-op commit here)
+    writeFileSync(join(repo, "merged.ts"), "export const merged = true;\n");
+    run("git add .", repo);
+    run('git commit -m "simulate merge"', repo);
+
+    const postNotifications: Array<{ msg: string; level: string }> = [];
+    postflightPopStash(repo, "M004", (msg, level) => {
+      postNotifications.push({ msg, level });
+    });
+
+    // The stashed README.md change must be restored
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# stash me\n", "stashed file must be restored");
+
+    // An info notification must have been emitted
+    assert.ok(
+      postNotifications.some(n => n.level === "info" && n.msg.includes("M004")),
+      "info notification must mention milestone ID after pop",
+    );
+
+    // Stash list must be empty
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "stash list must be empty after pop");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Round-trip: preflight + merge + postflight preserves changes ──────────
+
+test("preflight + merge + postflight round-trip preserves uncommitted changes", () => {
+  const repo = createTempRepo();
+  try {
+    const originalContent = "# my local work\n";
+    writeFileSync(join(repo, "README.md"), originalContent);
+
+    // Preflight: stash
+    const preflight = preflightCleanRoot(repo, "M005", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    // Merge: introduce a new file (no overlap with README.md)
+    writeFileSync(join(repo, "feature.ts"), "export const feature = true;\n");
+    run("git add feature.ts", repo);
+    run('git commit -m "feat: add feature"', repo);
+
+    // Postflight: pop stash
+    postflightPopStash(repo, "M005", () => {});
+
+    // README.md must still have our local content
+    const restored = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(restored.replace(/\r\n/g, "\n"), originalContent, "local changes must survive merge");
+
+    // feature.ts must also exist (the merge commit landed)
+    const featureContent = readFileSync(join(repo, "feature.ts"), "utf-8");
+    assert.ok(featureContent.includes("feature"), "merged feature must be present");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});