@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

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

@@ -0,0 +1,132 @@
+// gsd-pi — Milestone merge cleanup module.
+//
+// Owns the teardown ordering after a milestone has safely reached the
+// integration branch: clear transient state, remove the worktree, delete the
+// milestone branch only after removal succeeds, clear process-local workspace
+// state, and anchor cwd back at the project root.
+
+import { nativeBranchDelete } from "./native-git-bridge.js";
+import { clearProjectRootStateFiles } from "./auto-worktree-cleanup.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { removeWorktree } from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
+
+export interface MilestoneMergeCleanupRequest {
+  projectRoot: string;
+  milestoneId: string;
+  milestoneBranch: string;
+  previousCwd: string;
+  clearProjectRootState?: boolean;
+  chdirWarningContext?: string;
+}
+
+export interface MilestoneMergeCleanupResult {
+  worktreeRemoved: boolean;
+  branchDeleteAttempted: boolean;
+  activeWorkspaceCleared: boolean;
+}
+
+interface MilestoneMergeCleanupDeps {
+  clearProjectRootStateFiles: typeof clearProjectRootStateFiles;
+  removeWorktree: typeof removeWorktree;
+  nativeBranchDelete: typeof nativeBranchDelete;
+  setActiveWorkspace: typeof setActiveWorkspace;
+  nudgeGitBranchCache: typeof nudgeGitBranchCache;
+  chdir: (path: string) => void;
+}
+
+const defaultDeps: MilestoneMergeCleanupDeps = {
+  clearProjectRootStateFiles,
+  removeWorktree,
+  nativeBranchDelete,
+  setActiveWorkspace,
+  nudgeGitBranchCache,
+  chdir: process.chdir.bind(process),
+};
+
+let deps: MilestoneMergeCleanupDeps = defaultDeps;
+
+export function _setMilestoneCleanupDepsForTests(overrides: Partial<MilestoneMergeCleanupDeps>): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMilestoneCleanupDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+export function cleanupMergedMilestoneWorktree(
+  request: MilestoneMergeCleanupRequest,
+): MilestoneMergeCleanupResult {
+  const {
+    projectRoot,
+    milestoneId,
+    milestoneBranch,
+    previousCwd,
+    clearProjectRootState = false,
+    chdirWarningContext = "after milestone cleanup",
+  } = request;
+
+  if (clearProjectRootState) {
+    try {
+      deps.clearProjectRootStateFiles(projectRoot, milestoneId);
+    } catch (err) {
+      logWarning("worktree", `clearProjectRootStateFiles failed during milestone cleanup: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  let worktreeRemoved = true;
+  try {
+    worktreeRemoved = deps.removeWorktree(projectRoot, milestoneId, {
+      branch: milestoneBranch,
+      deleteBranch: false,
+    });
+  } catch (err) {
+    worktreeRemoved = false;
+    logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!worktreeRemoved) {
+    logWarning(
+      "worktree",
+      `Skipping milestone branch deletion for ${milestoneBranch}; worktree removal was aborted to preserve uncommitted milestone work.`,
+    );
+    deps.nudgeGitBranchCache(previousCwd);
+    chdirToProjectRoot(projectRoot, chdirWarningContext);
+    return {
+      worktreeRemoved: false,
+      branchDeleteAttempted: false,
+      activeWorkspaceCleared: false,
+    };
+  }
+
+  try {
+    deps.nativeBranchDelete(projectRoot, milestoneBranch);
+  } catch (err) {
+    logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  deps.setActiveWorkspace(null);
+  deps.nudgeGitBranchCache(previousCwd);
+  chdirToProjectRoot(projectRoot, chdirWarningContext);
+
+  return {
+    worktreeRemoved: true,
+    branchDeleteAttempted: true,
+    activeWorkspaceCleared: true,
+  };
+}
+
+function chdirToProjectRoot(projectRoot: string, context: string): void {
+  try {
+    deps.chdir(projectRoot);
+  } catch (err) {
+    logWarning("worktree", `chdir to project root ${context} failed: ${err instanceof Error ? err.message : String(err)}`);
+    debugLog("mergeMilestoneToMain", {
+      phase: "post-merge-chdir-failed",
+      target: projectRoot,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

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

@@ -0,0 +1,71 @@
+// gsd-pi — Code-change safety checks for auto-worktree merge closeout.
+//
+// Owns the git diff policy that decides whether a completed milestone actually
+// changed user code, and whether an empty merge result is safe to clean up.
+
+import { execFileSync } from "node:child_process";
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { nativeDiffNumstat } from "./native-git-bridge.js";
+import { logWarning } from "./workflow-logger.js";
+
+const GIT_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+export function assertNoUnanchoredCodeChangesAfterEmptyMerge(
+  basePath: string,
+  mainBranch: string,
+  milestoneBranch: string,
+  effectiveStrategy: "merge" | "squash",
+  nothingToCommit: boolean,
+): void {
+  if (!nothingToCommit) return;
+
+  const codeChanges = nativeDiffNumstat(basePath, mainBranch, milestoneBranch)
+    .filter((entry) => !entry.path.startsWith(".gsd/"));
+  if (codeChanges.length === 0) return;
+
+  throw new GSDError(
+    GSD_GIT_ERROR,
+    `${effectiveStrategy === "merge" ? "Merge" : "Squash merge"} produced nothing to commit but milestone branch "${milestoneBranch}" ` +
+      `has ${codeChanges.length} code file(s) not on "${mainBranch}". ` +
+      `Aborting worktree teardown to prevent data loss.`,
+  );
+}
+
+export function detectMergedCodeFilesChanged(basePath: string, nothingToCommit: boolean): boolean {
+  if (nothingToCommit) return false;
+
+  try {
+    const diffTreeOutput = execFileSync(
+      "git",
+      ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"],
+      { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trim();
+    return containsCodeFile(diffTreeOutput);
+  } catch (err) {
+    return detectCodeFilesChangedFromEmptyTree(basePath, err);
+  }
+}
+
+function detectCodeFilesChangedFromEmptyTree(basePath: string, originalError: unknown): boolean {
+  try {
+    const fallbackOutput = execFileSync(
+      "git",
+      ["diff", "--name-only", GIT_EMPTY_TREE, "HEAD"],
+      { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+    ).trim();
+    return containsCodeFile(fallbackOutput);
+  } catch {
+    // Truly unable to determine — assume code was changed to avoid silent data loss.
+    logWarning(
+      "worktree",
+      `diff-tree and empty-tree fallback both failed (assuming code changed): ${originalError instanceof Error ? originalError.message : String(originalError)}`,
+    );
+    return true;
+  }
+}
+
+function containsCodeFile(output: string): boolean {
+  const files = output ? output.split("\n").filter(Boolean) : [];
+  return files.some((file) => !file.startsWith(".gsd/"));
+}

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

@@ -0,0 +1,112 @@
+// gsd-pi — Milestone merge DB readiness guard.
+//
+// Owns the invariant that, before leaving worktree context for a milestone
+// merge, the project DB is the active DB, worktree DB state is reconciled, and
+// canonical closeout state proves the milestone is safe to merge.
+
+import { join } from "node:path";
+
+import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON } from "./closeout-consistency-gate.js";
+import {
+  closeWorkflowDatabase,
+  getWorkflowDatabasePath,
+  openWorkflowDatabasePath,
+} from "./db-workspace.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  isDbAvailable,
+  reconcileWorktreeDb,
+} from "./gsd-db.js";
+import {
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { _shouldReconcileWorktreeDb } from "./auto-worktree-cleanup.js";
+import { logError } from "./workflow-logger.js";
+
+export interface MilestoneDbReadyRequest {
+  milestoneId: string;
+  projectRoot: string;
+  worktreeCwd: string;
+}
+
+interface MergeDbReadyDeps {
+  closeWorkflowDatabase: typeof closeWorkflowDatabase;
+  formatCloseoutProofBlock: typeof formatCloseoutProofBlock;
+  getWorkflowDatabasePath: typeof getWorkflowDatabasePath;
+  isDbAvailable: typeof isDbAvailable;
+  logError: typeof logError;
+  openWorkflowDatabasePath: typeof openWorkflowDatabasePath;
+  proveMilestoneCloseout: typeof proveMilestoneCloseout;
+  reconcileWorktreeDb: typeof reconcileWorktreeDb;
+  resolveGsdPathContract: typeof resolveGsdPathContract;
+  shouldReconcileWorktreeDb: typeof _shouldReconcileWorktreeDb;
+}
+
+const defaultDeps: MergeDbReadyDeps = {
+  closeWorkflowDatabase,
+  formatCloseoutProofBlock,
+  getWorkflowDatabasePath,
+  isDbAvailable,
+  logError,
+  openWorkflowDatabasePath,
+  proveMilestoneCloseout,
+  reconcileWorktreeDb,
+  resolveGsdPathContract,
+  shouldReconcileWorktreeDb: _shouldReconcileWorktreeDb,
+};
+
+let deps: MergeDbReadyDeps = defaultDeps;
+
+export function _setMergeDbReadyDepsForTests(
+  overrides: Partial<MergeDbReadyDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMergeDbReadyDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function reconcileWorktreeDatabase(request: MilestoneDbReadyRequest): void {
+  const { milestoneId, projectRoot, worktreeCwd } = request;
+  const contract = deps.resolveGsdPathContract(worktreeCwd, projectRoot);
+  const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+  const mainDbPath = contract.projectDb;
+
+  try {
+    const activeDbPath = deps.getWorkflowDatabasePath();
+    if (activeDbPath && deps.shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
+      deps.closeWorkflowDatabase();
+      if (!deps.openWorkflowDatabasePath(mainDbPath)) {
+        throw new Error(`cannot open project DB at ${mainDbPath}`);
+      }
+    }
+    if (deps.shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
+      deps.reconcileWorktreeDb(mainDbPath, worktreeDbPath);
+    }
+  } catch (err) {
+    const message = `DB reconciliation failed before milestone ${milestoneId} merge: ${err instanceof Error ? err.message : String(err)}`;
+    deps.logError("worktree", message);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`,
+    );
+  }
+}
+
+function assertCloseoutProof(milestoneId: string): void {
+  const closeoutProof = deps.proveMilestoneCloseout(milestoneId);
+  if (!closeoutProof.ok) {
+    throw new GSDError(GSD_GIT_ERROR, deps.formatCloseoutProofBlock(closeoutProof));
+  }
+}
+
+export function assertMilestoneDbReadyForMerge(
+  request: MilestoneDbReadyRequest,
+): void {
+  if (!deps.isDbAvailable()) return;
+  reconcileWorktreeDatabase(request);
+  assertCloseoutProof(request.milestoneId);
+}

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

@@ -0,0 +1,99 @@
+// gsd-pi — Milestone merge integration-branch preparation.
+//
+// Owns branch-selection safety before the merge transaction touches the project
+// root: resolve integration branch, fail closed on self-merge metadata, clear
+// transient milestone state, reject detached HEAD, and checkout when needed.
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import {
+  resolveMilestoneIntegrationBranch,
+} from "./git-service.js";
+import {
+  nativeCheckoutBranch,
+  nativeDetectMainBranch,
+  nativeGetCurrentBranch,
+} from "./native-git-bridge.js";
+import { clearProjectRootStateFiles } from "./auto-worktree-cleanup.js";
+
+export interface PrepareIntegrationBranchRequest {
+  milestoneBranch: string;
+  milestoneId: string;
+  prefs: Parameters<typeof resolveMilestoneIntegrationBranch>[2];
+  previousCwd: string;
+  projectRoot: string;
+}
+
+export interface PreparedIntegrationBranch {
+  mainBranch: string;
+}
+
+interface MergeIntegrationBranchDeps {
+  chdir: typeof process.chdir;
+  clearProjectRootStateFiles: typeof clearProjectRootStateFiles;
+  nativeCheckoutBranch: typeof nativeCheckoutBranch;
+  nativeDetectMainBranch: typeof nativeDetectMainBranch;
+  nativeGetCurrentBranch: typeof nativeGetCurrentBranch;
+  resolveMilestoneIntegrationBranch: typeof resolveMilestoneIntegrationBranch;
+}
+
+const defaultDeps: MergeIntegrationBranchDeps = {
+  chdir: process.chdir.bind(process),
+  clearProjectRootStateFiles,
+  nativeCheckoutBranch,
+  nativeDetectMainBranch,
+  nativeGetCurrentBranch,
+  resolveMilestoneIntegrationBranch,
+};
+
+let deps: MergeIntegrationBranchDeps = defaultDeps;
+
+export function _setMergeIntegrationBranchDepsForTests(
+  overrides: Partial<MergeIntegrationBranchDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMergeIntegrationBranchDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function normalizeLocalBranchRef(branch: string): string {
+  return branch.startsWith("refs/heads/")
+    ? branch.slice("refs/heads/".length)
+    : branch;
+}
+
+export function prepareIntegrationBranchForMilestoneMerge(
+  request: PrepareIntegrationBranchRequest,
+): PreparedIntegrationBranch {
+  const { milestoneBranch, milestoneId, prefs, previousCwd, projectRoot } = request;
+  const branchResolution = deps.resolveMilestoneIntegrationBranch(projectRoot, milestoneId, prefs);
+  const mainBranch = branchResolution.effectiveBranch ?? deps.nativeDetectMainBranch(projectRoot);
+
+  if (normalizeLocalBranchRef(mainBranch) === milestoneBranch) {
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Resolved integration branch "${mainBranch}" is the same ref as milestone branch ` +
+      `"${milestoneBranch}" — refusing to self-merge. ${branchResolution.reason}. ` +
+      `Repair milestone integration metadata before retrying milestone completion.`,
+    );
+  }
+
+  deps.clearProjectRootStateFiles(projectRoot, milestoneId);
+
+  const currentBranchAtBase = deps.nativeGetCurrentBranch(projectRoot);
+  if (!currentBranchAtBase || currentBranchAtBase.length === 0) {
+    deps.chdir(previousCwd);
+    throw new GSDError(
+      GSD_GIT_ERROR,
+      `Project root is in detached HEAD state — cannot perform milestone merge. ` +
+      `Checkout an integration branch (e.g. \`git checkout ${mainBranch}\`) before resuming.`,
+    );
+  }
+  if (currentBranchAtBase !== mainBranch) {
+    deps.nativeCheckoutBranch(projectRoot, mainBranch);
+  }
+
+  return { mainBranch };
+}

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

@@ -0,0 +1,166 @@
+// gsd-pi — Milestone merge commit-message construction.
+//
+// Owns the completed-slice/task summary and milestone title fallback policy used
+// by auto-worktree milestone merge commits and publication summaries.
+
+import {
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+} from "./gsd-db.js";
+
+interface CompletedTaskSummary {
+  id: string;
+  title: string;
+}
+
+interface CompletedSliceSummary {
+  id: string;
+  title: string;
+  tasks: CompletedTaskSummary[];
+}
+
+export interface MilestoneMergeMessageRequest {
+  milestoneId: string;
+  milestoneBranch: string;
+  roadmapContent: string;
+}
+
+export interface MilestoneMergeMessage {
+  commitMessage: string;
+  milestoneTitle: string;
+  sliceSummaries: string[];
+}
+
+interface MilestoneMergeMessageDeps {
+  isDbAvailable: typeof isDbAvailable;
+  getMilestone: typeof getMilestone;
+  getMilestoneSlices: typeof getMilestoneSlices;
+  getSliceTasks: typeof getSliceTasks;
+}
+
+const defaultDeps: MilestoneMergeMessageDeps = {
+  isDbAvailable,
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+};
+
+let deps: MilestoneMergeMessageDeps = defaultDeps;
+
+export function _setMilestoneMergeMessageDepsForTests(
+  overrides: Partial<MilestoneMergeMessageDeps>,
+): void {
+  deps = { ...defaultDeps, ...overrides };
+}
+
+export function _resetMilestoneMergeMessageDepsForTests(): void {
+  deps = defaultDeps;
+}
+
+function stripGsdDisplayPrefix(value: string | undefined | null, id: string): string | undefined {
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+
+  const lower = raw.toLowerCase();
+  const idLower = id.toLowerCase();
+  if (lower.startsWith(`${idLower}:`)) {
+    return raw.slice(id.length + 1).trim() || undefined;
+  }
+  return raw;
+}
+
+function getDbCompletedSlices(milestoneId: string): CompletedSliceSummary[] {
+  if (!deps.isDbAvailable()) return [];
+  return deps.getMilestoneSlices(milestoneId)
+    .filter((slice) => slice.status === "complete")
+    .map((slice) => ({
+      id: slice.id,
+      title: stripGsdDisplayPrefix(slice.title, slice.id) ?? slice.id,
+      tasks: deps.getSliceTasks(milestoneId, slice.id)
+        .filter((task) => task.status === "complete")
+        .map((task) => ({
+          id: task.id,
+          title: stripGsdDisplayPrefix(task.title, task.id) ?? task.id,
+        })),
+    }));
+}
+
+function getRoadmapCompletedSlices(roadmapContent: string): CompletedSliceSummary[] {
+  if (!roadmapContent) return [];
+
+  const completedSlices: CompletedSliceSummary[] = [];
+  const sliceRe = /- \[x\] \*\*(\w+):\s*(.+?)\*\*/gi;
+  let match: RegExpExecArray | null;
+  while ((match = sliceRe.exec(roadmapContent)) !== null) {
+    completedSlices.push({ id: match[1], title: match[2], tasks: [] });
+  }
+  return completedSlices;
+}
+
+function getCompletedSlices(
+  milestoneId: string,
+  roadmapContent: string,
+): CompletedSliceSummary[] {
+  const dbCompletedSlices = getDbCompletedSlices(milestoneId);
+  if (dbCompletedSlices.length > 0) return dbCompletedSlices;
+  return getRoadmapCompletedSlices(roadmapContent);
+}
+
+function getRoadmapMilestoneTitle(milestoneId: string, roadmapContent: string): string | undefined {
+  if (!roadmapContent) return undefined;
+  const titleMatch = roadmapContent.match(new RegExp(`^#\\s+${milestoneId}:\\s*(.+)`, "m"));
+  return titleMatch?.[1]?.trim() || undefined;
+}
+
+function getMilestoneTitle(milestoneId: string, roadmapContent: string): string {
+  const dbMilestone = deps.getMilestone(milestoneId);
+  const dbTitle = stripGsdDisplayPrefix(dbMilestone?.title, milestoneId);
+  return dbTitle ?? getRoadmapMilestoneTitle(milestoneId, roadmapContent) ?? milestoneId;
+}
+
+function buildCommitMessage(request: {
+  completedSlices: CompletedSliceSummary[];
+  milestoneBranch: string;
+  milestoneId: string;
+  milestoneTitle: string;
+}): string {
+  const { completedSlices, milestoneBranch, milestoneId, milestoneTitle } = request;
+  const subject = `feat: ${milestoneTitle}`;
+  const milestoneContext = milestoneTitle === milestoneId
+    ? `Milestone: ${milestoneId}`
+    : `Milestone: ${milestoneId} - ${milestoneTitle}`;
+
+  if (completedSlices.length === 0) {
+    return `${subject}\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
+  }
+
+  const sliceLines = completedSlices
+    .map((slice) => `- ${slice.id}: ${slice.title}`)
+    .join("\n");
+  const taskLines = completedSlices
+    .flatMap((slice) => slice.tasks.map((task) => `- ${slice.id}/${task.id}: ${task.title}`))
+    .join("\n");
+  const taskBlock = taskLines ? `\n\nCompleted tasks:\n${taskLines}` : "";
+
+  return `${subject}\n\nCompleted slices:\n${sliceLines}${taskBlock}\n\n${milestoneContext}\nGSD-Milestone: ${milestoneId}\nBranch: ${milestoneBranch}`;
+}
+
+export function buildMilestoneMergeMessage(
+  request: MilestoneMergeMessageRequest,
+): MilestoneMergeMessage {
+  const { milestoneId, milestoneBranch, roadmapContent } = request;
+  const completedSlices = getCompletedSlices(milestoneId, roadmapContent);
+  const milestoneTitle = getMilestoneTitle(milestoneId, roadmapContent);
+  return {
+    commitMessage: buildCommitMessage({
+      completedSlices,
+      milestoneBranch,
+      milestoneId,
+      milestoneTitle,
+    }),
+    milestoneTitle,
+    sliceSummaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+  };
+}

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),
+    });
+  }
+}