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

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

@@ -0,0 +1,35 @@
+// gsd-pi — Conflict auto-resolve policy for auto-worktree merges.
+//
+// Owns the pure path policy for conflict paths that are safe to resolve
+// mechanically. Git mutation stays in git-conflict-resolve.ts.
+/** Patterns for machine-generated build artifacts that can be safely
+ * auto-resolved by accepting --theirs during merge. These files are
+ * regenerable and never contain meaningful manual edits. */
+export const SAFE_AUTO_RESOLVE_PATTERNS = [
+    /\.tsbuildinfo$/,
+    /\.pyc$/,
+    /\/__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, common build artifacts, and regenerable
+ * dependency lockfiles. */
+export function isSafeToAutoResolve(filePath) {
+    return filePath.startsWith(".gsd/")
+        || SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
+}

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

@@ -0,0 +1,130 @@
+// gsd-pi — Auto-worktree creation module.
+//
+// Owns the creation path for milestone worktrees: repository readiness,
+// branch reuse/start-point selection, initial untracked-content import,
+// post-create hook, cwd transition, and session registry update.
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { classifyProject } from "./detection.js";
+import { GSDError, GSD_GIT_ERROR, GSD_IO_ERROR } from "./errors.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { nativeBranchExists } from "./native-git-bridge.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, _resolveAutoWorktreeStartPoint, } from "./auto-worktree-branch-lifecycle.js";
+import { setActiveWorkspace } from "./auto-worktree-session-registry.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
+import { createWorktree } from "./worktree-manager.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { createWorkspace } from "./workspace.js";
+import { debugLog } from "./debug-logger.js";
+import { logWarning } from "./workflow-logger.js";
+function importUntrackedProjectRootContentIntoEmptyWorktree(projectRoot, worktreeRoot, milestoneId) {
+    const worktreeClassification = classifyProject(worktreeRoot);
+    if (worktreeClassification.kind !== "greenfield")
+        return 0;
+    const projectRootClassification = classifyProject(projectRoot);
+    if (projectRootClassification.kind === "greenfield" ||
+        projectRootClassification.kind === "invalid-repo" ||
+        projectRootClassification.untrackedFiles.length === 0) {
+        return 0;
+    }
+    let copied = 0;
+    for (const relPath of projectRootClassification.untrackedFiles) {
+        const src = join(projectRoot, relPath);
+        if (!existsSync(src))
+            continue;
+        const dst = join(worktreeRoot, relPath);
+        if (existsSync(dst))
+            continue;
+        mkdirSync(dirname(dst), { recursive: true });
+        cpSync(src, dst, { recursive: true, force: false });
+        copied++;
+    }
+    if (copied > 0) {
+        debugLog("createAutoWorktree", {
+            phase: "import-untracked-project-content",
+            milestoneId,
+            copied,
+        });
+    }
+    return copied;
+}
+export function createAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
+    // Check if repo has commits — git worktree requires a valid HEAD.
+    try {
+        execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+            cwd: basePath,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        throw new GSDError(GSD_GIT_ERROR, "Cannot create worktree: repository has no commits yet. Worktree isolation requires at least one commit.");
+    }
+    const branch = autoWorktreeBranch(milestoneId);
+    // Check if the milestone branch already exists — it survives auto-mode
+    // stop/pause and contains committed work from prior sessions. If it exists,
+    // re-attach the worktree to it WITHOUT resetting. Only create a fresh branch
+    // from the integration branch when no prior work exists.
+    const branchExists = nativeBranchExists(basePath, branch);
+    let info;
+    if (branchExists) {
+        // #5538-followup: fast-forward the reused branch onto the integration
+        // branch when safe so the next milestone forks from up-to-date code.
+        // Without this, a milestone that was created before another milestone
+        // merged into main would carry a stale base into its worktree.
+        fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch);
+        // Re-attach worktree to the existing milestone branch (preserving commits).
+        info = createWorktree(basePath, milestoneId, {
+            branch,
+            reuseExistingBranch: true,
+        });
+    }
+    else {
+        // Fresh start — create branch from integration branch.
+        // Use the same 3-tier fallback as mergeMilestoneToMain (#3461):
+        //   1. META.json integration branch (explicit per-milestone override)
+        //   2. git.main_branch preference (user's configured working branch)
+        //   3. nativeDetectMainBranch (origin/HEAD auto-detection)
+        // Without tier 2, projects with main_branch=dev but origin/HEAD→master
+        // would fork worktrees from the wrong (stale) branch.
+        const integrationBranch = readIntegrationBranch(basePath, milestoneId)
+            ?? undefined;
+        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        const startPoint = _resolveAutoWorktreeStartPoint(integrationBranch, gitPrefs?.main_branch, (branchName) => nativeBranchExists(basePath, branchName));
+        info = createWorktree(basePath, milestoneId, {
+            branch,
+            startPoint,
+        });
+    }
+    // Phase C: copyPlanningArtifacts and reconcilePlanCheckboxes were
+    // deleted. Both addressed the same problem (worktree-local .gsd/
+    // projection lagging behind project-root state) by maintaining a stale
+    // copy. Now that auto-mode writers in workflow-projections.ts,
+    // triage-resolution.ts, rule-registry.ts, and auto-post-unit.ts route
+    // through s.canonicalProjectRoot, the worktree never needs a local
+    // .gsd/ — both reads and writes converge on the project-root .gsd/.
+    // The original concerns (#759, #778) no longer apply because there is
+    // no second copy to drift.
+    importUntrackedProjectRootContentIntoEmptyWorktree(basePath, info.path, milestoneId);
+    // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets.
+    const hookError = runWorktreePostCreateHook(basePath, info.path);
+    if (hookError) {
+        // Non-fatal — log but don't prevent worktree usage.
+        logWarning("reconcile", hookError, { worktree: info.name });
+    }
+    const previousCwd = process.cwd();
+    try {
+        process.chdir(info.path);
+        setActiveWorkspace(createWorkspace(basePath));
+    }
+    catch (err) {
+        // If chdir fails, the worktree was created but we couldn't enter it.
+        // Don't set activeWorkspace -- caller can retry or clean up.
+        throw new GSDError(GSD_IO_ERROR, `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    nudgeGitBranchCache(previousCwd);
+    return info.path;
+}

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

@@ -0,0 +1,118 @@
+// gsd-pi — Auto-worktree entry and presence detection module.
+//
+// Owns the small interface for finding, entering, and identifying milestone
+// worktrees. The legacy auto-worktree barrel re-exports these functions for
+// compatibility while lifecycle callers can depend on this focused module.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { GSDError, GSD_GIT_ERROR, GSD_IO_ERROR } from "./errors.js";
+import { nativeGetCurrentBranch } from "./native-git-bridge.js";
+import { worktreePath } from "./worktree-manager.js";
+import { worktreePathFor } from "./worktree-placement.js";
+import { nudgeGitBranchCache } from "./worktree.js";
+import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
+import { getAutoWorktreeOriginalBase, setActiveWorkspace, } from "./auto-worktree-session-registry.js";
+import { createWorkspace } from "./workspace.js";
+import { logWarning } from "./workflow-logger.js";
+function safeCwd(fallback) {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Detect if the process is currently inside an auto-worktree.
+ * Uses the current directory structure plus git branch prefix so detection
+ * still works after process restart when module state has been reset.
+ */
+export function isInAutoWorktree(basePath) {
+    const targetPath = isGsdWorktreePath(basePath) ? basePath : safeCwd("");
+    if (!isGsdWorktreePath(targetPath))
+        return false;
+    const storedBase = getAutoWorktreeOriginalBase();
+    const projectRoot = resolveWorktreeProjectRoot(basePath, storedBase);
+    const targetProjectRoot = resolveWorktreeProjectRoot(targetPath, storedBase);
+    if (normalizeWorktreePathForCompare(projectRoot) !==
+        normalizeWorktreePathForCompare(targetProjectRoot)) {
+        return false;
+    }
+    try {
+        const branch = nativeGetCurrentBranch(targetPath);
+        return branch.startsWith("milestone/");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the filesystem path for an auto-worktree, or null if it doesn't exist
+ * or is not a valid git worktree.
+ *
+ * Validates that the path is a real git worktree (has a .git file with a
+ * gitdir: pointer) rather than just a stray directory. This prevents
+ * mis-detection of leftover directories as active worktrees (#695).
+ */
+export function getAutoWorktreePath(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
+    // 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.
+    // A git worktree has a .git *file* (not directory) containing "gitdir: <path>".
+    const gitPath = join(p, ".git");
+    if (!existsSync(gitPath))
+        return null;
+    try {
+        const content = readFileSync(gitPath, "utf8").trim();
+        if (!content.startsWith("gitdir: "))
+            return null;
+    }
+    catch (e) {
+        logWarning("worktree", `getAutoWorktreePath .git read failed: ${e.message}`);
+        return null;
+    }
+    return p;
+}
+/**
+ * Enter an existing auto-worktree (chdir into it, store originalBase).
+ * Use for resume -- the worktree already exists from a prior create.
+ *
+ * Atomic: chdir + originalBase update in same try block.
+ */
+export function enterAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
+    const p = worktreePath(basePath, milestoneId);
+    if (!existsSync(p)) {
+        throw new GSDError(GSD_IO_ERROR, `Auto-worktree for ${milestoneId} does not exist at ${p}`);
+    }
+    // Validate this is a real git worktree, not a stray directory (#695)
+    const gitPath = join(p, ".git");
+    if (!existsSync(gitPath)) {
+        throw new GSDError(GSD_GIT_ERROR, `Auto-worktree path ${p} exists but is not a git worktree (no .git)`);
+    }
+    try {
+        const content = readFileSync(gitPath, "utf8").trim();
+        if (!content.startsWith("gitdir: ")) {
+            throw new GSDError(GSD_GIT_ERROR, `Auto-worktree path ${p} has a .git but it is not a worktree gitdir pointer`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("worktree"))
+            throw err;
+        throw new GSDError(GSD_IO_ERROR, `Auto-worktree path ${p} exists but .git is unreadable`);
+    }
+    const previousCwd = process.cwd();
+    try {
+        process.chdir(p);
+        setActiveWorkspace(createWorkspace(basePath));
+    }
+    catch (err) {
+        throw new GSDError(GSD_IO_ERROR, `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    nudgeGitBranchCache(previousCwd);
+    return p;
+}

package/dist/resources/extensions/gsd/auto-worktree-merge-already-merged.js

@@ -0,0 +1,98 @@
+// gsd-pi — Already-merged milestone merge fast path.
+//
+// Owns the safety invariant for milestone branches already reachable from the
+// integration branch: skip the squash merge only when milestone-touched code is
+// still anchored on the current integration branch, then run normal cleanup.
+import { execFileSync } from "node:child_process";
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { nativeDiffNumstat, nativeIsAncestor, } from "./native-git-bridge.js";
+import { cleanupMergedMilestoneWorktree } from "./auto-worktree-merge-cleanup.js";
+import { logWarning } from "./workflow-logger.js";
+export function finalizeAlreadyMergedMilestoneIfReachable(request) {
+    const { projectRoot, milestoneId, milestoneBranch, mainBranch, previousCwd, commitMessage, } = request;
+    if (!nativeIsAncestor(projectRoot, milestoneBranch, mainBranch)) {
+        return null;
+    }
+    assertNoUnanchoredRegularMergeCodeChanges({
+        projectRoot,
+        milestoneBranch,
+        mainBranch,
+        previousCwd,
+    });
+    debugLog("mergeMilestoneToMain", {
+        action: "skip-squash-already-merged",
+        milestoneId,
+        milestoneBranch,
+        mainBranch,
+    });
+    cleanupMergedMilestoneWorktree({
+        projectRoot,
+        milestoneId,
+        milestoneBranch,
+        previousCwd,
+        clearProjectRootState: true,
+        chdirWarningContext: "after already-merged cleanup",
+    });
+    return { commitMessage, pushed: false, prCreated: false, codeFilesChanged: true };
+}
+function assertNoUnanchoredRegularMergeCodeChanges(request) {
+    const { projectRoot, milestoneBranch, mainBranch, previousCwd } = request;
+    const codeChanges = nativeDiffNumstat(projectRoot, mainBranch, milestoneBranch).filter((entry) => !entry.path.startsWith(".gsd/"));
+    if (codeChanges.length === 0)
+        return;
+    const regularMergeChangedPaths = findRegularMergeChangedPaths(projectRoot, milestoneBranch, mainBranch);
+    const unanchoredCodeChanges = codeChanges.filter((entry) => regularMergeChangedPaths.has(entry.path));
+    if (unanchoredCodeChanges.length === 0)
+        return;
+    process.chdir(previousCwd);
+    throw new GSDError(GSD_GIT_ERROR, `Milestone branch "${milestoneBranch}" is reachable from "${mainBranch}" ` +
+        `but has ${unanchoredCodeChanges.length} milestone-touched code file(s) not on current "${mainBranch}". ` +
+        `Aborting worktree teardown to prevent data loss.`);
+}
+function findRegularMergeChangedPaths(basePath, milestoneBranch, mainBranch) {
+    const changedPaths = new Set();
+    let mergeLog = "";
+    try {
+        mergeLog = execFileSync("git", ["rev-list", "--merges", "--parents", mainBranch], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch (err) {
+        logWarning("worktree", `regular merge lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        return changedPaths;
+    }
+    for (const line of mergeLog.split("\n").filter(Boolean)) {
+        const [mergeCommit, firstParent, ...otherParents] = line.split(" ");
+        if (!mergeCommit || !firstParent || otherParents.length === 0)
+            continue;
+        const mergedMilestone = otherParents.some((parent) => {
+            try {
+                return nativeIsAncestor(basePath, milestoneBranch, parent);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!mergedMilestone)
+            continue;
+        try {
+            const output = execFileSync("git", ["diff", "--name-only", firstParent, mergeCommit], {
+                cwd: basePath,
+                stdio: ["ignore", "pipe", "pipe"],
+                encoding: "utf-8",
+            }).trim();
+            for (const path of output.split("\n").filter(Boolean)) {
+                if (!path.startsWith(".gsd/"))
+                    changedPaths.add(path);
+            }
+        }
+        catch (err) {
+            logWarning("worktree", `regular merge diff lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return changedPaths;
+    }
+    return changedPaths;
+}

package/dist/resources/extensions/gsd/auto-worktree-merge-branch-head.js

@@ -0,0 +1,52 @@
+// gsd-pi — Milestone branch/head reconciliation before merge.
+//
+// Owns the data-loss guard that keeps the named milestone branch aligned with
+// the actual worktree HEAD. Detached worktree commits can otherwise sit beyond
+// the branch ref and be silently omitted from the integration merge.
+import { execFileSync } from "node:child_process";
+import { debugLog } from "./debug-logger.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { nativeIsAncestor, nativeUpdateRef, } from "./native-git-bridge.js";
+export function reconcileMilestoneBranchHead(request) {
+    const { projectRoot, worktreeCwd, milestoneBranch, previousCwd } = request;
+    if (worktreeCwd === projectRoot) {
+        return { checked: false, updated: false, reason: "not-worktree" };
+    }
+    try {
+        const worktreeHead = gitRevParse(worktreeCwd, "HEAD");
+        const branchHead = gitRevParse(projectRoot, milestoneBranch);
+        if (!worktreeHead || !branchHead || worktreeHead === branchHead) {
+            return { checked: true, updated: false, reason: "already-current" };
+        }
+        if (nativeIsAncestor(projectRoot, branchHead, worktreeHead)) {
+            nativeUpdateRef(projectRoot, `refs/heads/${milestoneBranch}`, worktreeHead);
+            debugLog("mergeMilestoneToMain", {
+                action: "fast-forward-branch-ref",
+                milestoneBranch,
+                oldRef: branchHead.slice(0, 8),
+                newRef: worktreeHead.slice(0, 8),
+            });
+            return { checked: true, updated: true, reason: "fast-forwarded" };
+        }
+        process.chdir(previousCwd);
+        throw new GSDError(GSD_GIT_ERROR, `Worktree HEAD (${worktreeHead.slice(0, 8)}) diverged from ` +
+            `${milestoneBranch} (${branchHead.slice(0, 8)}). ` +
+            `Manual reconciliation required before merge.`);
+    }
+    catch (err) {
+        if (err instanceof GSDError)
+            throw err;
+        debugLog("mergeMilestoneToMain", {
+            action: "reconcile-skipped",
+            reason: String(err),
+        });
+        return { checked: false, updated: false, reason: "lookup-failed" };
+    }
+}
+function gitRevParse(cwd, ref) {
+    return execFileSync("git", ["rev-parse", ref], {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+    }).trim();
+}

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

@@ -0,0 +1,87 @@
+// 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";
+const defaultDeps = {
+    clearProjectRootStateFiles,
+    removeWorktree,
+    nativeBranchDelete,
+    setActiveWorkspace,
+    nudgeGitBranchCache,
+    chdir: process.chdir.bind(process),
+};
+let deps = defaultDeps;
+export function _setMilestoneCleanupDepsForTests(overrides) {
+    deps = { ...defaultDeps, ...overrides };
+}
+export function _resetMilestoneCleanupDepsForTests() {
+    deps = defaultDeps;
+}
+export function cleanupMergedMilestoneWorktree(request) {
+    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, context) {
+    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/dist/resources/extensions/gsd/auto-worktree-merge-code-changes.js

@@ -0,0 +1,46 @@
+// 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, mainBranch, milestoneBranch, effectiveStrategy, nothingToCommit) {
+    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, nothingToCommit) {
+    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, originalError) {
+    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) {
+    const files = output ? output.split("\n").filter(Boolean) : [];
+    return files.some((file) => !file.startsWith(".gsd/"));
+}

package/dist/resources/extensions/gsd/auto-worktree-merge-db-ready.js

@@ -0,0 +1,68 @@
+// 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";
+const defaultDeps = {
+    closeWorkflowDatabase,
+    formatCloseoutProofBlock,
+    getWorkflowDatabasePath,
+    isDbAvailable,
+    logError,
+    openWorkflowDatabasePath,
+    proveMilestoneCloseout,
+    reconcileWorktreeDb,
+    resolveGsdPathContract,
+    shouldReconcileWorktreeDb: _shouldReconcileWorktreeDb,
+};
+let deps = defaultDeps;
+export function _setMergeDbReadyDepsForTests(overrides) {
+    deps = { ...defaultDeps, ...overrides };
+}
+export function _resetMergeDbReadyDepsForTests() {
+    deps = defaultDeps;
+}
+function reconcileWorktreeDatabase(request) {
+    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) {
+    const closeoutProof = deps.proveMilestoneCloseout(milestoneId);
+    if (!closeoutProof.ok) {
+        throw new GSDError(GSD_GIT_ERROR, deps.formatCloseoutProofBlock(closeoutProof));
+    }
+}
+export function assertMilestoneDbReadyForMerge(request) {
+    if (!deps.isDbAvailable())
+        return;
+    reconcileWorktreeDatabase(request);
+    assertCloseoutProof(request.milestoneId);
+}