gsd-pi 2.12.0 → 2.13.0

package/dist/resources/extensions/gsd/git-self-heal.ts

@@ -0,0 +1,198 @@
+/**
+ * git-self-heal.ts — Automated git state recovery utilities.
+ *
+ * Four synchronous functions for recovering from broken git state
+ * during auto-mode operations. Uses only `git reset --hard HEAD` —
+ * never `git clean` (which would delete untracked .gsd/ dirs).
+ *
+ * Observability: Each function returns structured results describing
+ * what actions were taken. `formatGitError` maps raw git errors to
+ * user-friendly messages suggesting `/gsd doctor`.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { MergeConflictError } from "./git-service.js";
+
+// Re-export for consumers
+export { MergeConflictError };
+
+/** Result from abortAndReset describing what was cleaned up. */
+export interface AbortAndResetResult {
+  /** List of actions taken, e.g. ["aborted merge", "removed SQUASH_MSG", "reset to HEAD"] */
+  cleaned: string[];
+}
+
+/**
+ * Detect and clean up leftover merge/rebase state, then hard-reset.
+ *
+ * Checks for: .git/MERGE_HEAD, .git/SQUASH_MSG, .git/rebase-apply.
+ * Aborts in-progress merge or rebase if detected. Always finishes
+ * with `git reset --hard HEAD`.
+ *
+ * @returns Structured result listing what was cleaned. Empty `cleaned`
+ *          array means repo was already in a clean state.
+ */
+export function abortAndReset(cwd: string): AbortAndResetResult {
+  const gitDir = join(cwd, ".git");
+  const cleaned: string[] = [];
+
+  // Abort in-progress merge
+  if (existsSync(join(gitDir, "MERGE_HEAD"))) {
+    try {
+      execSync("git merge --abort", { cwd, stdio: "pipe" });
+      cleaned.push("aborted merge");
+    } catch {
+      // merge --abort can fail if state is really broken; continue to reset
+      cleaned.push("merge abort attempted (may have failed)");
+    }
+  }
+
+  // Remove leftover SQUASH_MSG (squash-merge leaves this without MERGE_HEAD)
+  const squashMsgPath = join(gitDir, "SQUASH_MSG");
+  if (existsSync(squashMsgPath)) {
+    try {
+      unlinkSync(squashMsgPath);
+      cleaned.push("removed SQUASH_MSG");
+    } catch {
+      // Not critical
+    }
+  }
+
+  // Abort in-progress rebase
+  if (existsSync(join(gitDir, "rebase-apply")) || existsSync(join(gitDir, "rebase-merge"))) {
+    try {
+      execSync("git rebase --abort", { cwd, stdio: "pipe" });
+      cleaned.push("aborted rebase");
+    } catch {
+      cleaned.push("rebase abort attempted (may have failed)");
+    }
+  }
+
+  // Always hard-reset to HEAD
+  try {
+    execSync("git reset --hard HEAD", { cwd, stdio: "pipe" });
+    if (cleaned.length > 0) {
+      cleaned.push("reset to HEAD");
+    }
+  } catch {
+    cleaned.push("reset to HEAD failed");
+  }
+
+  return { cleaned };
+}
+
+/**
+ * Wrap a merge operation with self-healing retry logic.
+ *
+ * Calls `mergeFn()`. On failure:
+ * - If conflicted files exist (via `git diff --diff-filter=U`), re-throws
+ *   as MergeConflictError immediately — no retry for real code conflicts.
+ * - Otherwise, runs `abortAndReset(cwd)`, retries `mergeFn()` once.
+ * - On second failure, throws the error.
+ *
+ * @param cwd - Working directory for git operations
+ * @param mergeFn - Synchronous function that performs the merge
+ * @returns The return value of `mergeFn()`
+ */
+export function withMergeHeal<T>(cwd: string, mergeFn: () => T): T {
+  try {
+    return mergeFn();
+  } catch (firstError) {
+    // Check for real code conflicts — escalate immediately, no retry
+    try {
+      const conflictOutput = execSync("git diff --name-only --diff-filter=U", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+
+      if (conflictOutput.length > 0) {
+        const conflictedFiles = conflictOutput.split("\n").filter(Boolean);
+        // If the original error is already a MergeConflictError, re-throw as-is
+        if (firstError instanceof MergeConflictError) {
+          throw firstError;
+        }
+        throw new MergeConflictError(
+          conflictedFiles,
+          "merge",
+          "unknown",
+          "unknown",
+        );
+      }
+    } catch (diffErr) {
+      // If diffErr is a MergeConflictError we just created/re-threw, propagate it
+      if (diffErr instanceof MergeConflictError) throw diffErr;
+      // Otherwise git diff itself failed — proceed with retry
+    }
+
+    // No real conflict detected — try abort+reset+retry once
+    abortAndReset(cwd);
+
+    // Retry
+    return mergeFn();
+  }
+}
+
+/**
+ * Recover a failed checkout by resetting first, then checking out.
+ *
+ * Performs `git reset --hard HEAD` then `git checkout <targetBranch>`.
+ * If checkout still fails after reset, throws with context.
+ */
+export function recoverCheckout(cwd: string, targetBranch: string): void {
+  execSync("git reset --hard HEAD", { cwd, stdio: "pipe" });
+
+  try {
+    execSync(`git checkout ${targetBranch}`, { cwd, stdio: "pipe" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `recoverCheckout failed: could not checkout '${targetBranch}' after reset. ${msg}`,
+    );
+  }
+}
+
+/** Known git error patterns mapped to user-friendly messages. */
+const ERROR_PATTERNS: Array<{ pattern: RegExp; message: string }> = [
+  {
+    pattern: /conflict|CONFLICT|merge conflict/i,
+    message: "A merge conflict occurred. Code changes on different branches touched the same files. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /cannot checkout|did not match any|pathspec .* did not match/i,
+    message: "Git could not switch branches — the target branch may not exist or the working tree is dirty. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /HEAD detached|detached HEAD/i,
+    message: "Git is in a detached HEAD state — not on any branch. Run `/gsd doctor` to diagnose and reattach.",
+  },
+  {
+    pattern: /\.lock|Unable to create .* lock|lock file/i,
+    message: "A git lock file is blocking operations. Another git process may be running, or a previous one crashed. Run `/gsd doctor` to diagnose.",
+  },
+  {
+    pattern: /fatal: not a git repository/i,
+    message: "This directory is not a git repository. Run `/gsd doctor` to check your project setup.",
+  },
+];
+
+/**
+ * Translate raw git error strings into user-friendly messages.
+ *
+ * Pattern-matches against common git error strings and returns
+ * a non-technical message suggesting `/gsd doctor`. Returns the
+ * original message if no pattern matches.
+ */
+export function formatGitError(error: string | Error): string {
+  const errorStr = error instanceof Error ? error.message : error;
+
+  for (const { pattern, message } of ERROR_PATTERNS) {
+    if (pattern.test(errorStr)) {
+      return message;
+    }
+  }
+
+  return `A git error occurred: ${errorStr.slice(0, 200)}. Run \`/gsd doctor\` for help.`;
+}

package/dist/resources/extensions/gsd/git-service.ts

@@ -37,6 +37,8 @@ export interface GitPreferences {
   commit_type?: string;
   main_branch?: string;
   merge_strategy?: "squash" | "merge";
+  isolation?: "worktree" | "branch";
+  merge_to_main?: "milestone" | "slice";
 }
 
 export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/;
@@ -764,6 +766,15 @@ export class GitServiceImpl {
       this.git(mergeArgs);
     } catch (mergeError) {
       // Check if conflicts can be auto-resolved (#189, #218)
+      //
+      // ─── BRANCH-MODE ONLY (D038) ────────────────────────────────────────
+      // The conflict resolution logic below applies ONLY when git.isolation = "branch".
+      // In worktree isolation mode, each milestone works in its own worktree directory
+      // so merge conflicts between slice branches and main are handled differently
+      // (worktree teardown merges via worktree-manager). This block is never reached
+      // in worktree mode because mergeSliceToMain is only called from the branch-mode
+      // code path. If you're modifying this logic, verify the isolation mode first.
+      // ─────────────────────────────────────────────────────────────────────
       const conflicted = this.git(["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });
       if (conflicted) {
         const conflictedFiles = conflicted.split("\n").filter(Boolean);

package/dist/resources/extensions/gsd/preferences.ts

@@ -634,7 +634,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
   };
 }
 
-function validatePreferences(preferences: GSDPreferences): {
+export function validatePreferences(preferences: GSDPreferences): {
   preferences: GSDPreferences;
   errors: string[];
 } {
@@ -905,6 +905,22 @@ function validatePreferences(preferences: GSDPreferences): {
         errors.push("git.main_branch must be a valid branch name (alphanumeric, _, -, /, .)");
       }
     }
+    if (g.isolation !== undefined) {
+      const validIsolation = new Set(["worktree", "branch"]);
+      if (typeof g.isolation === "string" && validIsolation.has(g.isolation)) {
+        git.isolation = g.isolation as "worktree" | "branch";
+      } else {
+        errors.push("git.isolation must be one of: worktree, branch");
+      }
+    }
+    if (g.merge_to_main !== undefined) {
+      const validMergeToMain = new Set(["milestone", "slice"]);
+      if (typeof g.merge_to_main === "string" && validMergeToMain.has(g.merge_to_main)) {
+        git.merge_to_main = g.merge_to_main as "milestone" | "slice";
+      } else {
+        errors.push("git.merge_to_main must be one of: milestone, slice");
+      }
+    }
 
     if (Object.keys(git).length > 0) {
       validated.git = git as GitPreferences;

package/dist/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/dist/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();