@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -8,28 +8,32 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, rmSync, unlinkSync, lstatSync as lstatSyncFn, } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve, sep as pathSep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
-import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, closeDatabase, openDatabase, getDbPath, } from "./gsd-db.js";
+import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, getSliceTasks, } from "./gsd-db.js";
+import { closeWorkflowDatabase, getWorkflowDatabasePath, openWorkflowDatabasePath, } from "./db-workspace.js";
 import { execFileSync } from "node:child_process";
-import { gsdRoot, resolveGsdPathContract } from "./paths.js";
-import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
+import { canonicalPhaseDirName, gsdRoot, milestonesDir, resolveGsdPathContract, resolveMilestonePath, } from "./paths.js";
+import { createWorktree, removeWorktree, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
+import { worktreePathFor } from "./worktree-placement.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
-import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+import { isGsdWorktreePath, projectRootFromWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 import { autoResolveSafeConflictPaths } from "./git-conflict-resolve.js";
-import { MergeConflictError, createDraftPR, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
-import { buildPrEvidence } from "./pr-evidence.js";
+import { MergeConflictError, readIntegrationBranch, resolveMilestoneIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
+import { publishMilestone } from "./publication.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
+import { checkoutBranchWithStashGuard, cleanupConflictState, gsdJsonlFilesWithConflictMarkers, hasConflictMarkers, popStashByRef, removeMergeStateFiles, stashAlreadyExistsFilesFromError, stashRefFromError, } from "./worktree-git-recovery.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { classifyProject } from "./detection.js";
-import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeConflictFiles, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeMergeAbort, nativeWorktreeList, nativeLsFiles, } from "./native-git-bridge.js";
-import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON, checkCloseoutConsistencyGate, formatCloseoutConsistencyBlock, } from "./closeout-consistency-gate.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeWorkingTreeStatus, nativeAddAllWithExclusions, nativeCommit, nativeCheckoutBranch, nativeMergeSquash, nativeMergeRegular, nativeConflictFiles, nativeAddPaths, nativeRmForce, nativeBranchDelete, nativeBranchForceReset, nativeBranchExists, nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, nativeWorktreeList, nativeLsFiles, } from "./native-git-bridge.js";
+import { CLOSEOUT_CONSISTENCY_BLOCKED_REASON, } from "./closeout-consistency-gate.js";
+import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
 import { gsdHome } from "./gsd-home.js";
 import { createWorkspace } from "./workspace.js";
-import { _finalizeProjectionForMergeImpl, _projectRootToWorktreeImpl, _projectWorktreeToRootImpl, } from "./worktree-state-projection.js";
+import { WorktreeStateProjection } from "./worktree-state-projection.js";
 const PROJECT_PREFERENCES_FILE = "PREFERENCES.md";
 const LEGACY_PROJECT_PREFERENCES_FILE = "preferences.md";
 const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
@@ -59,111 +63,6 @@ const ROOT_STATE_FILES = [
     // Back-sync (worktree → main) must NEVER overwrite the project root's copy
     // because the project root is authoritative for preferences (#2684).
 ];
-/**
- * Pop a stash entry by tracking the unique marker embedded in its message so
- * concurrent stash operations against the same project root cannot cause us to
- * pop the wrong entry.
- *
- * If `stashMarker` is null or no longer present in the stash list (e.g. a
- * concurrent process popped/dropped it), leaves the stash list untouched and
- * returns null.
- *
- * Throws on pop failure so callers can handle conflict cases the same way
- * they would with the prior `git stash pop` form. When throwing after a
- * targeted pop attempt, the error is annotated with the targeted stash ref.
- *
- * (Issue #4980 HIGH-6)
- */
-function popStashByRef(basePath, stashMarker) {
-    let popArg = null;
-    if (stashMarker) {
-        try {
-            const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
-                cwd: basePath,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            }).trim().split("\n").filter(Boolean);
-            for (const entry of list) {
-                const [ref, subject] = entry.split("\0");
-                if (ref && subject?.includes(stashMarker)) {
-                    popArg = ref;
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            logWarning("worktree", `stash list lookup failed; leaving stash untouched: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    if (!popArg) {
-        logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic pop");
-        return null;
-    }
-    try {
-        execFileSync("git", ["stash", "pop", popArg], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-    }
-    catch (err) {
-        if (err && typeof err === "object") {
-            err.stashRef = popArg;
-        }
-        throw err;
-    }
-    return popArg;
-}
-/**
- * Extract a stash ref annotation injected by popStashByRef() when git stash
- * pop fails and we need to conditionally drop the exact stash entry later.
- */
-function stashRefFromError(err) {
-    if (!err || typeof err !== "object")
-        return null;
-    const stashRef = err.stashRef;
-    return typeof stashRef === "string" && stashRef.length > 0 ? stashRef : null;
-}
-function stashAlreadyExistsFilesFromError(err) {
-    if (!err || typeof err !== "object")
-        return [];
-    const stderr = err.stderr;
-    const stderrText = typeof stderr === "string"
-        ? stderr
-        : stderr instanceof Uint8Array
-            ? Buffer.from(stderr).toString("utf-8")
-            : "";
-    const message = err instanceof Error ? err.message : String(err);
-    const text = `${stderrText}\n${message}`;
-    const files = new Set();
-    for (const line of text.split("\n")) {
-        const m = line.match(/^(.*?)\s+already exists, no checkout\s*$/i);
-        if (!m)
-            continue;
-        const filePath = m[1]?.trim();
-        if (filePath)
-            files.add(filePath);
-    }
-    return [...files];
-}
-/**
- * Detect whether an on-disk file still contains unresolved merge conflict
- * markers from a failed stash-pop or merge attempt.
- *
- * Returns false when the file cannot be read.
- */
-function hasConflictMarkers(filePath) {
-    try {
-        const content = readFileSync(filePath, "utf-8");
-        return content.includes("<<<<<<<") && content.includes("=======") && content.includes(">>>>>>>");
-    }
-    catch {
-        return false;
-    }
-}
-function gsdJsonlFilesWithConflictMarkers(basePath) {
-    return nativeLsFiles(basePath, ".gsd/*.jsonl").filter((f) => hasConflictMarkers(join(basePath, f)));
-}
 /**
  * Check if two filesystem paths resolve to the same real location.
  * Returns false if either path cannot be resolved (e.g. doesn't exist).
@@ -242,6 +141,16 @@ function stripGsdDisplayPrefix(value, id) {
 // ─── Module State ──────────────────────────────────────────────────────────
 /** Active workspace registry — replaces the legacy `originalBase` singleton. */
 let activeWorkspace = null;
+/**
+ * Optional override for the shelter restore copy step (milestone merge #2505).
+ * Production leaves this null so restoreShelter uses the real cpSync; tests
+ * inject a throwing function to deterministically exercise the best-effort
+ * failure path (auto-worktree.ts:1809) and the shelter-retention guarantee,
+ * which is otherwise unreachable because shelter and restore run synchronously
+ * in one mergeMilestoneToMain call (the filesystem cannot change between them).
+ * @internal
+ */
+let _restoreEntryFn = null;
 function setActiveWorkspace(ws) {
     activeWorkspace = ws;
 }
@@ -284,19 +193,6 @@ function gitPathspecForWorktreePath(basePath, targetPath) {
 export function _gitPathspecForWorktreePath(basePath, targetPath) {
     return gitPathspecForWorktreePath(basePath, targetPath);
 }
-function gitRemoteExists(basePath, remote) {
-    try {
-        execFileSync("git", ["remote", "get-url", remote], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function findRegularMergeChangedPaths(basePath, milestoneBranch, mainBranch) {
     const changedPaths = new Set();
     let mergeLog = "";
@@ -414,55 +310,26 @@ export const SAFE_AUTO_RESOLVE_PATTERNS = [
     /\/__pycache__\//,
     /\.DS_Store$/,
     /\.map$/,
+    // Regenerable dependency lockfiles. These are fully derivable from their
+    // manifests by the package manager, so accepting the merge side during
+    // auto-resolve clears the conflict markers without losing meaningful edits —
+    // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
+    /(?:^|\/)pnpm-lock\.yaml$/,
+    /(?:^|\/)package-lock\.json$/,
+    /(?:^|\/)npm-shrinkwrap\.json$/,
+    /(?:^|\/)yarn\.lock$/,
+    /(?:^|\/)bun\.lockb?$/,
+    /(?:^|\/)Cargo\.lock$/,
+    /(?:^|\/)composer\.lock$/,
+    /(?:^|\/)Gemfile\.lock$/,
+    /(?:^|\/)Pipfile\.lock$/,
+    /(?:^|\/)poetry\.lock$/,
 ];
 /** Returns true if the file path is safe to auto-resolve during merge.
- * Covers `.gsd/` state files and common build artifacts. */
+ * Covers `.gsd/` state files, common build artifacts, and regenerable
+ * dependency lockfiles. */
 export const isSafeToAutoResolve = (filePath) => filePath.startsWith(".gsd/") ||
     SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
-function removeMergeStateFiles(basePath, contextLabel) {
-    try {
-        for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
-            const rawPath = execFileSync("git", ["rev-parse", "--git-path", f], {
-                cwd: basePath,
-                stdio: ["ignore", "pipe", "pipe"],
-                encoding: "utf-8",
-            }).trim();
-            const p = rawPath.length > 0
-                ? (isAbsolute(rawPath) ? rawPath : resolve(basePath, rawPath))
-                : join(resolveGitDir(basePath), f);
-            if (existsSync(p))
-                unlinkSync(p);
-        }
-    }
-    catch (err) {
-        logError("worktree", `${contextLabel} merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function cleanupSquashConflictState(basePath) {
-    // `git merge --squash` conflicts can leave unmerged index entries without
-    // MERGE_HEAD, so merge-abort alone is not enough. Reset the merge index, then
-    // remove merge message files that native/libgit2 paths may have created.
-    try {
-        nativeMergeAbort(basePath);
-    }
-    catch (err) {
-        // Expected for squash conflicts when MERGE_HEAD was never written.
-        debugLog("squash-conflict-cleanup:merge-abort-skipped", {
-            error: err instanceof Error ? err.message : String(err),
-        });
-    }
-    try {
-        execFileSync("git", ["reset", "--merge"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-    }
-    catch (err) {
-        logError("worktree", `git reset --merge failed after squash conflict: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    removeMergeStateFiles(basePath, "squash conflict");
-}
 // ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
 /**
  * Sync milestone artifacts from project root INTO worktree before deriveState.
@@ -478,7 +345,7 @@ function cleanupSquashConflictState(basePath) {
  * the bodies with raw paths.
  */
 export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneId) {
-    _projectRootToWorktreeImpl(projectRoot, worktreePath_, milestoneId);
+    new WorktreeStateProjection().projectRootToWorktreePaths(projectRoot, worktreePath_, milestoneId);
 }
 /**
  * Path-string entry point to WorktreeStateProjection.projectWorktreeToRoot.
@@ -486,7 +353,7 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
  * the projection-invariant tests can exercise the body with raw paths.
  */
 export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
-    _projectWorktreeToRootImpl(worktreePath_, projectRoot, milestoneId);
+    new WorktreeStateProjection().projectWorktreeToRootPaths(worktreePath_, projectRoot, milestoneId);
 }
 // ─── Resource Staleness ───────────────────────────────────────────────────
 /**
@@ -536,19 +403,9 @@ export function checkResourcesStale(versionOnStart) {
  * Returns the corrected base path.
  */
 export function escapeStaleWorktree(base) {
-    // Direct layout: /.gsd/worktrees/
-    const directMarker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-    let idx = base.indexOf(directMarker);
-    if (idx === -1) {
-        // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-        const symlinkRe = new RegExp(`\\${pathSep}\\.gsd\\${pathSep}projects\\${pathSep}[a-f0-9]+\\${pathSep}worktrees\\${pathSep}`);
-        const match = base.match(symlinkRe);
-        if (!match || match.index === undefined)
-            return base;
-        idx = match.index;
-    }
-    // base is inside .gsd/worktrees/<something> — extract the project root
-    const projectRoot = base.slice(0, idx);
+    const projectRoot = projectRootFromWorktreePath(base);
+    if (projectRoot === null)
+        return base;
     // Guard: If the candidate project root's .gsd IS the user-level ~/.gsd,
     // the string-slice heuristic matched the wrong /.gsd/ boundary. This happens
     // when .gsd is a symlink into ~/.gsd/projects/<hash> and process.cwd()
@@ -717,99 +574,102 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
             }
         }
     }
-    // Sync milestones: copy entire milestone directories that are missing
-    const mainMilestonesDir = join(mainGsd, "milestones");
-    const wtMilestonesDir = join(wtGsd, "milestones");
-    if (existsSync(mainMilestonesDir)) {
-        try {
-            mkdirSync(wtMilestonesDir, { recursive: true });
-            const mainMilestones = readdirSync(mainMilestonesDir, {
-                withFileTypes: true,
-            })
-                .filter((d) => d.isDirectory())
-                .map((d) => d.name);
-            for (const mid of mainMilestones) {
-                const srcDir = join(mainMilestonesDir, mid);
-                const dstDir = join(wtMilestonesDir, mid);
-                if (!existsSync(dstDir)) {
-                    // Entire milestone missing from worktree — copy it
-                    try {
-                        cpSync(srcDir, dstDir, { recursive: true });
-                        synced.push(`milestones/${mid}/`);
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+    // Sync milestone/phase trees: copy entire directories that are missing.
+    // Support both flat-phase (phases/) and legacy (milestones/) layouts.
+    for (const layoutSegment of ["phases", "milestones"]) {
+        const mainMilestonesDir = join(mainGsd, layoutSegment);
+        const wtMilestonesDir = join(wtGsd, layoutSegment);
+        if (existsSync(mainMilestonesDir)) {
+            try {
+                mkdirSync(wtMilestonesDir, { recursive: true });
+                const mainMilestones = readdirSync(mainMilestonesDir, {
+                    withFileTypes: true,
+                })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => d.name);
+                for (const mid of mainMilestones) {
+                    const srcDir = join(mainMilestonesDir, mid);
+                    const dstDir = join(wtMilestonesDir, mid);
+                    if (!existsSync(dstDir)) {
+                        // Entire milestone missing from worktree — copy it
+                        try {
+                            cpSync(srcDir, dstDir, { recursive: true });
+                            synced.push(`milestones/${mid}/`);
+                        }
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
-                }
-                else {
-                    // Milestone directory exists but may be missing files (stale snapshot).
-                    // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
-                    try {
-                        const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
-                        for (const f of srcFiles) {
-                            const srcFile = join(srcDir, f);
-                            const dstFile = join(dstDir, f);
-                            if (!existsSync(dstFile)) {
-                                try {
-                                    const srcStat = lstatSyncFn(srcFile);
-                                    if (srcStat.isFile()) {
-                                        cpSync(srcFile, dstFile);
-                                        synced.push(`milestones/${mid}/${f}`);
+                    else {
+                        // Milestone directory exists but may be missing files (stale snapshot).
+                        // Sync individual top-level milestone files (CONTEXT, ROADMAP, RESEARCH, etc.)
+                        try {
+                            const srcFiles = readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".json"));
+                            for (const f of srcFiles) {
+                                const srcFile = join(srcDir, f);
+                                const dstFile = join(dstDir, f);
+                                if (!existsSync(dstFile)) {
+                                    try {
+                                        const srcStat = lstatSyncFn(srcFile);
+                                        if (srcStat.isFile()) {
+                                            cpSync(srcFile, dstFile);
+                                            synced.push(`milestones/${mid}/${f}`);
+                                        }
                                     }
+                                    catch (err) {
+                                        /* non-fatal */
+                                        logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
+                                    }
+                                }
+                            }
+                            // Sync slices directory if it exists in main but not in worktree
+                            const srcSlicesDir = join(srcDir, "slices");
+                            const dstSlicesDir = join(dstDir, "slices");
+                            if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
+                                try {
+                                    cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
+                                    synced.push(`milestones/${mid}/slices/`);
                                 }
                                 catch (err) {
                                     /* non-fatal */
-                                    logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`);
+                                    logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
                                 }
                             }
-                        }
-                        // Sync slices directory if it exists in main but not in worktree
-                        const srcSlicesDir = join(srcDir, "slices");
-                        const dstSlicesDir = join(dstDir, "slices");
-                        if (existsSync(srcSlicesDir) && !existsSync(dstSlicesDir)) {
-                            try {
-                                cpSync(srcSlicesDir, dstSlicesDir, { recursive: true });
-                                synced.push(`milestones/${mid}/slices/`);
-                            }
-                            catch (err) {
-                                /* non-fatal */
-                                logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-                            }
-                        }
-                        else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
-                            // Both exist — sync missing slice directories
-                            const srcSlices = readdirSync(srcSlicesDir, {
-                                withFileTypes: true,
-                            })
-                                .filter((d) => d.isDirectory())
-                                .map((d) => d.name);
-                            for (const sid of srcSlices) {
-                                const srcSlice = join(srcSlicesDir, sid);
-                                const dstSlice = join(dstSlicesDir, sid);
-                                if (!existsSync(dstSlice)) {
-                                    try {
-                                        cpSync(srcSlice, dstSlice, { recursive: true });
-                                        synced.push(`milestones/${mid}/slices/${sid}/`);
-                                    }
-                                    catch (err) {
-                                        /* non-fatal */
-                                        logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                            else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) {
+                                // Both exist — sync missing slice directories
+                                const srcSlices = readdirSync(srcSlicesDir, {
+                                    withFileTypes: true,
+                                })
+                                    .filter((d) => d.isDirectory())
+                                    .map((d) => d.name);
+                                for (const sid of srcSlices) {
+                                    const srcSlice = join(srcSlicesDir, sid);
+                                    const dstSlice = join(dstSlicesDir, sid);
+                                    if (!existsSync(dstSlice)) {
+                                        try {
+                                            cpSync(srcSlice, dstSlice, { recursive: true });
+                                            synced.push(`milestones/${mid}/slices/${sid}/`);
+                                        }
+                                        catch (err) {
+                                            /* non-fatal */
+                                            logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`);
+                                        }
                                     }
                                 }
                             }
                         }
-                    }
-                    catch (err) {
-                        /* non-fatal */
-                        logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        catch (err) {
+                            /* non-fatal */
+                            logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                        }
                     }
                 }
             }
-        }
-        catch (err) {
-            /* non-fatal */
-            logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            catch (err) {
+                /* non-fatal */
+                logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return { synced };
@@ -828,7 +688,7 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
  * the shared project DB or the pre-upgrade DB reconciliation path above.
  */
 export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
-    return _finalizeProjectionForMergeImpl(mainBasePath, worktreePath, milestoneId);
+    return new WorktreeStateProjection().finalizeProjectionForMergePaths(mainBasePath, worktreePath, milestoneId);
 }
 export { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
@@ -905,109 +765,6 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
     }
     checkoutBranchWithStashGuard(basePath, branch, `enter-branch-mode:${milestoneId}`);
 }
-export function checkoutBranchWithStashGuard(basePath, branch, reason) {
-    let stashMarker = null;
-    let stashed = false;
-    const status = nativeWorkingTreeStatus(basePath).trim();
-    if (status.length > 0) {
-        stashMarker = `gsd-checkout-stash:${reason}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
-        const stashListBefore = execFileSync("git", ["stash", "list"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-        execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd: checkout stash [${stashMarker}]`], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-        const stashListAfter = execFileSync("git", ["stash", "list"], {
-            cwd: basePath,
-            stdio: ["ignore", "pipe", "pipe"],
-            encoding: "utf-8",
-        });
-        stashed = stashListAfter !== stashListBefore;
-    }
-    // Checkout and stash-restore are split so we can distinguish two failure
-    // modes: (a) checkout failed → HEAD did not move, restore stash and rethrow;
-    // (b) checkout succeeded but stash pop failed → HEAD moved to `branch` but
-    // the working-tree changes remain in the stash list. We surface a distinct
-    // error in case (b) so callers don't assume the branch switch was rolled back.
-    try {
-        nativeCheckoutBranch(basePath, branch);
-    }
-    catch (checkoutErr) {
-        if (stashed) {
-            try {
-                popStashByRef(basePath, stashMarker);
-            }
-            catch (restoreErr) {
-                logWarning("worktree", `git stash pop failed during checkout restore: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
-            }
-        }
-        throw checkoutErr;
-    }
-    if (stashed) {
-        try {
-            popStashByRef(basePath, stashMarker);
-        }
-        catch (popErr) {
-            const msg = popErr instanceof Error ? popErr.message : String(popErr);
-            const stderr = popErr && typeof popErr === "object"
-                ? popErr.stderr
-                : undefined;
-            const stderrText = typeof stderr === "string"
-                ? stderr
-                : stderr instanceof Uint8Array
-                    ? Buffer.from(stderr).toString("utf-8")
-                    : "";
-            const stashPopMessage = `${stderrText}\n${msg}`.trim();
-            const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
-            const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-            const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
-            const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
-            const stashRefForDrop = stashRefFromError(popErr);
-            const nonGsdUnmerged = nativeConflictFiles(basePath).filter((f) => !f.startsWith(".gsd/"));
-            const gsdContentConflicts = isUntrackedRestoreFailure
-                ? gsdJsonlFilesWithConflictMarkers(basePath)
-                : [];
-            const gsdConflictFiles = [...new Set([...gsdAlreadyExists, ...gsdContentConflicts])];
-            if (isUntrackedRestoreFailure &&
-                gsdConflictFiles.length > 0 &&
-                nonGsdAlreadyExists.length === 0 &&
-                nonGsdUnmerged.length === 0) {
-                for (const f of gsdConflictFiles) {
-                    execFileSync("git", ["checkout", "HEAD", "--", f], {
-                        cwd: basePath,
-                        stdio: ["ignore", "pipe", "pipe"],
-                        encoding: "utf-8",
-                    });
-                    nativeAddPaths(basePath, [f]);
-                }
-                if (stashRefForDrop) {
-                    try {
-                        execFileSync("git", ["stash", "drop", stashRefForDrop], {
-                            cwd: basePath,
-                            stdio: ["ignore", "pipe", "pipe"],
-                            encoding: "utf-8",
-                        });
-                    }
-                    catch (err) { /* stash may already be consumed */
-                        logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                else {
-                    logWarning("worktree", "recorded stash entry could not be resolved; skipping automatic drop");
-                }
-                return;
-            }
-            const wrapped = new Error(`checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`);
-            if (stashRefForDrop)
-                wrapped.stashRef = stashRefForDrop;
-            throw wrapped;
-        }
-    }
-}
 // ─── Public API ────────────────────────────────────────────────────────────
 /**
  * Create a new auto-worktree for a milestone, chdir into it, and store
@@ -1071,6 +828,14 @@ function _resolveIntegrationBranchForReuse(basePath, milestoneId) {
         return null;
     }
 }
+function safeCwd(fallback) {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * When reusing an existing milestone branch, fast-forward it onto the
  * integration branch when that's safe (branch is a strict ancestor of
@@ -1220,7 +985,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
     originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false, preserveWorktree = false } = opts;
-    const previousCwd = process.cwd();
+    const previousCwd = safeCwd(originalBasePath);
     // Wrap the entire teardown body in a single try/finally so activeWorkspace
     // is ALWAYS cleared — even if process.chdir throws (e.g. originalBasePath
     // was deleted before teardown ran). Previously the finally only covered
@@ -1304,7 +1069,7 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
  * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    const targetPath = isGsdWorktreePath(basePath) ? basePath : process.cwd();
+    const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
     if (!isGsdWorktreePath(targetPath))
         return false;
     const storedBase = getAutoWorktreeOriginalBase();
@@ -1332,7 +1097,9 @@ export function isInAutoWorktree(basePath) {
  */
 export function getAutoWorktreePath(basePath, milestoneId) {
     basePath = resolveWorktreeProjectRoot(basePath);
-    const p = worktreePath(basePath, milestoneId);
+    // basePath is already the resolved project root — go straight to placement
+    // instead of worktreePath(), which would re-resolve the root.
+    const p = worktreePathFor(basePath, milestoneId);
     if (!existsSync(p))
         return null;
     // Validate this is a real git worktree, not a stray directory.
@@ -1409,6 +1176,19 @@ export function getAutoWorktreeOriginalBase() {
 export function _resetAutoWorktreeOriginalBaseForTests() {
     setActiveWorkspace(null);
 }
+/**
+ * Inject an override for the shelter restore copy step, returning a function
+ * that restores the default (real cpSync) behavior. Used by tests to
+ * deterministically exercise the best-effort restore-failure path
+ * (auto-worktree.ts:1809) and the #2505 shelter-retention guarantee — which is
+ * otherwise unreachable because shelter + restore run synchronously in one
+ * mergeMilestoneToMain call. No production caller.
+ * @internal
+ */
+export function _setRestoreEntryFnForTests(fn) {
+    _restoreEntryFn = fn;
+    return () => { _restoreEntryFn = null; };
+}
 export function getActiveAutoWorktreeContext() {
     const ws = getActiveWorkspace();
     if (!ws)
@@ -1518,10 +1298,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
         const mainDbPath = contract.projectDb;
         try {
-            const activeDbPath = getDbPath();
+            const activeDbPath = getWorkflowDatabasePath();
             if (activeDbPath && _shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
-                closeDatabase();
-                if (!openDatabase(mainDbPath)) {
+                closeWorkflowDatabase();
+                if (!openWorkflowDatabasePath(mainDbPath)) {
                     throw new Error(`cannot open project DB at ${mainDbPath}`);
                 }
             }
@@ -1534,9 +1314,9 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             logError("worktree", message);
             throw new GSDError(GSD_GIT_ERROR, `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`);
         }
-        const closeoutGate = checkCloseoutConsistencyGate(milestoneId);
-        if (!closeoutGate.ok) {
-            throw new GSDError(GSD_GIT_ERROR, formatCloseoutConsistencyBlock(closeoutGate));
+        const closeoutProof = proveMilestoneCloseout(milestoneId);
+        if (!closeoutProof.ok) {
+            throw new GSDError(GSD_GIT_ERROR, formatCloseoutProofBlock(closeoutProof));
         }
     }
     // 2. Get completed slices for commit message
@@ -1745,10 +1525,18 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
     // does not sweep queued CONTEXT files into the stash. If stash pop later
     // fails, files trapped inside the stash are permanently lost (#2505).
-    const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
+    const planningDir = milestonesDir(originalBasePath_);
     const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
     const shelteredDirs = [];
     let shelterRestored = false;
+    const mergeDirNames = new Set([milestoneId]);
+    const resolvedMergeDir = resolveMilestonePath(originalBasePath_, milestoneId);
+    if (resolvedMergeDir) {
+        mergeDirNames.add(basename(resolvedMergeDir));
+    }
+    else {
+        mergeDirNames.add(canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+    }
     // Helper: restore sheltered milestone directories (#2505).
     // Called on both success and error paths to ensure queued CONTEXT files
     // are never permanently lost. Idempotent — the error path may fire after
@@ -1773,8 +1561,17 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 continue;
             }
             try {
-                mkdirSync(milestonesDir, { recursive: true });
-                cpSync(src, join(milestonesDir, dirName), { recursive: true, force: true });
+                mkdirSync(planningDir, { recursive: true });
+                // Test seam: when _restoreEntryFn is injected, route the copy through it
+                // so the best-effort failure path (and shelter-retention guarantee) can
+                // be exercised deterministically. Production leaves it null → real cpSync.
+                const dest = join(planningDir, dirName);
+                if (_restoreEntryFn) {
+                    _restoreEntryFn(src, dest);
+                }
+                else {
+                    cpSync(src, dest, { recursive: true, force: true });
+                }
             }
             catch (err) { /* best-effort */
                 restoreFailed = true;
@@ -1798,15 +1595,15 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
     };
     try {
-        if (existsSync(milestonesDir)) {
-            const entries = readdirSync(milestonesDir, { withFileTypes: true });
+        if (existsSync(planningDir)) {
+            const entries = readdirSync(planningDir, { withFileTypes: true });
             for (const entry of entries) {
                 if (!entry.isDirectory())
                     continue;
                 // Only shelter directories that do NOT belong to the milestone being merged
-                if (entry.name === milestoneId)
+                if (mergeDirNames.has(entry.name))
                     continue;
-                const srcDir = join(milestonesDir, entry.name);
+                const srcDir = join(planningDir, entry.name);
                 const dstDir = join(shelterDir, entry.name);
                 try {
                     mkdirSync(shelterDir, { recursive: true });
@@ -1831,18 +1628,18 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     //     branch. Passing NO pathspec lets git skip gitignored paths silently;
     //     adding an explicit pathspec trips a `git add`-style fatal on ignored
     //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
-    //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
-    //     in step 7 above, so they won't be swept into the stash.
+    //     Queued CONTEXT files under `.gsd/phases/*` (or legacy milestones/*)
+    //     are already sheltered in step 7 above, so they won't be swept into the stash.
     // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
     // sidecars while the connection is open. `git stash --include-untracked`
     // walks those files and fails with EBUSY (#4704). Close the DB before
     // stashing so Windows releases the handles; reopen after. No-op on
     // POSIX, where advisory locks don't block git.
     const needsDbCycle = process.platform === "win32" && isDbAvailable();
-    const dbPathToReopen = needsDbCycle ? getDbPath() : null;
+    const dbPathToReopen = needsDbCycle ? getWorkflowDatabasePath() : null;
     if (needsDbCycle) {
         try {
-            closeDatabase();
+            closeWorkflowDatabase();
         }
         catch (err) {
             logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1871,17 +1668,23 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         // report the dirty tree if it fails.
         logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
     }
-    // 7b. Clean up stale merge state before attempting squash merge (#2912).
+    // 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 --squash` to refuse with
+    // 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. Squash merge — auto-resolve .gsd/ state file conflicts (#530)
-    const mergeResult = nativeMergeSquash(originalBasePath_, milestoneBranch);
+    // 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);
     if (needsDbCycle && dbPathToReopen) {
         try {
-            openDatabase(dbPathToReopen);
+            openWorkflowDatabasePath(dbPathToReopen);
         }
         catch (err) {
             logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1912,7 +1715,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             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, `Squash merge of ${milestoneBranch} rejected: working tree has dirty or untracked files ` +
+            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
@@ -1930,7 +1733,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             }
             // If there are still real code conflicts, escalate
             if (codeConflicts.length > 0) {
-                cleanupSquashConflictState(originalBasePath_);
+                cleanupConflictState(originalBasePath_);
                 // Pop stash before throwing so local work is not lost (#2151).
                 if (stashed) {
                     try {
@@ -1947,7 +1750,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 // causing autoCommitDirtyState to commit unrelated milestone files to
                 // the integration branch (#2929).
                 process.chdir(previousCwd);
-                throw new MergeConflictError(codeConflicts, "squash", milestoneBranch, mainBranch);
+                throw new MergeConflictError(codeConflicts, effectiveStrategy, milestoneBranch, mainBranch);
             }
         }
         // No conflicts detected — possibly "already up to date", fall through to commit
@@ -1986,8 +1789,6 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
             const gsdContentConflicts = [];
             const alreadyExists = stashAlreadyExistsFilesFromError(e);
-            const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-            const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
             // Untracked-file restore failures can leave marker conflicts in tracked
             // .gsd JSONL files without producing `U` status entries.
             if (isUntrackedRestoreFailure) {
@@ -2048,10 +1849,11 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             }
             else if (gsdUU.length === 0 &&
                 nonGsdUU.length === 0 &&
-                gsdAlreadyExists.length > 0 &&
-                nonGsdAlreadyExists.length === 0) {
-                // Untracked-file restore failure from stash pop where all collided
-                // paths are .gsd/ artifacts that already exist after merge.
+                alreadyExists.length > 0) {
+                // Untracked-file restore failure from stash pop where all collided paths
+                // already exist after merge (committed on target). Safe to drop the stash
+                // for the full alreadyExists set — they were untracked on source by
+                // definition of the "already exists, no checkout" failure.
                 if (stashRefForDrop) {
                     try {
                         execFileSync("git", ["stash", "drop", stashRefForDrop], {
@@ -2074,11 +1876,6 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                     files: nonGsdUU.join(", "),
                 });
             }
-            else if (nonGsdAlreadyExists.length > 0) {
-                logWarning("reconcile", "Stash pop restore collision on non-.gsd files after merge", {
-                    files: nonGsdAlreadyExists.join(", "),
-                });
-            }
             else {
                 logWarning("worktree", "git stash pop failed without resolvable conflict files; leaving stash for manual recovery");
             }
@@ -2096,7 +1893,7 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         if (codeChanges.length > 0) {
             // Milestone has unanchored code changes — abort teardown.
             process.chdir(previousCwd);
-            throw new GSDError(GSD_GIT_ERROR, `Squash merge produced nothing to commit but milestone branch "${milestoneBranch}" ` +
+            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.`);
         }
@@ -2170,66 +1967,32 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
         catch (err) {
             logWarning("worktree", `chdir to project root after merge failed: ${err instanceof Error ? err.message : String(err)}`);
+            debugLog("mergeMilestoneToMain", {
+                phase: "post-merge-chdir-failed",
+                target: originalBasePath_,
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     };
     let shouldCleanup = false;
-    let pushed = false;
-    let prCreated = false;
     try {
-        // 10. Auto-push if enabled
-        if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
-            const remote = prefs.remote ?? "origin";
-            if (gitRemoteExists(originalBasePath_, remote)) {
-                try {
-                    execFileSync("git", ["push", remote, mainBranch], {
-                        cwd: originalBasePath_,
-                        stdio: ["ignore", "pipe", "pipe"],
-                        encoding: "utf-8",
-                    });
-                    pushed = true;
-                }
-                catch (err) {
-                    // Push failure is non-fatal
-                    logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-        }
-        // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
-        if (prefs.auto_pr === true && !nothingToCommit) {
-            const remote = prefs.remote ?? "origin";
-            const prTarget = prefs.pr_target_branch ?? mainBranch;
-            if (gitRemoteExists(originalBasePath_, remote)) {
-                try {
-                    // Push the milestone branch to remote first
-                    execFileSync("git", ["push", remote, milestoneBranch], {
-                        cwd: originalBasePath_,
-                        stdio: ["ignore", "pipe", "pipe"],
-                        encoding: "utf-8",
-                    });
-                    const prEvidence = buildPrEvidence({
-                        milestoneId,
-                        milestoneTitle,
-                        changeType: "feat",
-                        summaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
-                        testsRun: ["Auto-created after milestone merge. Run `npm run verify:merge` before marking this draft ready."],
-                        rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
-                        how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
-                    });
-                    const prUrl = createDraftPR(originalBasePath_, milestoneId, prEvidence.title, prEvidence.body, {
-                        head: milestoneBranch,
-                        base: prTarget,
-                    });
-                    if (!prUrl) {
-                        throw new Error("gh pr create returned no URL");
-                    }
-                    prCreated = true;
-                }
-                catch (err) {
-                    // PR creation failure is non-fatal — gh may not be installed or authenticated
-                    logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-        }
+        // 10/9b. Publication (auto-push / draft PR) — Publication module seam (ADR-034).
+        const publication = publishMilestone({
+            basePath: originalBasePath_,
+            milestoneId,
+            milestoneTitle,
+            integrationBranch: mainBranch,
+            milestoneBranch,
+            sliceSummaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+            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.