gsd-pi 2.4.0 → 2.5.0

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

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import type { GitPreferences } from "./git-service.ts";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
 const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
@@ -51,6 +52,7 @@ export interface GSDPreferences {
   uat_dispatch?: boolean;
   budget_ceiling?: number;
   remote_questions?: RemoteQuestionsConfig;
+  git?: GitPreferences;
 }
 
 export interface LoadedGSDPreferences {
@@ -511,6 +513,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     remote_questions: override.remote_questions
       ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
       : base.remote_questions,
+    git: (base.git || override.git)
+      ? { ...(base.git ?? {}), ...(override.git ?? {}) }
+      : undefined,
   };
 }
 
@@ -594,6 +599,52 @@ function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Git Preferences ───────────────────────────────────────────────────
+  if (preferences.git && typeof preferences.git === "object") {
+    const git: Record<string, unknown> = {};
+    const g = preferences.git as Record<string, unknown>;
+
+    if (g.auto_push !== undefined) {
+      if (typeof g.auto_push === "boolean") git.auto_push = g.auto_push;
+      else errors.push("git.auto_push must be a boolean");
+    }
+    if (g.push_branches !== undefined) {
+      if (typeof g.push_branches === "boolean") git.push_branches = g.push_branches;
+      else errors.push("git.push_branches must be a boolean");
+    }
+    if (g.remote !== undefined) {
+      if (typeof g.remote === "string" && g.remote.trim() !== "") git.remote = g.remote.trim();
+      else errors.push("git.remote must be a non-empty string");
+    }
+    if (g.snapshots !== undefined) {
+      if (typeof g.snapshots === "boolean") git.snapshots = g.snapshots;
+      else errors.push("git.snapshots must be a boolean");
+    }
+    if (g.pre_merge_check !== undefined) {
+      if (typeof g.pre_merge_check === "boolean") {
+        git.pre_merge_check = g.pre_merge_check;
+      } else if (typeof g.pre_merge_check === "string" && g.pre_merge_check.trim() !== "") {
+        git.pre_merge_check = g.pre_merge_check.trim();
+      } else {
+        errors.push("git.pre_merge_check must be a boolean or a non-empty string command");
+      }
+    }
+    if (g.commit_type !== undefined) {
+      const validCommitTypes = new Set([
+        "feat", "fix", "refactor", "docs", "test", "chore", "perf", "ci", "build", "style",
+      ]);
+      if (typeof g.commit_type === "string" && validCommitTypes.has(g.commit_type)) {
+        git.commit_type = g.commit_type;
+      } else {
+        errors.push(`git.commit_type must be one of: feat, fix, refactor, docs, test, chore, perf, ci, build, style`);
+      }
+    }
+
+    if (Object.keys(git).length > 0) {
+      validated.git = git as GitPreferences;
+    }
+  }
+
   return { preferences: validated, errors };
 }
 

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -15,7 +15,7 @@ Then:
 6. Write `{{milestoneSummaryAbsPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
 7. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
 8. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
-9. Commit all changes: `git add -A && git commit -m 'feat(gsd): complete {{milestoneId}}'`
+9. Do not commit manually — the system auto-commits your changes after this unit completes.
 10. Update `.gsd/STATE.md`
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -18,7 +18,7 @@ Then:
 7. Write `{{sliceUatAbsPath}}`. Fill the new `UAT Type`, `Requirements Proved By This UAT`, and `Not Proven By This UAT` sections explicitly.
 8. Review task summaries for `key_decisions`. Ensure any significant architectural, pattern, or observability decisions are in `.gsd/DECISIONS.md`. If any are missing, append them now.
 9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
-10. Commit all remaining slice changes: `git add -A && git commit -m 'feat(gsd): complete {{sliceId}}'`. Do not squash-merge manually; the extension will merge the slice branch back to main after this unit succeeds.
+10. Do not commit or squash-merge manually — the system auto-commits your changes and handles the merge after this unit succeeds.
 11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 12. Update `.gsd/STATE.md`
 

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -55,7 +55,7 @@ Then:
 13. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 14. Write `{{taskSummaryAbsPath}}`
 15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
-16. Commit your work: `git add -A && git commit -m 'feat({{sliceId}}/{{taskId}}): <what was built>'`. If `git add` silently fails to stage files (a known git worktree stat-cache bug), use this workaround per file: `git update-index --cacheinfo 100644,$(git hash-object -w <file>),<file>` then commit. If that also fails, move on — the system will auto-commit remaining changes after your session ends.
+16. Do not commit manually — the system auto-commits your changes after this unit completes.
 17. Update `.gsd/STATE.md`
 
 You are on the slice branch. All work stays here.

package/src/resources/extensions/gsd/prompts/replan-slice.md

@@ -31,7 +31,7 @@ All relevant context has been preloaded below — the roadmap, current slice pla
    - Ensure the slice Goal and Demo sections are still achievable with the new tasks, or update them if the blocker fundamentally changes what the slice can deliver
    - Update the Files Likely Touched section if the replan changes which files are affected
 5. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
-6. Commit all changes: `git add -A && git commit -m 'refactor({{sliceId}}): replan after blocker in {{blockerTaskId}}'`
+6. Do not commit manually — the system auto-commits your changes after this unit completes.
 7. Update `.gsd/STATE.md`
 
 **You MUST write `{{replanAbsPath}}` and the updated slice plan before finishing.**

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

@@ -8,6 +8,13 @@ custom_instructions: []
 models: {}
 skill_discovery:
 auto_supervisor: {}
+git:
+  auto_push:
+  push_branches:
+  remote:
+  snapshots:
+  pre_merge_check:
+  commit_type:
 ---
 
 # GSD Skill Preferences

package/src/resources/extensions/gsd/tests/git-service.test.ts

@@ -11,6 +11,7 @@ import {
   type GitPreferences,
   type CommitOptions,
   type MergeSliceResult,
+  type PreMergeCheckResult,
 } from "../git-service.ts";
 
 let passed = 0;
@@ -881,6 +882,363 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ═══════════════════════════════════════════════════════════════════════
+  // S05: Enhanced features — merge guards, snapshots, auto-push, rich commits
+  // ═══════════════════════════════════════════════════════════════════════
+
+  // ─── createSnapshot: prefs enabled ─────────────────────────────────────
+
+  console.log("\n=== createSnapshot: enabled ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, { snapshots: true });
+
+    // Create a slice branch with a commit
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/snap.ts", "snapshot me");
+    svc.commit({ message: "snapshot test commit" });
+
+    // Create snapshot ref for this slice branch
+    svc.createSnapshot("gsd/M001/S01");
+
+    // Verify ref exists under refs/gsd/snapshots/
+    const refs = run("git for-each-ref refs/gsd/snapshots/", repo);
+    assert(refs.includes("refs/gsd/snapshots/gsd/M001/S01/"), "snapshot ref created under refs/gsd/snapshots/");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── createSnapshot: prefs disabled ────────────────────────────────────
+
+  console.log("\n=== createSnapshot: disabled ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, { snapshots: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/no-snap.ts", "no snapshot");
+    svc.commit({ message: "no snapshot commit" });
+
+    // createSnapshot should be a no-op when disabled
+    svc.createSnapshot("gsd/M001/S01");
+
+    const refs = run("git for-each-ref refs/gsd/snapshots/", repo);
+    assertEq(refs, "", "no snapshot ref created when prefs.snapshots is false");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── runPreMergeCheck: pass ────────────────────────────────────────────
+
+  console.log("\n=== runPreMergeCheck: pass ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // Create package.json with passing test script
+    createFile(repo, "package.json", JSON.stringify({
+      name: "test-pass",
+      scripts: { test: "node -e 'process.exit(0)'" },
+    }));
+    run("git add -A", repo);
+    run("git commit -m 'add package.json'", repo);
+
+    const svc = new GitServiceImpl(repo, { pre_merge_check: true });
+    const result: PreMergeCheckResult = svc.runPreMergeCheck();
+
+    assertEq(result.passed, true, "runPreMergeCheck returns passed:true when tests pass");
+    assert(!result.skipped, "runPreMergeCheck is not skipped when enabled");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── runPreMergeCheck: fail ────────────────────────────────────────────
+
+  console.log("\n=== runPreMergeCheck: fail ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // Create package.json with failing test script
+    createFile(repo, "package.json", JSON.stringify({
+      name: "test-fail",
+      scripts: { test: "node -e 'process.exit(1)'" },
+    }));
+    run("git add -A", repo);
+    run("git commit -m 'add failing package.json'", repo);
+
+    const svc = new GitServiceImpl(repo, { pre_merge_check: true });
+    const result: PreMergeCheckResult = svc.runPreMergeCheck();
+
+    assertEq(result.passed, false, "runPreMergeCheck returns passed:false when tests fail");
+    assert(!result.skipped, "runPreMergeCheck is not skipped when enabled");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── runPreMergeCheck: disabled ────────────────────────────────────────
+
+  console.log("\n=== runPreMergeCheck: disabled ===");
+
+  {
+    const repo = initBranchTestRepo();
+    createFile(repo, "package.json", JSON.stringify({
+      name: "test-disabled",
+      scripts: { test: "node -e 'process.exit(1)'" },
+    }));
+    run("git add -A", repo);
+    run("git commit -m 'add package.json'", repo);
+
+    const svc = new GitServiceImpl(repo, { pre_merge_check: false });
+    const result: PreMergeCheckResult = svc.runPreMergeCheck();
+
+    assertEq(result.skipped, true, "runPreMergeCheck skipped when pre_merge_check is false");
+    assertEq(result.passed, true, "runPreMergeCheck returns passed:true when skipped (no block)");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── runPreMergeCheck: custom command ──────────────────────────────────
+
+  console.log("\n=== runPreMergeCheck: custom command ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // Custom command string overrides auto-detection
+    const svc = new GitServiceImpl(repo, { pre_merge_check: "node -e 'process.exit(0)'" });
+    const result: PreMergeCheckResult = svc.runPreMergeCheck();
+
+    assertEq(result.passed, true, "runPreMergeCheck passes with custom command that exits 0");
+    assert(!result.skipped, "custom command is not skipped");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── Rich commit message ──────────────────────────────────────────────
+
+  console.log("\n=== mergeSliceToMain: rich commit message ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo, { pre_merge_check: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+
+    // Make 3 distinct commits on the slice branch
+    createFile(repo, "src/auth.ts", "export const auth = true;");
+    svc.commit({ message: "add auth module" });
+
+    createFile(repo, "src/login.ts", "export const login = true;");
+    svc.commit({ message: "add login page" });
+
+    createFile(repo, "src/session.ts", "export const session = true;");
+    svc.commit({ message: "add session handling" });
+
+    svc.switchToMain();
+    const result = svc.mergeSliceToMain("M001", "S01", "Implement user authentication");
+
+    // Inspect the full commit body on main
+    const commitBody = run("git log -1 --format=%B", repo);
+
+    // Rich commit should have the subject line
+    assert(commitBody.includes("feat(M001/S01): Implement user authentication"),
+      "rich commit has conventional subject line");
+
+    // Rich commit body should include task list with commit subjects
+    assert(commitBody.includes("add auth module"),
+      "rich commit body includes first commit subject");
+    assert(commitBody.includes("add login page"),
+      "rich commit body includes second commit subject");
+    assert(commitBody.includes("add session handling"),
+      "rich commit body includes third commit subject");
+
+    // Rich commit body should include Branch: line for forensics
+    assert(commitBody.includes("Branch:"),
+      "rich commit body includes Branch: line");
+    assert(commitBody.includes("gsd/M001/S01"),
+      "rich commit body Branch: line includes slice branch name");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── Auto-push: enabled ───────────────────────────────────────────────
+
+  console.log("\n=== Auto-push: enabled ===");
+
+  {
+    // Create a bare remote repo
+    const bareDir = mkdtempSync(join(tmpdir(), "gsd-git-bare-"));
+    run("git init --bare -b main", bareDir);
+
+    // Create local repo and add the bare as remote
+    const repo = initBranchTestRepo();
+    run(`git remote add origin ${bareDir}`, repo);
+    run("git push -u origin main", repo);
+
+    const svc = new GitServiceImpl(repo, { auto_push: true, pre_merge_check: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/pushed.ts", "export const pushed = true;");
+    svc.commit({ message: "work to push" });
+
+    svc.switchToMain();
+    svc.mergeSliceToMain("M001", "S01", "Add pushed feature");
+
+    // Verify the remote has the merge commit
+    const remoteLog = run(`git --git-dir=${bareDir} log --oneline -1`, bareDir);
+    assert(remoteLog.includes("Add pushed feature"),
+      "auto-push: remote has the merge commit when auto_push is true");
+
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(bareDir, { recursive: true, force: true });
+  }
+
+  // ─── Auto-push: disabled ──────────────────────────────────────────────
+
+  console.log("\n=== Auto-push: disabled ===");
+
+  {
+    const bareDir = mkdtempSync(join(tmpdir(), "gsd-git-bare-"));
+    run("git init --bare -b main", bareDir);
+
+    const repo = initBranchTestRepo();
+    run(`git remote add origin ${bareDir}`, repo);
+    run("git push -u origin main", repo);
+
+    // auto_push explicitly false (or omitted — same behavior)
+    const svc = new GitServiceImpl(repo, { auto_push: false, pre_merge_check: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/not-pushed.ts", "export const notPushed = true;");
+    svc.commit({ message: "work not pushed" });
+
+    svc.switchToMain();
+    svc.mergeSliceToMain("M001", "S01", "Add unpushed feature");
+
+    // Remote should NOT have the new merge commit — still at the initial push
+    const remoteLog = run(`git --git-dir=${bareDir} log --oneline`, bareDir);
+    assert(!remoteLog.includes("Add unpushed feature"),
+      "auto-push: remote does NOT have merge commit when auto_push is false");
+
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(bareDir, { recursive: true, force: true });
+  }
+
+  // ─── Remote fetch before branching: with remote ────────────────────────
+
+  console.log("\n=== Remote fetch: with remote ===");
+
+  {
+    const bareDir = mkdtempSync(join(tmpdir(), "gsd-git-bare-"));
+    run("git init --bare -b main", bareDir);
+
+    const repo = initBranchTestRepo();
+    run(`git remote add origin ${bareDir}`, repo);
+    run("git push -u origin main", repo);
+
+    // Add a commit to the remote via a temporary clone
+    const cloneDir = mkdtempSync(join(tmpdir(), "gsd-git-clone-"));
+    run(`git clone ${bareDir} ${cloneDir}`, cloneDir);
+    run("git config user.name 'Remote Dev'", cloneDir);
+    run("git config user.email 'remote@example.com'", cloneDir);
+    createFile(cloneDir, "remote-file.txt", "from remote");
+    run("git add -A", cloneDir);
+    run("git commit -m 'remote commit'", cloneDir);
+    run("git push origin main", cloneDir);
+
+    // ensureSliceBranch should fetch before creating the branch — no crash
+    const svc = new GitServiceImpl(repo);
+    let noError = true;
+    try {
+      svc.ensureSliceBranch("M001", "S01");
+    } catch {
+      noError = false;
+    }
+    assert(noError, "ensureSliceBranch succeeds when remote has new commits (fetch runs)");
+
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(bareDir, { recursive: true, force: true });
+    rmSync(cloneDir, { recursive: true, force: true });
+  }
+
+  // ─── Remote fetch before branching: without remote ─────────────────────
+
+  console.log("\n=== Remote fetch: without remote ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // No remote configured — ensureSliceBranch should not crash
+    const svc = new GitServiceImpl(repo);
+
+    let noError = true;
+    try {
+      svc.ensureSliceBranch("M001", "S01");
+    } catch {
+      noError = false;
+    }
+    assert(noError, "ensureSliceBranch succeeds when no remote is configured");
+    assertEq(svc.getCurrentBranch(), "gsd/M001/S01", "branch created even without remote");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── Facade prefs: mergeSliceToMain creates snapshot when prefs set ────
+
+  console.log("\n=== Facade prefs: snapshot via merge with prefs ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // Simulate facade behavior: GitServiceImpl with snapshots:true should
+    // create a snapshot ref during mergeSliceToMain
+    const svc = new GitServiceImpl(repo, { snapshots: true, pre_merge_check: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/facade-test.ts", "facade");
+    svc.commit({ message: "facade test commit" });
+
+    svc.switchToMain();
+    svc.mergeSliceToMain("M001", "S01", "Facade snapshot test");
+
+    // After merge, a snapshot ref should exist (created before merge)
+    const refs = run("git for-each-ref refs/gsd/snapshots/", repo);
+    assert(refs.includes("refs/gsd/snapshots/"), "mergeSliceToMain creates snapshot when prefs.snapshots is true");
+    assert(refs.includes("gsd/M001/S01"), "snapshot ref references the slice branch name");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── Facade prefs: no snapshot when prefs omit snapshots ───────────────
+
+  console.log("\n=== Facade prefs: no snapshot when prefs omit snapshots ===");
+
+  {
+    const repo = initBranchTestRepo();
+    // Default prefs — snapshots not enabled
+    const svc = new GitServiceImpl(repo, { pre_merge_check: false });
+
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, "src/no-facade-snap.ts", "no facade snap");
+    svc.commit({ message: "no facade snapshot" });
+
+    svc.switchToMain();
+    svc.mergeSliceToMain("M001", "S01", "No snapshot test");
+
+    // No snapshot ref should exist
+    const refs = run("git for-each-ref refs/gsd/snapshots/", repo);
+    assertEq(refs, "", "no snapshot ref when snapshots pref is not set");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
+  // ─── PreMergeCheckResult type export compile check ─────────────────────
+
+  console.log("\n=== PreMergeCheckResult type export ===");
+
+  {
+    const _checkResult: PreMergeCheckResult = { passed: true, skipped: false };
+    assert(true, "PreMergeCheckResult type exported and usable");
+  }
+
   console.log(`\nResults: ${passed} passed, ${failed} failed`);
   if (failed > 0) process.exit(1);
   console.log("All tests passed ✓");

package/src/resources/extensions/gsd/tests/replan-slice.test.ts

@@ -385,7 +385,6 @@ console.log('\n=== prompt: replan-slice template loads and substitutes variables
     sliceTitle: 'Test Slice',
     slicePath: '.gsd/milestones/M001/slices/S01',
     planPath: '.gsd/milestones/M001/slices/S01/S01-PLAN.md',
-    blockerTaskId: 'T02',
     inlinedContext: '## Inlined Context\n\nTest context here.',
   });
 
@@ -393,7 +392,6 @@ console.log('\n=== prompt: replan-slice template loads and substitutes variables
   assert(prompt.includes('S01'), 'prompt contains sliceId');
   assert(prompt.includes('Test Slice'), 'prompt contains sliceTitle');
   assert(prompt.includes('.gsd/milestones/M001/slices/S01/S01-PLAN.md'), 'prompt contains planPath');
-  assert(prompt.includes('T02'), 'prompt contains blockerTaskId');
   assert(prompt.includes('Test context here'), 'prompt contains inlined context');
 }
 

package/src/resources/extensions/gsd/worktree-command.ts

@@ -19,6 +19,7 @@ import {
   createWorktree,
   listWorktrees,
   removeWorktree,
+  mergeWorktreeToMain,
   diffWorktreeAll,
   diffWorktreeNumstat,
   getMainBranch,
@@ -28,7 +29,9 @@ import {
   worktreeBranchName,
   worktreePath,
 } from "./worktree-manager.js";
+import { inferCommitType } from "./git-service.js";
 import type { FileLineStat } from "./worktree-manager.js";
+import { execSync } from "node:child_process";
 import { existsSync, realpathSync, readFileSync, readdirSync, rmSync, unlinkSync, utimesSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 
@@ -349,13 +352,14 @@ async function handleCreate(
   ctx: ExtensionCommandContext,
 ): Promise<void> {
   try {
+    // Auto-commit dirty files before leaving current workspace (must happen
+    // before createWorktree so the new worktree forks from committed HEAD)
+    const commitMsg = autoCommitCurrentBranch(basePath, "worktree-switch", name);
+
     // Create from the main tree, not from inside another worktree
     const mainBase = originalCwd ?? basePath;
     const info = createWorktree(mainBase, name);
 
-    // Auto-commit dirty files before leaving current workspace
-    const commitMsg = autoCommitCurrentBranch(basePath, "worktree-switch", name);
-
     // Track original cwd before switching
     if (!originalCwd) originalCwd = basePath;
 
@@ -655,9 +659,8 @@ async function handleMerge(
       return;
     }
 
-    // Switch to the main tree before dispatching the merge.
-    // The LLM needs to run git merge --squash from the main branch, and if
-    // it later removes the worktree, the agent's CWD must not be inside it.
+    // Switch to the main tree before merging.
+    // Must be on the main branch to run git merge --squash.
     if (originalCwd) {
       const prevCwd = process.cwd();
       process.chdir(basePath);
@@ -665,6 +668,45 @@ async function handleMerge(
       originalCwd = null;
     }
 
+    // --- Deterministic merge path (preferred) ---
+    // Try a direct squash-merge first. Only fall back to LLM on conflict.
+    const commitType = inferCommitType(name);
+    const commitMessage = `${commitType}(${name}): merge worktree ${name}`;
+    try {
+      mergeWorktreeToMain(basePath, name, commitMessage);
+      ctx.ui.notify(
+        [
+          `${CLR.ok("✓")} Merged ${CLR.name(name)} → ${CLR.branch(mainBranch)} ${CLR.muted("(deterministic squash)")}`,
+          "",
+          `  ${totalChanges} file${totalChanges === 1 ? "" : "s"} changed, ${CLR.ok(`+${totalAdded}`)} ${RED}-${totalRemoved}${RESET} lines`,
+          `  ${CLR.muted("commit:")} ${commitMessage}`,
+        ].join("\n"),
+        "info",
+      );
+      return;
+    } catch (mergeErr) {
+      const mergeMsg = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
+      const isConflict = /conflict/i.test(mergeMsg);
+
+      if (isConflict) {
+        // Abort the failed merge so the working tree is clean for LLM retry
+        try {
+          execSync("git merge --abort", { cwd: basePath, stdio: "pipe" });
+        } catch { /* already clean */ }
+
+        ctx.ui.notify(
+          `${CLR.muted("Deterministic merge hit conflicts — falling back to LLM-guided merge.")}`,
+          "warning",
+        );
+        // Fall through to LLM dispatch below
+      } else {
+        // Non-conflict error — surface it directly, don't fall back
+        ctx.ui.notify(`Failed to merge: ${mergeMsg}`, "error");
+        return;
+      }
+    }
+
+    // --- LLM fallback path (conflict resolution) ---
     // Format file lists for the prompt
     const formatFiles = (files: string[]) =>
       files.length > 0 ? files.map(f => `- \`${f}\``).join("\n") : "_(none)_";