@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

package/src/resources/extensions/gsd/auto-worktree-merge-pre-teardown.ts

@@ -0,0 +1,93 @@
+// gsd-pi — Milestone merge pre-teardown safety guard.
+//
+// Owns the final data-loss check before deleting a merged milestone worktree:
+// if the milestone worktree still has uncommitted work, abort teardown so the
+// milestone branch remains a recovery ref.
+
+import { existsSync } from "node:fs";
+
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  nativeGetCurrentBranch,
+  nativeWorkingTreeStatus,
+} from "./native-git-bridge.js";
+
+export interface PreTeardownSafetyRequest {
+  milestoneBranch: string;
+  previousCwd: string;
+  worktreeCwd: string;
+}
+
+interface PreTeardownSafetyDeps {
+  chdir: typeof process.chdir;
+  debugLog: typeof debugLog;
+  existsSync: typeof existsSync;
+  nativeGetCurrentBranch: typeof nativeGetCurrentBranch;
+  nativeWorkingTreeStatus: typeof nativeWorkingTreeStatus;
+}
+
+const defaultDeps: PreTeardownSafetyDeps = {
+  chdir: process.chdir.bind(process),
+  debugLog,
+  existsSync,
+  nativeGetCurrentBranch,
+  nativeWorkingTreeStatus,
+};
+
+let deps: PreTeardownSafetyDeps = defaultDeps;
+
+export function _setPreTeardownSafetyDepsForTests(
+  overrides: Partial<PreTeardownSafetyDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetPreTeardownSafetyDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+/**
+ * Abort teardown when the milestone worktree still has uncommitted changes.
+ *
+ * The guard is intentionally scoped to worktree paths that are still on the
+ * milestone branch. In branch-mode or parallel merge paths, `worktreeCwd` can
+ * point at the integration branch; blocking on that dirty state would conflate
+ * unrelated milestones and preserve the wrong recovery ref.
+ */
+export function assertMilestoneWorktreeCleanBeforeTeardown(
+  request: PreTeardownSafetyRequest,
+): void {
+  const { milestoneBranch, previousCwd, worktreeCwd } = request;
+  if (!deps.existsSync(worktreeCwd)) return;
+
+  let preTeardownBranch: string | null = null;
+  try {
+    preTeardownBranch = deps.nativeGetCurrentBranch(worktreeCwd);
+  } catch (err) {
+    deps.debugLog("mergeMilestoneToMain", {
+      phase: "pre-teardown-branch-detect-failed",
+      error: String(err),
+    });
+  }
+
+  if (preTeardownBranch !== milestoneBranch) return;
+
+  try {
+    const dirtyCheck = deps.nativeWorkingTreeStatus(worktreeCwd);
+    if (!dirtyCheck) return;
+
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Milestone worktree still has uncommitted changes after squash merge. ` +
+        `Aborting teardown to preserve ${milestoneBranch}. Status:\n${dirtyCheck}`,
+    );
+  } catch (err) {
+    if (err instanceof GSDError) throw err;
+    deps.debugLog("mergeMilestoneToMain", {
+      phase: "pre-teardown-dirty-check-error",
+      error: String(err),
+    });
+  }
+}

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

@@ -0,0 +1,213 @@
+// gsd-pi — Pre-merge stash handling for auto-worktree merge closeout.
+//
+// Owns the local-work protection around milestone merge: stash before merge,
+// DB handle cycling for Windows, restoring on merge failures, and post-commit
+// stash-pop conflict recovery.
+
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+
+import {
+  closeWorkflowDatabase,
+  getWorkflowDatabasePath,
+  openWorkflowDatabasePath,
+} from "./db-workspace.js";
+import {
+  nativeAddPaths,
+  nativeConflictFiles,
+  nativeLsFiles,
+  nativeRmForce,
+} from "./native-git-bridge.js";
+import {
+  gsdJsonlFilesWithConflictMarkers,
+  hasConflictMarkers,
+  popStashByRef,
+  stashAlreadyExistsFilesFromError,
+  stashRefFromError,
+} from "./worktree-git-recovery.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface PreMergeStash {
+  stash(): void;
+  reopenDbAfterMerge(): void;
+  restoreForMergeFailure(): void;
+  restoreAfterCommit(): void;
+}
+
+export function createPreMergeStash(
+  basePath: string,
+  milestoneId: string,
+  cycleDbHandles: boolean,
+): PreMergeStash {
+  let stashed = false;
+  let marker: string | null = null;
+  const dbPathToReopen = cycleDbHandles ? getWorkflowDatabasePath() : null;
+
+  return {
+    stash(): void {
+      closeDbBeforeStashIfNeeded(cycleDbHandles);
+      try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+          cwd: basePath,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        }).trim();
+        if (!status) return;
+
+        marker = createStashMarker(milestoneId);
+        execFileSync(
+          "git",
+          ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId} [${marker}]`],
+          { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+        );
+        stashed = true;
+      } catch (err) {
+        // Stash failure is non-fatal — proceed without stash and let the merge
+        // report the dirty tree if it fails.
+        logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    reopenDbAfterMerge(): void {
+      if (!cycleDbHandles || !dbPathToReopen) return;
+      try {
+        openWorkflowDatabasePath(dbPathToReopen);
+      } catch (err) {
+        logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    restoreForMergeFailure(): void {
+      if (!stashed) return;
+      try {
+        popStashByRef(basePath, marker);
+      } catch (err) {
+        logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    },
+
+    restoreAfterCommit(): void {
+      if (!stashed) return;
+      restoreStashAfterCommit(basePath, marker);
+    },
+  };
+}
+
+function closeDbBeforeStashIfNeeded(cycleDbHandles: boolean): void {
+  if (!cycleDbHandles) return;
+  try {
+    closeWorkflowDatabase();
+  } catch (err) {
+    logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function createStashMarker(milestoneId: string): string {
+  return `gsd-pre-merge:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+}
+
+function restoreStashAfterCommit(basePath: string, marker: string | null): void {
+  let stashRefForDrop: string | null = null;
+  try {
+    stashRefForDrop = popStashByRef(basePath, marker);
+  } catch (e) {
+    stashRefForDrop = stashRefFromError(e);
+    logWarning("worktree", `git stash pop failed, attempting conflict resolution: ${(e as Error).message}`);
+    resolveStashPopConflict(basePath, e, stashRefForDrop);
+  }
+}
+
+function resolveStashPopConflict(basePath: string, error: unknown, stashRefForDrop: string | null): void {
+  const uu = nativeConflictFiles(basePath);
+  const gsdUU = uu.filter((f) => f.startsWith(".gsd/"));
+  const nonGsdUU = uu.filter((f) => !f.startsWith(".gsd/"));
+  const stashPopMessage = error instanceof Error ? error.message : String(error);
+  const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
+  const gsdContentConflicts: string[] = [];
+  const alreadyExists = stashAlreadyExistsFilesFromError(error);
+
+  if (isUntrackedRestoreFailure) {
+    gsdContentConflicts.push(...gsdJsonlFilesWithConflictMarkers(basePath));
+  }
+
+  const gsdConflictFiles = [...new Set([...gsdUU, ...gsdContentConflicts])];
+  resolveGsdConflictFiles(basePath, gsdConflictFiles);
+
+  if (gsdConflictFiles.length > 0 && nonGsdUU.length === 0) {
+    dropStashIfNoNonGsdConflictsRemain(basePath, stashRefForDrop);
+    return;
+  }
+
+  if (gsdUU.length === 0 && nonGsdUU.length === 0 && alreadyExists.length > 0) {
+    dropRecordedStash(basePath, stashRefForDrop);
+    return;
+  }
+
+  if (nonGsdUU.length > 0) {
+    logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
+      files: nonGsdUU.join(", "),
+    });
+    return;
+  }
+
+  logWarning(
+    "worktree",
+    "git stash pop failed without resolvable conflict files; leaving stash for manual recovery",
+  );
+}
+
+function resolveGsdConflictFiles(basePath: string, conflictFiles: string[]): void {
+  for (const file of conflictFiles) {
+    try {
+      // Accept the committed (HEAD) version of the state file.
+      execFileSync("git", ["checkout", "HEAD", "--", file], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      });
+      nativeAddPaths(basePath, [file]);
+    } catch (err) {
+      // Last resort: remove the conflicted state file.
+      logWarning("worktree", `checkout HEAD failed for ${file}, removing: ${(err as Error).message}`);
+      nativeRmForce(basePath, [file]);
+    }
+  }
+}
+
+function dropStashIfNoNonGsdConflictsRemain(basePath: string, stashRefForDrop: string | null): void {
+  const remainingUnmerged = nativeConflictFiles(basePath);
+  const nonGsdUnmerged = remainingUnmerged.filter((f) => !f.startsWith(".gsd/"));
+  const markerCandidates = Array.from(new Set([
+    ...nonGsdUnmerged,
+    ...nativeLsFiles(basePath, "."),
+  ])).filter((f) => !f.startsWith(".gsd/"));
+  const nonGsdMarkerConflicts = markerCandidates.filter((f) =>
+    hasConflictMarkers(join(basePath, f)),
+  );
+  const hasRemainingNonGsdConflicts = nonGsdUnmerged.length > 0 || nonGsdMarkerConflicts.length > 0;
+  if (hasRemainingNonGsdConflicts) {
+    const files = Array.from(new Set([...nonGsdUnmerged, ...nonGsdMarkerConflicts]));
+    logWarning("reconcile", "Leaving stash because non-.gsd conflicts remain after auto-resolution", {
+      files: files.join(", "),
+    });
+    return;
+  }
+
+  dropRecordedStash(basePath, stashRefForDrop);
+}
+
+function dropRecordedStash(basePath: string, stashRefForDrop: string | null): void {
+  if (!stashRefForDrop) {
+    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
+    return;
+  }
+  try {
+    execFileSync("git", ["stash", "drop", stashRefForDrop], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch (err) {
+    logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

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

@@ -0,0 +1,391 @@
+// gsd-pi — Auto-worktree merge module.
+//
+// Owns milestone merge/closeout for auto-worktrees: dirty-state capture, DB
+// reconciliation, integration-branch merge, stash/shelter recovery, publication,
+// and safe teardown.
+
+import { atomicWriteSync } from "./atomic-write.js";
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
+import {
+  MergeConflictError,
+  RUNTIME_EXCLUSION_PATHS,
+} from "./git-service.js";
+import {
+  getMilestone,
+  isDbAvailable,
+} from "./gsd-db.js";
+import {
+  nativeAddAllWithExclusions,
+  nativeCommit,
+  nativeConflictFiles,
+  nativeGetCurrentBranch,
+  nativeMergeRegular,
+  nativeMergeSquash,
+  nativeWorkingTreeStatus,
+} from "./native-git-bridge.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { publishMilestone } from "./publication.js";
+import {
+  autoWorktreeBranch,
+} from "./auto-worktree-branch-lifecycle.js";
+import { createMilestoneDirectoryShelter } from "./auto-worktree-milestone-shelter.js";
+import { getActiveWorkspace } from "./auto-worktree-session-registry.js";
+import {
+  assertNoUnanchoredCodeChangesAfterEmptyMerge,
+  detectMergedCodeFilesChanged,
+} from "./auto-worktree-merge-code-changes.js";
+import { reconcileMilestoneBranchHead } from "./auto-worktree-merge-branch-head.js";
+import { finalizeAlreadyMergedMilestoneIfReachable } from "./auto-worktree-merge-already-merged.js";
+import { cleanupMergedMilestoneWorktree } from "./auto-worktree-merge-cleanup.js";
+import { assertMilestoneDbReadyForMerge } from "./auto-worktree-merge-db-ready.js";
+import { prepareIntegrationBranchForMilestoneMerge } from "./auto-worktree-merge-integration-branch.js";
+import { buildMilestoneMergeMessage } from "./auto-worktree-merge-message.js";
+import { assertMilestoneWorktreeCleanBeforeTeardown } from "./auto-worktree-merge-pre-teardown.js";
+import { createPreMergeStash } from "./auto-worktree-merge-stash.js";
+import {
+  cleanupConflictState,
+  removeMergeStateFiles,
+} from "./worktree-git-recovery.js";
+import { logError, logWarning } from "./workflow-logger.js";
+
+export { _setRestoreEntryFnForTests } from "./auto-worktree-milestone-shelter.js";
+
+
+// ─── Merge Milestone -> Main ───────────────────────────────────────────────
+
+/**
+ * Auto-commit any dirty (uncommitted) state in the given directory.
+ * Returns true if a commit was made, false if working tree was clean.
+ */
+function autoCommitDirtyState(cwd: string): boolean {
+  try {
+    const status = nativeWorkingTreeStatus(cwd);
+    if (!status) return false;
+    nativeAddAllWithExclusions(cwd, RUNTIME_EXCLUSION_PATHS);
+    const result = nativeCommit(
+      cwd,
+      "chore: auto-commit before milestone merge",
+    );
+    return result !== null;
+  } catch (e) {
+    debugLog("autoCommitDirtyState", { error: String(e) });
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Failed to auto-commit dirty worktree state before milestone merge: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}
+
+/**
+ * Squash-merge the milestone branch into main with a rich commit message
+ * listing all completed slices, then tear down the worktree.
+ *
+ * Sequence:
+ *  1. Auto-commit dirty worktree state
+ *  2. chdir to originalBasePath
+ *  3. git checkout main
+ *  4. git merge --squash milestone/<MID>
+ *  5. git commit with rich message
+ *  6. Auto-push if enabled
+ *  7. Delete milestone branch
+ *  8. Remove worktree directory
+ *  9. Clear originalBase
+ *
+ * On merge conflict: throws MergeConflictError.
+ * On "nothing to commit" after squash: safe only if milestone work is already
+ * on the integration branch.  Throws if unanchored code changes would be lost.
+ *
+ * @internal **Do not call directly.** This is the inner squash-merge primitive
+ * for the Worktree Lifecycle Module (ADR-016 phase 2 / A3, issue #5619).
+ * Production callers must go through `WorktreeLifecycle.mergeMilestoneStandalone`
+ * or `WorktreeLifecycle.exitMilestone({ merge: true })`. The export keyword
+ * is preserved for legacy tests and the default transaction adapter; production
+ * wiring depends on `createDefaultMilestoneMergeTransaction()` instead.
+ */
+export function mergeMilestoneToMain(
+  originalBasePath_: string,
+  milestoneId: string,
+  roadmapContent: string,
+): { commitMessage: string; pushed: boolean; prCreated: boolean; codeFilesChanged: boolean } {
+  const worktreeCwd = process.cwd();
+  const milestoneBranch = autoWorktreeBranch(milestoneId);
+
+  // 1. Auto-commit dirty state before leaving.
+  //    Guard: when we entered through an auto-worktree (originalBase is set),
+  //    only auto-commit when cwd is on the milestone branch. In parallel mode,
+  //    cwd may be on the integration branch after a prior merge's
+  //    MergeConflictError left cwd unrestored. Auto-committing on the
+  //    integration branch captures dirty files from OTHER milestones under a
+  //    misleading commit message, contaminating the main branch (#2929).
+  //
+  //    When activeWorkspace is null (branch mode, no worktree), autoCommitDirtyState
+  //    runs unconditionally — the caller is responsible for cwd placement.
+  {
+    let shouldAutoCommit = true;
+    if (getActiveWorkspace() !== null) {
+      try {
+        const currentBranch = nativeGetCurrentBranch(worktreeCwd);
+        shouldAutoCommit = currentBranch === milestoneBranch;
+      } catch {
+        // If we can't determine the branch, skip the auto-commit to be safe
+        shouldAutoCommit = false;
+      }
+    }
+    if (shouldAutoCommit) {
+      autoCommitDirtyState(worktreeCwd);
+    }
+  }
+
+  // Reconcile DB state and prove closeout before leaving worktree context.
+  assertMilestoneDbReadyForMerge({
+    milestoneId,
+    projectRoot: originalBasePath_,
+    worktreeCwd,
+  });
+
+  // 2. Build completed-slice summaries and rich commit message.
+  const { commitMessage, milestoneTitle, sliceSummaries } = buildMilestoneMergeMessage({
+    milestoneId,
+    milestoneBranch,
+    roadmapContent,
+  });
+
+  // 3. chdir to original base
+  // Note: previousCwd captures the cwd at this point — i.e. the worktree cwd
+  // entering the function. Subsequent throws restore to previousCwd, leaving
+  // the caller in worktree-cwd; callers (worktree-resolver) are responsible
+  // for any further cwd movement on the error path.
+  const previousCwd = process.cwd();
+  process.chdir(originalBasePath_);
+
+  // 4/5. Resolve and prepare the integration branch. The integration-branch
+  //      module owns stale metadata fallback, self-merge fail-closed behavior,
+  //      detached HEAD protection, transient state cleanup, and checkout.
+  const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+  const { mainBranch } = prepareIntegrationBranchForMilestoneMerge({
+    milestoneBranch,
+    milestoneId,
+    prefs,
+    previousCwd,
+    projectRoot: originalBasePath_,
+  });
+
+  // 6b. Reconcile worktree HEAD with milestone branch ref (#1846).
+  //     The branch-head module owns the data-loss guard: fast-forward stale
+  //     branch refs to detached worktree commits, and fail loudly on divergence.
+  reconcileMilestoneBranchHead({
+    projectRoot: originalBasePath_,
+    worktreeCwd,
+    milestoneBranch,
+    previousCwd,
+  });
+
+  // Already regular-merged milestones can skip the squash path and proceed to cleanup (#5831).
+  const alreadyMerged = finalizeAlreadyMergedMilestoneIfReachable({
+    projectRoot: originalBasePath_,
+    milestoneId,
+    milestoneBranch,
+    mainBranch,
+    previousCwd,
+    commitMessage,
+  });
+  if (alreadyMerged) return alreadyMerged;
+
+  // 7. Shelter queued milestone directories before the squash merge (#2505).
+  // MUST run before the pre-merge stash so queued CONTEXT files are not swept
+  // into a stash that may later fail to pop and strand user work.
+  const milestoneDirectoryShelter = createMilestoneDirectoryShelter(
+    originalBasePath_,
+    milestoneId,
+    getMilestone(milestoneId)?.title,
+  );
+
+  // 7a. Stash pre-existing dirty files so the squash merge is not blocked by
+  //     unrelated local changes (#2151). The stash module also owns Windows DB
+  //     handle cycling and later stash-pop conflict recovery.
+  const preMergeStash = createPreMergeStash(
+    originalBasePath_,
+    milestoneId,
+    process.platform === "win32" && isDbAvailable(),
+  );
+  preMergeStash.stash();
+
+  // 7b. Clean up stale merge state before attempting the merge (#2912).
+  // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
+  // or interrupted operation) causes git merge to refuse with
+  // "fatal: You have not concluded your merge (MERGE_HEAD exists)".
+  // Defensively remove merge artifacts before starting.
+  removeMergeStateFiles(originalBasePath_, "pre-merge");
+
+  // 8. Merge — respect merge_strategy preference (#549).
+  // "squash" (default): stages changes without a merge commit; caller commits.
+  // "merge": --no-ff --no-commit so caller can supply the commit message while
+  // git records a real merge commit (MERGE_HEAD present when nativeCommit runs).
+  const effectiveStrategy = prefs.merge_strategy === "merge" ? "merge" : "squash";
+  const mergeResult = effectiveStrategy === "merge"
+    ? nativeMergeRegular(originalBasePath_, milestoneBranch)
+    : nativeMergeSquash(originalBasePath_, milestoneBranch);
+  preMergeStash.reopenDbAfterMerge();
+
+  if (!mergeResult.success) {
+    // Dirty working tree — the merge was rejected before it started (e.g.
+    // untracked .gsd/ files left by syncStateToProjectRoot).  Preserve the
+    // milestone branch so commits are not lost.
+    if (mergeResult.conflicts.includes("__dirty_working_tree__")) {
+      // Defensively clean merge state — the native path may leave MERGE_HEAD
+      // even when the merge is rejected (#2912).
+      removeMergeStateFiles(originalBasePath_, "dirty-tree rejection");
+
+      // Pop stash before throwing so local work is not lost.
+      preMergeStash.restoreForMergeFailure();
+      milestoneDirectoryShelter.restore();
+      // Restore cwd so the caller is not stranded on the integration branch
+      process.chdir(previousCwd);
+      // Surface the actual dirty filenames from git stderr instead of
+      // generically blaming .gsd/ (#2151).
+      const fileList = mergeResult.dirtyFiles?.length
+        ? `Dirty files:\n${mergeResult.dirtyFiles.map((f) => `  ${f}`).join("\n")}`
+        : `Check \`git status\` in the project root for details.`;
+      throw new GSDError(
+        GSD_GIT_ERROR,
+        `${effectiveStrategy === "merge" ? "Merge" : "Squash merge"} of ${milestoneBranch} rejected: working tree has dirty or untracked files ` +
+          `that conflict with the merge. ${fileList}`,
+      );
+    }
+
+    // Check for conflicts — use merge result first, fall back to nativeConflictFiles
+    const conflictedFiles =
+      mergeResult.conflicts.length > 0
+        ? mergeResult.conflicts
+        : nativeConflictFiles(originalBasePath_);
+
+    if (conflictedFiles.length > 0) {
+      // Separate auto-resolvable conflicts (GSD state files + build artifacts)
+      // from real code conflicts. GSD state files diverge between branches
+      // during normal operation. Build artifacts are machine-generated and
+      // regenerable. Both are safe to accept from the milestone branch.
+      const { resolved: autoResolved, remaining: codeConflicts } = autoResolveSafeConflictPaths(
+        originalBasePath_,
+        conflictedFiles,
+      );
+      if (autoResolved.length > 0) {
+        logWarning("worktree", `auto-resolved safe merge conflicts: ${autoResolved.join(", ")}`);
+      }
+
+      // If there are still real code conflicts, escalate
+      if (codeConflicts.length > 0) {
+        cleanupConflictState(originalBasePath_);
+
+        // Pop stash before throwing so local work is not lost (#2151).
+        preMergeStash.restoreForMergeFailure();
+        milestoneDirectoryShelter.restore();
+        // Restore cwd so the caller is not stranded on the integration branch.
+        // Without this, the next mergeMilestoneToMain call in a parallel merge
+        // sequence uses process.cwd() (now the project root) as worktreeCwd,
+        // causing autoCommitDirtyState to commit unrelated milestone files to
+        // the integration branch (#2929).
+        process.chdir(previousCwd);
+        throw new MergeConflictError(
+          codeConflicts,
+          effectiveStrategy,
+          milestoneBranch,
+          mainBranch,
+        );
+      }
+    }
+    // No conflicts detected — possibly "already up to date", fall through to commit
+  }
+
+  // 9. Commit (handle nothing-to-commit gracefully)
+  const commitResult = nativeCommit(originalBasePath_, commitMessage);
+  const nothingToCommit = commitResult === null;
+
+  // 9a. Clean up merge state files left by git merge --squash (#1853, #2912).
+  // git only removes SQUASH_MSG when the commit reads it directly (plain
+  // `git commit`).  nativeCommit uses `-F -` (stdin) or libgit2, neither
+  // of which trigger git's SQUASH_MSG cleanup.  MERGE_HEAD is created by
+  // libgit2's merge even in squash mode and is not removed by nativeCommit.
+  // If left on disk, doctor reports `corrupt_merge_state` on every subsequent run.
+  removeMergeStateFiles(originalBasePath_, "post-commit");
+
+  // 9a-ii. Restore stashed files now that the merge+commit is complete (#2151).
+  preMergeStash.restoreAfterCommit();
+
+  // 9a-iii. Restore sheltered queued milestone directories (#2505).
+  milestoneDirectoryShelter.restore();
+
+  // 9b. Safety check (#1792): if nothing was committed, verify the milestone
+  // work is already on the integration branch before allowing teardown.
+  try {
+    assertNoUnanchoredCodeChangesAfterEmptyMerge(
+      originalBasePath_,
+      mainBranch,
+      milestoneBranch,
+      effectiveStrategy,
+      nothingToCommit,
+    );
+  } catch (err) {
+    process.chdir(previousCwd);
+    throw err;
+  }
+
+  // 9c. Detect whether any non-.gsd/ code files were actually merged (#1906).
+  const codeFilesChanged = detectMergedCodeFilesChanged(originalBasePath_, nothingToCommit);
+
+  const finalizeMilestoneCleanup = (): void => {
+    cleanupMergedMilestoneWorktree({
+      projectRoot: originalBasePath_,
+      milestoneId,
+      milestoneBranch,
+      previousCwd,
+      chdirWarningContext: "after merge",
+    });
+  };
+
+  let shouldCleanup = false;
+  try {
+    // 10/9b. Publication (auto-push / draft PR) — Publication module seam (ADR-034).
+    const publication = publishMilestone({
+      basePath: originalBasePath_,
+      milestoneId,
+      milestoneTitle,
+      integrationBranch: mainBranch,
+      milestoneBranch,
+      sliceSummaries,
+      nothingToCommit,
+      prefs: {
+        autoPush: prefs.auto_push === true,
+        autoPr: prefs.auto_pr === true,
+        remote: prefs.remote,
+        prTargetBranch: prefs.pr_target_branch,
+      },
+    });
+    const { pushed, prCreated } = publication;
+
+    // 11. Guard removed — step 9b (#1792) now handles this with a smarter check:
+    //     throws only when the milestone has unanchored code changes, passes
+    //     through when the code is genuinely already on the integration branch.
+
+    // 11a. Pre-teardown safety net (#1853): preserve the milestone branch if
+    // the source worktree still has uncommitted changes after the merge commit.
+    assertMilestoneWorktreeCleanBeforeTeardown({
+      milestoneBranch,
+      previousCwd,
+      worktreeCwd,
+    });
+
+    shouldCleanup = true;
+    return { commitMessage, pushed, prCreated, codeFilesChanged };
+  } finally {
+    if (shouldCleanup) {
+      finalizeMilestoneCleanup();
+    } else {
+      logWarning(
+        "worktree",
+        `Skipping worktree cleanup for ${milestoneBranch}; merge did not reach safe-cleanup point and milestone work is preserved for manual recovery.`,
+      );
+    }
+  }
+}