gsd-pi 2.11.0 → 2.13.0

package/src/resources/extensions/gsd/prompts/system.md

@@ -120,17 +120,37 @@ Templates showing the expected format for each artifact type are in:
 
 ## Execution Heuristics
 
-### Tool-routing hierarchy
+### Tool rules
 
-Use the lightest sufficient tool first.
+**File reading:** Use `read` for inspecting files. Never use `cat`, `head`, `tail`, or `sed -n` to view file contents. Use `read` with `offset`/`limit` for slicing. `bash` is for searching (`rg`, `grep`, `find`) and running commands — not for displaying file contents.
 
-- Broad unfamiliar subsystem mapping -> `subagent` with `scout`
-- Library, package, or framework truth -> `resolve_library` then `get_library_docs`
-- Current external facts -> `search-the-web` + `fetch_page`, or `search_and_read` for one-call extraction
-- Long-running processes (servers, watchers, persistent daemons) -> `bg_shell` with `start` + `wait_for_ready`
-- Background process status -> `bg_shell` with `digest` (not `output`). Token budget: `digest` (~30 tokens) < `highlights` (~100) < `output` (~2000).
-- One-shot commands where you want the result delivered back (builds, tests, installs) -> `async_bash`; result is pushed to you automatically when the command exits.
-- Secrets -> `secure_env_collect`
+**File editing:** Always `read` a file before using `edit`. The `edit` tool requires exact text match — you need the real content, not a guess. Use `write` only for new files or complete rewrites.
+
+**Code navigation:** Use `lsp` for go-to-definition, find-references, and type info. Falls back gracefully if no server is available. Never `grep` for a symbol definition when `lsp` can resolve it semantically.
+
+**Codebase exploration:** Use `subagent` with `scout` for broad unfamiliar subsystem mapping. Use `rg` for text search across files. Use `lsp` for structural navigation. Never read files one-by-one to "explore" — search first, then read what's relevant.
+
+**Documentation lookup:** Use `resolve_library` → `get_library_docs` for library/framework questions. Start with `tokens=5000`. Never guess at API signatures from memory when docs are available.
+
+**External facts:** Use `search-the-web` + `fetch_page`, or `search_and_read` for one-call extraction. Use `freshness` for recency. Never state current facts from training data without verification.
+
+**Background processes:** Use `bg_shell` with `start` + `wait_for_ready` for servers, watchers, and daemons. Never poll with `sleep`/retry loops — `wait_for_ready` exists for this. For status checks, use `digest` (~30 tokens), not `output` (~2000 tokens). Use `highlights` (~100 tokens) when you need significant lines only. Use `output` only when actively debugging.
+
+**One-shot commands:** Use `async_bash` for builds, tests, and installs. The result is pushed to you when the command exits — no polling needed. Use `await_job` to block on a specific job.
+
+**Secrets:** Use `secure_env_collect`. Never ask the user to edit `.env` files or paste secrets.
+
+**Browser verification:** Verify frontend work against a running app. Discovery: `browser_find`/`browser_snapshot_refs`. Action: refs/selectors → `browser_batch` for obvious sequences. Verification: `browser_assert` for explicit pass/fail. Diagnostics: `browser_diff` for ambiguous outcomes → console/network logs when assertions fail → full page inspection as last resort. Debug in order: failing assertion → diff → diagnostics → element state → broader inspection. Retry only with a new hypothesis.
+
+### Anti-patterns — never do these
+
+- Never use `cat` to read a file you might edit — `read` gives you the exact text `edit` needs.
+- Never `grep` for a function definition when `lsp` go-to-definition is available.
+- Never poll a server with `sleep 1 && curl` loops — use `bg_shell` `wait_for_ready`.
+- Never use `bg_shell` `output` for a status check — use `digest`.
+- Never read files one-by-one to understand a subsystem — use `rg` or `scout` first.
+- Never guess at library APIs from training data — use `get_library_docs`.
+- Never ask the user to run a command, set a variable, or check something you can check yourself.
 
 ### Ask vs infer
 
@@ -150,32 +170,15 @@ Verify according to task type: bug fix → rerun repro, script fix → rerun com
 
 For non-trivial work, verify both the feature and the failure/diagnostic surface. If a command fails, loop: inspect error, fix, rerun until it passes or a real blocker requires user input.
 
+Work is not done when the code compiles. Work is done when the verification passes.
+
 ### Agent-First Observability
 
 For relevant work: add health/status surfaces, persist failure state (last error, phase, timestamp, retry count), verify both happy path and at least one diagnostic signal. Never log secrets. Remove noisy one-off instrumentation before finishing unless it provides durable diagnostic value.
 
 ### Root-cause-first debugging
 
-Fix the root cause, not symptoms. When applying a temporary mitigation, label it clearly and preserve the path to the real fix.
-
-## Situational Playbooks
-
-### Background processes
-
-Use `bg_shell` for persistent processes — servers, watchers, anything that keeps running. Set `type:'server'` + `ready_port` for dev servers, `group:'name'` for related processes. Use `wait_for_ready` instead of polling. Use `digest` for status checks, `highlights` for significant output, `output` only when debugging. Use `send_and_wait` for interactive CLIs. Kill processes when done.
-
-Use `async_bash` for one-shot commands (builds, tests, installs) where you want the output delivered back automatically. Result arrives as a follow-up message when the command exits — no polling needed. Use `await_job` to explicitly wait for a specific job, `cancel_job` to stop one, `/jobs` to see what's running.
-
-### Web behavior
-
-Verify frontend work with browser tools against a running app. Operating order: `browser_find`/`browser_snapshot_refs` for discovery → refs/selectors for targeting → `browser_batch` for obvious sequences → `browser_assert` for verification → `browser_diff` for ambiguous outcomes → console/network logs when assertions fail → full page inspection as last resort.
-
-Debug browser failures in order: failing assertion → `browser_diff` → console/network diagnostics → element/accessibility state → broader inspection. Retry only with a new hypothesis.
-
-### Libraries and current facts
-
-- Libraries: `resolve_library` → `get_library_docs` with specific topic query. Start with `tokens=5000`.
-- Current facts: `search-the-web` to evaluate the landscape and pick URLs, or `search_and_read` when you know what you're looking for. Use `freshness` for recency, `domain` to scope to a specific site.
+Fix the root cause, not symptoms. When applying a temporary mitigation, label it clearly and preserve the path to the real fix. Never add a guard or try/catch to suppress an error you haven't diagnosed.
 
 ## Communication
 

package/src/resources/extensions/gsd/templates/context.md

@@ -1,4 +1,4 @@
-# {{milestoneId}}: {{milestoneTitle}} — Context
+# {{milestoneId}}: {{milestoneTitle}}
 
 **Gathered:** {{date}}
 **Status:** Ready for planning

package/src/resources/extensions/gsd/templates/state.md

@@ -1,8 +1,8 @@
 # GSD State
 
-**Active Milestone:** {{milestoneId}} — {{milestoneTitle}}
-**Active Slice:** {{sliceId}} — {{sliceTitle}}
-**Active Task:** {{taskId}} — {{taskTitle}}
+**Active Milestone:** {{milestoneId}}: {{milestoneTitle}}
+**Active Slice:** {{sliceId}}: {{sliceTitle}}
+**Active Task:** {{taskId}}: {{taskTitle}}
 **Phase:** {{phase}}
 **Slice Branch:** {{activeBranch}}
 **Active Workspace:** {{activeWorkspace}}

package/src/resources/extensions/gsd/tests/auto-worktree-merge.test.ts

@@ -0,0 +1,282 @@
+/**
+ * auto-worktree-merge.test.ts — Integration tests for mergeSliceToMilestone.
+ *
+ * Covers: --no-ff merge topology, rich commit messages, slice branch deletion,
+ * zero-commit error, real code conflicts, .gsd/ non-conflict in worktree mode.
+ * All tests use real git operations in temp repos.
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import {
+  createAutoWorktree,
+  teardownAutoWorktree,
+  mergeSliceToMilestone,
+} from "../auto-worktree.ts";
+import { MergeConflictError } from "../git-service.ts";
+import { getSliceBranchName } from "../worktree.ts";
+
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+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(), "wt-merge-test-")));
+  run("git init", dir);
+  run("git config user.email test@test.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;
+}
+
+/** Create a slice branch in the worktree, add commits, return branch name. */
+function setupSliceBranch(
+  wtPath: string,
+  milestoneId: string,
+  sliceId: string,
+  commits: Array<{ file: string; content: string; message: string }>,
+): string {
+  // Detect worktree name for branch naming
+  const normalizedPath = wtPath.replaceAll("\\", "/");
+  const marker = "/.gsd/worktrees/";
+  const idx = normalizedPath.indexOf(marker);
+  const worktreeName = idx !== -1 ? normalizedPath.slice(idx + marker.length).split("/")[0] : null;
+  const sliceBranch = getSliceBranchName(milestoneId, sliceId, worktreeName);
+
+  run(`git checkout -b ${sliceBranch}`, wtPath);
+  for (const c of commits) {
+    writeFileSync(join(wtPath, c.file), c.content);
+    run("git add .", wtPath);
+    run(`git commit -m "${c.message}"`, wtPath);
+  }
+  return sliceBranch;
+}
+
+async function main(): Promise<void> {
+  const savedCwd = process.cwd();
+  const tempDirs: string[] = [];
+
+  function freshRepo(): string {
+    const d = createTempRepo();
+    tempDirs.push(d);
+    return d;
+  }
+
+  try {
+    // ─── Test 1: Single slice --no-ff merge ────────────────────────────
+    console.log("\n=== single slice --no-ff merge ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M003");
+
+      const sliceBranch = setupSliceBranch(wtPath, "M003", "S01", [
+        { file: "a.ts", content: "const a = 1;\n", message: "add a.ts" },
+        { file: "b.ts", content: "const b = 2;\n", message: "add b.ts" },
+        { file: "c.ts", content: "const c = 3;\n", message: "add c.ts" },
+      ]);
+      run("git checkout milestone/M003", wtPath);
+
+      const result = mergeSliceToMilestone(repo, "M003", "S01", "Add core files");
+
+      // Verify we're back on milestone branch
+      const branch = run("git branch --show-current", wtPath);
+      assertEq(branch, "milestone/M003", "back on milestone branch after merge");
+
+      // Verify merge topology via git log --graph
+      const log = run("git log --oneline --graph", wtPath);
+      assertTrue(log.includes("*   "), "merge commit visible in graph (asterisk with two parents)");
+      assertTrue(log.includes("add a.ts"), "slice commit 'add a.ts' visible");
+      assertTrue(log.includes("add b.ts"), "slice commit 'add b.ts' visible");
+      assertTrue(log.includes("add c.ts"), "slice commit 'add c.ts' visible");
+
+      // Verify commit message format
+      assertMatch(result.mergedCommitMessage, /feat\(M003\/S01\)/, "commit message has conventional format");
+      assertTrue(result.mergedCommitMessage.includes("Add core files"), "commit message includes slice title");
+
+      // Verify slice branch deleted
+      assertTrue(result.deletedBranch, "slice branch deleted");
+      const branches = run("git branch", wtPath);
+      assertTrue(!branches.includes(sliceBranch), "slice branch no longer in git branch list");
+
+      teardownAutoWorktree(repo, "M003");
+    }
+
+    // ─── Test 2: Two sequential slices ─────────────────────────────────
+    console.log("\n=== two sequential slices ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M003");
+
+      // Slice S01
+      setupSliceBranch(wtPath, "M003", "S01", [
+        { file: "s1.ts", content: "export const s1 = 1;\n", message: "s1 work" },
+      ]);
+      run("git checkout milestone/M003", wtPath);
+      mergeSliceToMilestone(repo, "M003", "S01", "First slice");
+
+      // Slice S02
+      setupSliceBranch(wtPath, "M003", "S02", [
+        { file: "s2.ts", content: "export const s2 = 2;\n", message: "s2 work" },
+      ]);
+      run("git checkout milestone/M003", wtPath);
+      mergeSliceToMilestone(repo, "M003", "S02", "Second slice");
+
+      // Verify two merge boundaries
+      const log = run("git log --oneline --graph", wtPath);
+      const mergeLines = log.split("\n").filter(l => l.includes("*   "));
+      assertTrue(mergeLines.length >= 2, "two distinct merge commits in graph");
+      assertTrue(log.includes("s1 work"), "S01 commit visible");
+      assertTrue(log.includes("s2 work"), "S02 commit visible");
+
+      teardownAutoWorktree(repo, "M003");
+    }
+
+    // ─── Test 3: Zero commits throws ───────────────────────────────────
+    console.log("\n=== zero commits throws ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M003");
+
+      // Create slice branch with no commits ahead
+      const normalizedPath = wtPath.replaceAll("\\", "/");
+      const marker = "/.gsd/worktrees/";
+      const idx = normalizedPath.indexOf(marker);
+      const worktreeName = idx !== -1 ? normalizedPath.slice(idx + marker.length).split("/")[0] : null;
+      const sliceBranch = getSliceBranchName("M003", "S01", worktreeName);
+      run(`git checkout -b ${sliceBranch}`, wtPath);
+      // No commits — immediately try to merge
+      run(`git checkout milestone/M003`, wtPath);
+
+      let threw = false;
+      try {
+        mergeSliceToMilestone(repo, "M003", "S01", "Empty slice");
+      } catch (err) {
+        threw = true;
+        assertTrue(
+          err instanceof Error && err.message.includes("no commits ahead"),
+          "error message mentions no commits ahead",
+        );
+      }
+      assertTrue(threw, "mergeSliceToMilestone throws on zero commits");
+
+      teardownAutoWorktree(repo, "M003");
+    }
+
+    // ─── Test 4: Real code conflict throws MergeConflictError ──────────
+    console.log("\n=== real code conflict throws MergeConflictError ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M003");
+
+      // Add a file on milestone branch
+      writeFileSync(join(wtPath, "shared.ts"), "// version 1\n");
+      run("git add .", wtPath);
+      run('git commit -m "add shared.ts"', wtPath);
+
+      // Create slice branch, modify same file differently
+      const normalizedPath = wtPath.replaceAll("\\", "/");
+      const marker = "/.gsd/worktrees/";
+      const idx = normalizedPath.indexOf(marker);
+      const worktreeName = idx !== -1 ? normalizedPath.slice(idx + marker.length).split("/")[0] : null;
+      const sliceBranch = getSliceBranchName("M003", "S01", worktreeName);
+      run(`git checkout -b ${sliceBranch}`, wtPath);
+      writeFileSync(join(wtPath, "shared.ts"), "// slice version\nexport const x = 1;\n");
+      run("git add .", wtPath);
+      run('git commit -m "slice edit shared.ts"', wtPath);
+
+      // Modify same file on milestone branch
+      run("git checkout milestone/M003", wtPath);
+      writeFileSync(join(wtPath, "shared.ts"), "// milestone version\nexport const y = 2;\n");
+      run("git add .", wtPath);
+      run('git commit -m "milestone edit shared.ts"', wtPath);
+
+      // Go back to milestone branch for merge call
+      run("git checkout milestone/M003", wtPath);
+
+      let caught: MergeConflictError | null = null;
+      try {
+        mergeSliceToMilestone(repo, "M003", "S01", "Conflicting slice");
+      } catch (err) {
+        if (err instanceof MergeConflictError) {
+          caught = err;
+        } else {
+          throw err;
+        }
+      }
+
+      assertTrue(caught !== null, "MergeConflictError thrown on conflict");
+      if (caught) {
+        assertTrue(caught.conflictedFiles.includes("shared.ts"), "conflictedFiles includes shared.ts");
+        assertEq(caught.strategy, "merge", "strategy is merge");
+        assertTrue(caught.branch.includes("S01"), "branch includes S01");
+      }
+
+      // Clean up conflict state before teardown
+      run("git merge --abort || true", wtPath);
+      run("git checkout milestone/M003", wtPath);
+      teardownAutoWorktree(repo, "M003");
+    }
+
+    // ─── Test 5: .gsd/ changes don't conflict ─────────────────────────
+    console.log("\n=== .gsd/ changes don't conflict ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M003");
+
+      // The .gsd/ directory in worktrees is local — it's not shared via git
+      // between the main repo and the worktree. So modifications to .gsd/
+      // files in both branches shouldn't cause conflicts because .gsd/ is
+      // in the main repo's tree but the worktree has its own working copy.
+      //
+      // In the worktree, .gsd/ IS tracked (inherited from main). But since
+      // slice branches diverge from milestone branch, .gsd/ changes on both
+      // can conflict. The key insight: in real auto-mode, .gsd/ changes only
+      // happen on the milestone branch (planning artifacts), not on slice
+      // branches (which only have code changes). So we test that code-only
+      // slice commits merge cleanly even when milestone has .gsd/ changes.
+
+      // Add a .gsd/ change on milestone branch
+      writeFileSync(join(wtPath, ".gsd", "STATE.md"), "# Updated State\nactive: M003\n");
+      run("git add .", wtPath);
+      run('git commit -m "update .gsd/STATE.md on milestone"', wtPath);
+
+      // Create slice branch with code-only changes
+      setupSliceBranch(wtPath, "M003", "S01", [
+        { file: "feature.ts", content: "export const feature = true;\n", message: "add feature" },
+      ]);
+      run("git checkout milestone/M003", wtPath);
+
+      // Merge should succeed — no .gsd/ conflict since slice didn't touch .gsd/
+      const result = mergeSliceToMilestone(repo, "M003", "S01", "Feature slice");
+      assertTrue(result.branch.includes("S01"), ".gsd/ no-conflict merge succeeded");
+      assertTrue(result.deletedBranch, "slice branch deleted after .gsd/-safe merge");
+
+      // Verify feature file exists after merge
+      assertTrue(existsSync(join(wtPath, "feature.ts")), "feature.ts present after merge");
+
+      teardownAutoWorktree(repo, "M003");
+    }
+
+  } finally {
+    process.chdir(savedCwd);
+    for (const d of tempDirs) {
+      if (existsSync(d)) rmSync(d, { recursive: true, force: true });
+    }
+  }
+
+  report();
+}
+
+main();

package/src/resources/extensions/gsd/tests/auto-worktree-milestone-merge.test.ts

@@ -0,0 +1,259 @@
+/**
+ * auto-worktree-milestone-merge.test.ts — Integration tests for mergeMilestoneToMain.
+ *
+ * Covers: squash-merge topology (one commit on main), rich commit message with
+ * slice titles, worktree cleanup, nothing-to-commit edge case, auto-push with
+ * bare remote. All tests use real git operations in temp repos.
+ */
+
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import {
+  createAutoWorktree,
+  mergeMilestoneToMain,
+  mergeSliceToMilestone,
+  getAutoWorktreeOriginalBase,
+} from "../auto-worktree.ts";
+import { getSliceBranchName } from "../worktree.ts";
+
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+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(), "wt-ms-merge-test-")));
+  run("git init", dir);
+  run("git config user.email test@test.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;
+}
+
+/** Minimal roadmap content for mergeMilestoneToMain. */
+function makeRoadmap(milestoneId: string, title: string, slices: Array<{ id: string; title: string }>): string {
+  const sliceLines = slices.map(s => `- [x] **${s.id}: ${s.title}**`).join("\n");
+  return `# ${milestoneId}: ${title}\n\n## Slices\n${sliceLines}\n`;
+}
+
+/** Set up a slice branch on the worktree, add commits, merge it --no-ff to milestone. */
+function addSliceToMilestone(
+  repo: string,
+  wtPath: string,
+  milestoneId: string,
+  sliceId: string,
+  sliceTitle: string,
+  commits: Array<{ file: string; content: string; message: string }>,
+): void {
+  // Detect worktree name for branch naming
+  const normalizedPath = wtPath.replaceAll("\\", "/");
+  const marker = "/.gsd/worktrees/";
+  const idx = normalizedPath.indexOf(marker);
+  const worktreeName = idx !== -1 ? normalizedPath.slice(idx + marker.length).split("/")[0] : null;
+
+  const sliceBranch = getSliceBranchName(milestoneId, sliceId, worktreeName);
+
+  run(`git checkout -b ${sliceBranch}`, wtPath);
+  for (const c of commits) {
+    writeFileSync(join(wtPath, c.file), c.content);
+    run("git add .", wtPath);
+    run(`git commit -m "${c.message}"`, wtPath);
+  }
+  run(`git checkout milestone/${milestoneId}`, wtPath);
+  mergeSliceToMilestone(repo, milestoneId, sliceId, sliceTitle);
+}
+
+async function main(): Promise<void> {
+  const savedCwd = process.cwd();
+  const tempDirs: string[] = [];
+
+  function freshRepo(): string {
+    const d = createTempRepo();
+    tempDirs.push(d);
+    return d;
+  }
+
+  try {
+    // ─── Test 1: Basic squash merge — one commit on main ───────────────
+    console.log("\n=== basic squash merge — one commit on main ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M010");
+
+      // Add two slices with multiple commits each
+      addSliceToMilestone(repo, wtPath, "M010", "S01", "Auth module", [
+        { file: "auth.ts", content: "export const auth = true;\n", message: "add auth" },
+        { file: "auth-utils.ts", content: "export const hash = () => {};\n", message: "add auth utils" },
+      ]);
+      addSliceToMilestone(repo, wtPath, "M010", "S02", "User dashboard", [
+        { file: "dashboard.ts", content: "export const dash = true;\n", message: "add dashboard" },
+        { file: "widgets.ts", content: "export const widgets = [];\n", message: "add widgets" },
+      ]);
+
+      const roadmap = makeRoadmap("M010", "User management", [
+        { id: "S01", title: "Auth module" },
+        { id: "S02", title: "User dashboard" },
+      ]);
+
+      const mainLogBefore = run("git log --oneline main", repo);
+      const mainCommitCountBefore = mainLogBefore.split("\n").length;
+
+      const result = mergeMilestoneToMain(repo, "M010", roadmap);
+
+      // Exactly one new commit on main
+      const mainLog = run("git log --oneline main", repo);
+      const mainCommitCountAfter = mainLog.split("\n").length;
+      assertEq(mainCommitCountAfter, mainCommitCountBefore + 1, "exactly one new commit on main");
+
+      // Milestone branch deleted
+      const branches = run("git branch", repo);
+      assertTrue(!branches.includes("milestone/M010"), "milestone branch deleted");
+
+      // Worktree directory removed
+      const worktreeDir = join(repo, ".gsd", "worktrees", "M010");
+      assertTrue(!existsSync(worktreeDir), "worktree directory removed");
+
+      // Module state cleared
+      assertEq(getAutoWorktreeOriginalBase(), null, "originalBase cleared after merge");
+
+      // Files from both slices present on main
+      assertTrue(existsSync(join(repo, "auth.ts")), "auth.ts on main");
+      assertTrue(existsSync(join(repo, "dashboard.ts")), "dashboard.ts on main");
+      assertTrue(existsSync(join(repo, "widgets.ts")), "widgets.ts on main");
+
+      // Result shape
+      assertTrue(result.commitMessage.length > 0, "commitMessage returned");
+      assertTrue(typeof result.pushed === "boolean", "pushed is boolean");
+    }
+
+    // ─── Test 2: Rich commit message format ────────────────────────────
+    console.log("\n=== rich commit message format ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M020");
+
+      addSliceToMilestone(repo, wtPath, "M020", "S01", "Core API", [
+        { file: "api.ts", content: "export const api = true;\n", message: "add api" },
+      ]);
+      addSliceToMilestone(repo, wtPath, "M020", "S02", "Error handling", [
+        { file: "errors.ts", content: "export class AppError {}\n", message: "add errors" },
+      ]);
+      addSliceToMilestone(repo, wtPath, "M020", "S03", "Logging infra", [
+        { file: "logger.ts", content: "export const log = () => {};\n", message: "add logger" },
+      ]);
+
+      const roadmap = makeRoadmap("M020", "Backend foundation", [
+        { id: "S01", title: "Core API" },
+        { id: "S02", title: "Error handling" },
+        { id: "S03", title: "Logging infra" },
+      ]);
+
+      const result = mergeMilestoneToMain(repo, "M020", roadmap);
+
+      // Subject line: conventional commit format
+      assertMatch(result.commitMessage, /^feat\(M020\):/, "subject has conventional commit prefix");
+      assertTrue(result.commitMessage.includes("Backend foundation"), "subject includes milestone title");
+
+      // Body: slice listing
+      assertTrue(result.commitMessage.includes("- S01: Core API"), "body lists S01");
+      assertTrue(result.commitMessage.includes("- S02: Error handling"), "body lists S02");
+      assertTrue(result.commitMessage.includes("- S03: Logging infra"), "body lists S03");
+
+      // Branch metadata
+      assertTrue(result.commitMessage.includes("Branch: milestone/M020"), "body has branch metadata");
+
+      // Verify the actual git commit message matches
+      const gitMsg = run("git log -1 --format=%B main", repo).trim();
+      assertMatch(gitMsg, /^feat\(M020\):/, "git commit message starts with feat(M020):");
+      assertTrue(gitMsg.includes("- S01: Core API"), "git commit body has S01");
+    }
+
+    // ─── Test 3: Nothing to commit — no changes ────────────────────────
+    console.log("\n=== nothing to commit — no changes ===");
+    {
+      const repo = freshRepo();
+      const wtPath = createAutoWorktree(repo, "M030");
+
+      // Don't add any slices/changes — milestone branch is identical to main
+      const roadmap = makeRoadmap("M030", "Empty milestone", []);
+
+      // Should complete without throwing
+      let threw = false;
+      try {
+        const result = mergeMilestoneToMain(repo, "M030", roadmap);
+        assertTrue(typeof result.pushed === "boolean", "returns result even with nothing to commit");
+      } catch {
+        threw = true;
+      }
+      assertTrue(!threw, "does not throw on nothing-to-commit");
+
+      // Main log unchanged (only init commit)
+      const mainLog = run("git log --oneline main", repo);
+      assertEq(mainLog.split("\n").length, 1, "main still has only init commit");
+    }
+
+    // ─── Test 4: Auto-push — verify push mechanics work ──────────────
+    // Note: loadEffectiveGSDPreferences uses a module-level const for project
+    // prefs path (process.cwd() at import time), so temp repo prefs aren't
+    // discoverable. We verify the push mechanics work by testing that
+    // mergeMilestoneToMain successfully completes with a remote configured,
+    // then manually push to verify the remote is set up correctly.
+    console.log("\n=== auto-push with bare remote ===");
+    {
+      const repo = freshRepo();
+
+      // Set up bare remote
+      const bareDir = realpathSync(mkdtempSync(join(tmpdir(), "wt-ms-bare-")));
+      tempDirs.push(bareDir);
+      run("git init --bare", bareDir);
+      run(`git remote add origin ${bareDir}`, repo);
+      run("git push -u origin main", repo);
+
+      const wtPath = createAutoWorktree(repo, "M040");
+
+      addSliceToMilestone(repo, wtPath, "M040", "S01", "Push test", [
+        { file: "pushed.ts", content: "export const pushed = true;\n", message: "add pushed file" },
+      ]);
+
+      const roadmap = makeRoadmap("M040", "Push verification", [
+        { id: "S01", title: "Push test" },
+      ]);
+
+      const result = mergeMilestoneToMain(repo, "M040", roadmap);
+
+      // Verify merge succeeded (commit on main)
+      const mainLog = run("git log --oneline main", repo);
+      assertTrue(mainLog.includes("feat(M040)"), "milestone commit on main");
+
+      // Manually push to verify remote works
+      run("git push origin main", repo);
+      const remoteLog = run("git log --oneline main", bareDir);
+      assertTrue(remoteLog.includes("feat(M040)"), "milestone commit reachable on remote after manual push");
+
+      // result.pushed will be false since prefs aren't loadable in temp repos
+      // (module-level const limitation) — that's expected
+      assertEq(result.pushed, false, "pushed is false without discoverable prefs");
+    }
+
+  } finally {
+    process.chdir(savedCwd);
+    for (const d of tempDirs) {
+      if (existsSync(d)) rmSync(d, { recursive: true, force: true });
+    }
+  }
+
+  report();
+}
+
+main();