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

package/dist/resources/extensions/gsd/unit-registry.js

@@ -20,8 +20,9 @@
 //
 // Not yet declared here (remaining ADR-033 steps): the manifest data
 // (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
-// against the registry's `UnitType`) and prompt-template association (still
-// implicit in auto-prompts.ts builders).
+// against the registry's `UnitType`). Prompt-template association is declared
+// for direct one-template units and verified conditional template sets;
+// composition logic stays with prompt builders.
 import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
 // ─── Shared tool-name constants (used by registry rows) ──────────────────
 export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
@@ -50,6 +51,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["research"],
+        promptTemplate: "research-milestone",
         toolContract: {
             allowedGsdTools: [
                 "gsd_summary_save",
@@ -65,6 +67,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["planning"],
+        promptTemplate: "plan-milestone",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -81,6 +84,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["discuss", "planning"],
+        promptTemplates: ["discuss", "discuss-headless", "guided-discuss-milestone"],
         toolContract: {
             allowedGsdTools: [
                 "gsd_summary_save",
@@ -113,6 +117,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "section-close",
         phaseChain: ["validation", "planning"],
+        promptTemplate: "validate-milestone",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -130,6 +135,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["completion"],
+        promptTemplate: "complete-milestone",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -153,6 +159,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["research"],
+        promptTemplate: "research-slice",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -169,6 +176,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["planning"],
+        promptTemplate: "plan-slice",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -187,6 +195,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["planning"],
+        promptTemplate: "refine-slice",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -203,6 +212,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["planning"],
+        promptTemplate: "replan-slice",
         toolContract: {
             allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
             requiredWorkflowTools: ["gsd_replan_slice"],
@@ -212,6 +222,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "section-close",
         phaseChain: ["completion"],
+        promptTemplate: "complete-slice",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -246,6 +257,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["validation", "planning"],
+        promptTemplate: "reassess-roadmap",
         toolContract: {
             allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
             requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
@@ -255,6 +267,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "execute-task",
         phaseChain: ["execution"],
+        promptTemplate: "execute-task",
         toolContract: {
             allowedGsdTools: [
                 "gsd_task_complete",
@@ -299,6 +312,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "execute-task",
         phaseChain: ["execution"],
+        promptTemplate: "reactive-execute",
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
@@ -314,6 +328,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["uat", "completion"],
+        promptTemplate: "run-uat",
         toolContract: {
             allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
             requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
@@ -328,6 +343,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["validation", "planning"],
+        promptTemplate: "gate-evaluate",
         toolContract: {
             allowedGsdTools: ["gsd_save_gate_result"],
             requiredWorkflowTools: ["gsd_save_gate_result"],
@@ -337,6 +353,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["validation", "planning"],
+        promptTemplate: "rewrite-docs",
         toolContract: {
             allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
             requiredWorkflowTools: [],
@@ -361,6 +378,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["discuss", "planning"],
+        promptTemplate: "guided-workflow-preferences",
         toolContract: {
             allowedGsdTools: ["gsd_summary_save"],
             requiredWorkflowTools: [],
@@ -370,6 +388,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["discuss", "planning"],
+        promptTemplate: "guided-discuss-project",
         toolContract: {
             allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
             requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
@@ -379,6 +398,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["discuss", "planning"],
+        promptTemplate: "guided-discuss-requirements",
         toolContract: {
             allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
             requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
@@ -388,6 +408,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["discuss", "planning"],
+        promptTemplate: "guided-research-decision",
         toolContract: {
             allowedGsdTools: ["gsd_summary_save"],
             requiredWorkflowTools: ["ask_user_questions"],
@@ -400,6 +421,7 @@ export const UNIT_REGISTRY = {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["research"],
+        promptTemplate: "guided-research-project",
         toolContract: {
             allowedGsdTools: [],
             requiredWorkflowTools: [],
@@ -419,3 +441,16 @@ export function getUnitDescriptor(unitType) {
 export function getUnitPhaseChain(unitType) {
     return getUnitDescriptor(unitType)?.phaseChain ?? null;
 }
+/** Prompt template id for units with a direct one-template builder. */
+export function getUnitPromptTemplate(unitType) {
+    return getUnitDescriptor(unitType)?.promptTemplate;
+}
+/** Prompt template ids for any verified direct or conditional prompt builder. */
+export function getUnitPromptTemplates(unitType) {
+    const descriptor = getUnitDescriptor(unitType);
+    if (!descriptor)
+        return [];
+    if (descriptor.promptTemplates)
+        return descriptor.promptTemplates;
+    return descriptor.promptTemplate ? [descriptor.promptTemplate] : [];
+}

package/dist/resources/extensions/gsd/unit-runtime.js

@@ -93,6 +93,8 @@ export function writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, up
     const path = runtimePath(basePath, unitType, unitId);
     return withRecordLock(path, () => {
         const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+        const sameRun = prev?.startedAt === startedAt;
+        const updatesHarnessAbort = Object.prototype.hasOwnProperty.call(updates, "harnessAbort");
         const next = {
             version: 1,
             unitType,
@@ -109,11 +111,24 @@ export function writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, up
             recovery: updates.recovery ?? prev?.recovery,
             recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
             lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+            harnessAbort: updatesHarnessAbort
+                ? updates.harnessAbort
+                : (sameRun ? prev?.harnessAbort : undefined),
         };
         atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
         return next;
     });
 }
+export function recordUnitHarnessAbort(basePath, unitType, unitId, startedAt, abort) {
+    return writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, {
+        harnessAbort: {
+            ...abort,
+            recordedAt: abort.recordedAt ?? Date.now(),
+        },
+        lastProgressAt: Date.now(),
+        lastProgressKind: `harness-abort:${abort.kind}`,
+    });
+}
 export function readUnitRuntimeRecord(basePath, unitType, unitId) {
     const path = runtimePath(basePath, unitType, unitId);
     if (!existsSync(path))
@@ -125,6 +140,12 @@ export function readUnitRuntimeRecord(basePath, unitType, unitId) {
         return null;
     }
 }
+export function readUnitHarnessAbort(basePath, unitType, unitId, startedAt) {
+    const record = readUnitRuntimeRecord(basePath, unitType, unitId);
+    if (!record || record.startedAt !== startedAt)
+        return null;
+    return record.harnessAbort ?? null;
+}
 export function clearUnitRuntimeRecord(basePath, unitType, unitId) {
     const path = runtimePath(basePath, unitType, unitId);
     if (existsSync(path))

package/dist/resources/extensions/gsd/unmerged-milestone-guard.js

@@ -2,7 +2,7 @@
 // File Purpose: Block new workflow entry when completed milestone branches are still unmerged.
 import { execFileSync } from "node:child_process";
 import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat, nativeIsAncestor, } from "./native-git-bridge.js";
-import { autoWorktreeBranch } from "./auto-worktree.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -1,7 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Shared command gate for validation-blocked milestones.
 import { existsSync } from "node:fs";
-import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";

package/dist/resources/extensions/gsd/workspace-git-preflight.js

@@ -1,8 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Unified workspace git preflight probe, heal, and readiness checks.
 import { existsSync, realpathSync } from "node:fs";
-import { getAutoWorktreePath } from "./auto-worktree.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { listMergeStateBlockers, probeGitConflictState, reconcileGitConflictsOnSignal, } from "./git-conflict-state.js";
 import { deriveState } from "./state.js";

package/dist/resources/extensions/gsd/workspace.js

@@ -1,10 +1,27 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
-import { join, resolve } from "node:path";
-import { resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { dirname, join, resolve } from "node:path";
+import { buildMilestoneFileName, canonicalPhaseDirName, isLegacyMilestonesLayout, milestonesDir, resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, normalizeRealPath, } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 function tryRealpath(p) {
     return normalizeRealPath(p);
 }
+function isLegacyMilestoneDirectory(dir) {
+    const parent = dirname(dir);
+    return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
+}
+function scopeMilestoneDir(basePath, milestoneId) {
+    return resolveMilestonePath(basePath, milestoneId) ?? join(milestonesDir(basePath), isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId));
+}
+function scopeMilestoneFile(basePath, milestoneId, suffix) {
+    const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
+    if (existing)
+        return existing;
+    const dir = scopeMilestoneDir(basePath, milestoneId);
+    const filename = isLegacyMilestoneDirectory(dir)
+        ? `${milestoneId}-${suffix}.md`
+        : buildMilestoneFileName(milestoneId, suffix);
+    return join(dir, filename);
+}
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.
  * Resolves both the project root and (when applicable) the worktree root,
@@ -39,21 +56,22 @@ export function createWorkspace(rawBasePath) {
  * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
  * with path-returning closures for DB-authoritative project state.
  *
- * These scope paths intentionally route to contract.projectGsd. In-flight
- * markdown artifact readers outside this scope use the projection-aware
- * resolvers in paths.ts so worktree units can see worktree-local projections.
+ * DB paths route to contract.projectGsd. Milestone artifact paths resolve from
+ * the pinned project root with the layout-aware resolvers, so flat-phase and
+ * legacy projects use the same scope surface.
  */
 export function scopeMilestone(workspace, milestoneId) {
     const { contract } = workspace;
     const gsd = contract.projectGsd;
+    const basePath = workspace.projectRoot;
     const scope = Object.freeze({
         workspace,
         milestoneId,
-        contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
-        roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+        contextFile: () => scopeMilestoneFile(basePath, milestoneId, "CONTEXT"),
+        roadmapFile: () => scopeMilestoneFile(basePath, milestoneId, "ROADMAP"),
         stateFile: () => join(gsd, "STATE.md"),
         dbPath: () => contract.projectDb,
-        milestoneDir: () => join(gsd, "milestones", milestoneId),
+        milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
         metaJson: () => join(gsd, `${milestoneId}-META.json`),
     });
     return scope;

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

@@ -11,7 +11,7 @@
  */
 import { loadPrompt } from "./prompt-loader.js";
 import { autoCommitCurrentBranch, getMainBranch, nudgeGitBranchCache } from "./worktree.js";
-import { runWorktreePostCreateHook } from "./auto-worktree.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { showConfirm } from "../shared/tui.js";
 import { gsdRoot, milestonesDir, resolveGsdPathContract } from "./paths.js";
 import { createWorktree, listWorktrees, removeWorktree, mergeWorktreeToMain, diffWorktreeAll, diffWorktreeNumstat, getWorktreeGSDDiff, getWorktreeCodeDiff, getWorktreeLog, worktreeBranchName, worktreePath, } from "./worktree-manager.js";

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

@@ -47,11 +47,15 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 // adding type churn without enabling any test variation.
 import { autoCommitCurrentBranch, getCurrentBranch, } from "./worktree.js";
 import { nativeCheckoutBranch } from "./native-git-bridge.js";
-// ADR-016 phase 2 / C2 (#5625): worktree-manager helpers inlined from
-// `./auto-worktree.js`. These seven functions are not real seams — Lifecycle
-// is the only Module that calls them, and they live alongside the Module's
-// other primitives in `auto-worktree.ts`.
-import { autoWorktreeBranch, createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, getAutoWorktreePath, isInAutoWorktree, teardownAutoWorktree, } from "./auto-worktree.js";
+// ADR-016 phase 2 / C2 (#5625): lifecycle uses focused auto-worktree
+// modules instead of the legacy compatibility barrel. Branch, entry/path,
+// creation, and teardown primitives are still implementation-level seams for
+// Lifecycle; tests vary them through `WorktreeLifecycleTestOverrides` below.
+import { autoWorktreeBranch, enterBranchModeForMilestone, } from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import { enterAutoWorktree, isInAutoWorktree, } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { resolveRoadmapForMilestoneMerge } from "./milestone-merge-roadmap.js";
 const recentWorktreeMergeFailures = new Map();
 const MERGE_FAILURE_DEDUPE_MS = 60_000;
@@ -102,6 +106,51 @@ class UserNotifiedError extends Error {
 function isSamePathPhysical(a, b) {
     return normalizeWorktreePathForCompare(a) === normalizeWorktreePathForCompare(b);
 }
+function preflightBlockedMergeReason(blockedReason) {
+    if (blockedReason?.startsWith("unmerged-conflicts")) {
+        return "preflight-unmerged-conflicts";
+    }
+    return "preflight-dirty-overlap";
+}
+/**
+ * Run a milestone merge behind the Worktree Lifecycle seam with the root-clean
+ * stash guard that protects user changes around merge.
+ *
+ * The helper owns the invariant ordering (preflight -> merge callback ->
+ * postflight on every attempted merge path) and returns the same typed result
+ * shape as `exitMilestone`. Auto closeout remains responsible for translating
+ * that result into loop policy (pause vs. stop, visible transcript
+ * preservation, projection rebuild).
+ */
+function runGuardedMilestoneMerge(request) {
+    const { merge, guard, milestoneId, notify } = request;
+    const preflight = guard.preflightCleanRoot(guard.projectRoot, milestoneId, notify);
+    if (preflight.blocked) {
+        return {
+            ok: false,
+            reason: preflightBlockedMergeReason(preflight.blockedReason),
+        };
+    }
+    let mergeError = null;
+    const exitResult = merge();
+    if (!exitResult.ok) {
+        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
+    }
+    let postflight;
+    if (preflight.stashPushed) {
+        postflight = guard.postflightPopStash(guard.projectRoot, milestoneId, preflight.stashMarker, notify);
+    }
+    if (mergeError instanceof MergeConflictError) {
+        return { ok: false, reason: "merge-conflict", cause: mergeError, postflight };
+    }
+    if (mergeError) {
+        return { ok: false, reason: "merge-failed", cause: mergeError, postflight };
+    }
+    if (postflight?.needsManualRecovery) {
+        return { ok: false, reason: "postflight-stash-restore-failed", postflight };
+    }
+    return exitResult;
+}
 // ─── Validation ──────────────────────────────────────────────────────────
 function isValidMilestoneId(milestoneId) {
     return !/[\/\\]|\.\./.test(milestoneId);
@@ -645,7 +694,7 @@ function _mergeWorktreeModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(originalBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(originalBasePath, milestoneId, roadmapResolution.content);
         // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree
         // cleanup internally (step 12), but it can silently fail on Windows
         // or when the worktree directory is locked. Perform a secondary
@@ -780,7 +829,7 @@ function _mergeBranchModeImpl(deps, mctx) {
                 pushed: false,
             };
         }
-        const mergeResult = deps.mergeMilestoneToMain(worktreeBasePath, milestoneId, roadmapResolution.content);
+        const mergeResult = deps.mergeMilestone(worktreeBasePath, milestoneId, roadmapResolution.content);
         if (mergeResult.codeFilesChanged) {
             notify(`Milestone ${milestoneId} merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`, "info");
         }
@@ -829,8 +878,9 @@ function _mergeBranchModeImpl(deps, mctx) {
  * **CWD anchor**: anchors `process.cwd()` at `originalBasePath` before
  * non-worktree merge paths to mirror the single-loop guard against ENOENT
  * after teardown (de73fb43d). Worktree-mode merge paths keep the real
- * worktree as cwd because `mergeMilestoneToMain()` infers source worktree
- * state from `process.cwd()`. Best-effort; silent on failure.
+ * worktree as cwd because the default milestone merge transaction delegates
+ * to the legacy merge primitive, which infers source worktree state from
+ * `process.cwd()`. Best-effort; silent on failure.
  *
  * **Failure handling**: `MergeConflictError` and other unrecoverable errors
  * propagate to the caller. The caller is responsible for any state restore
@@ -918,8 +968,8 @@ export function mergeMilestoneStandalone(deps, mctx) {
     }
     // Set cwd to the correct anchor before dispatching to mode implementations.
     // Worktree mode / in-worktree override must run from the live worktree so
-    // mergeMilestoneToMain can find worktree-local state; branch mode runs from
-    // the original project root. Best-effort for synthetic test paths.
+    // The default merge transaction can find worktree-local state; branch mode
+    // runs from the original project root. Best-effort for synthetic test paths.
     const targetCwd = mode === "worktree" || inWorktree
         ? worktreeBasePath
         : originalBasePath;
@@ -983,14 +1033,31 @@ export class WorktreeLifecycle {
      * With `opts.merge === false`, runs auto-commit and teardown without
      * merging to main.
      *
+     * When `opts.guardedMerge` is present with `opts.merge === true`, the
+     * lifecycle verb also owns the root-clean guard around the merge: preflight
+     * runs before the inner merge, postflight stash restore runs after every
+     * attempted merge path, and guard failures are returned as typed
+     * `ExitResult` reasons.
+     *
      * Returns a typed `ExitResult`. `MergeConflictError` is surfaced as
      * `{ ok: false, reason: "merge-conflict", cause }` instead of thrown,
-     * giving callers a typed branch for the expected failure path.
-     * Unexpected failures (filesystem, git permissions, etc.) are wrapped
-     * as `{ ok: false, reason: "teardown-failed", cause }` so callers always
+     * giving callers a typed branch for the expected failure path. Guarded merge
+     * failures surface as `preflight-dirty-overlap`,
+     * `preflight-unmerged-conflicts`, `merge-failed`, or
+     * `postflight-stash-restore-failed`. Unexpected failures (filesystem, git
+     * permissions, etc.) are wrapped as
+     * `{ ok: false, reason: "teardown-failed", cause }` so callers always
      * receive a discriminated union — no exceptions for any expected outcome.
      */
     exitMilestone(milestoneId, opts, ctx) {
+        if (opts.merge && opts.guardedMerge) {
+            return runGuardedMilestoneMerge({
+                merge: () => this.exitMilestone(milestoneId, { merge: true }, ctx),
+                guard: opts.guardedMerge,
+                milestoneId,
+                notify: ctx.notify,
+            });
+        }
         if (opts.merge) {
             try {
                 const merged = this._mergeAndExit(milestoneId, ctx);

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

@@ -17,7 +17,7 @@
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
@@ -163,6 +163,76 @@ function isRegisteredGitWorktreeAtPath(basePath, wtPath) {
         return false;
     }
 }
+function inspectUncommittedWorktreeState(wtPath) {
+    try {
+        const status = execFileSync("git", ["status", "--porcelain=v1", "--untracked-files=all"], { cwd: wtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trimEnd();
+        return { dirty: status.length > 0, status };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("worktree", `dirty worktree inspection failed for ${wtPath}: ${message}`);
+        // Fail closed: unknown state must quarantine rather than force-remove.
+        return { dirty: true, status: `git status failed: ${message}` };
+    }
+}
+function timestampForPath() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function uniqueQuarantinePath(basePath, name) {
+    const root = join(basePath, ".gsd", "quarantine", "worktrees");
+    const baseName = `${name}-${timestampForPath()}`;
+    let candidate = join(root, baseName);
+    let suffix = 2;
+    while (existsSync(candidate)) {
+        candidate = join(root, `${baseName}-${suffix}`);
+        suffix++;
+    }
+    return candidate;
+}
+function quarantineDirtyWorktree(basePath, name, branch, wtPath, status) {
+    const quarantinePath = uniqueQuarantinePath(basePath, name);
+    mkdirSync(join(basePath, ".gsd", "quarantine", "worktrees"), { recursive: true });
+    let moved = false;
+    try {
+        renameSync(wtPath, quarantinePath);
+        moved = true;
+    }
+    catch (renameErr) {
+        logWarning("worktree", `dirty worktree rename quarantine failed for ${name}: ${renameErr instanceof Error ? renameErr.message : String(renameErr)}; trying copy snapshot`);
+        try {
+            cpSync(wtPath, quarantinePath, { recursive: true, force: false, errorOnExist: true });
+        }
+        catch (copyErr) {
+            logWarning("reconcile", `Dirty worktree quarantine failed; preserving original worktree ${wtPath}: ${copyErr instanceof Error ? copyErr.message : String(copyErr)}`, { worktree: name, path: wtPath });
+            return null;
+        }
+    }
+    try {
+        const gitFile = join(quarantinePath, ".git");
+        if (existsSync(gitFile) && lstatSync(gitFile).isFile()) {
+            unlinkSync(gitFile);
+        }
+    }
+    catch (err) {
+        logWarning("worktree", `failed to remove quarantined worktree git pointer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        writeFileSync(join(quarantinePath, ".gsd-quarantine.json"), JSON.stringify({
+            kind: "dirty-worktree",
+            worktree: name,
+            branch,
+            originalPath: wtPath,
+            moved,
+            quarantinedAt: new Date().toISOString(),
+            status,
+        }, null, 2) + "\n", "utf-8");
+    }
+    catch (err) {
+        logWarning("worktree", `failed to write worktree quarantine metadata: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    logWarning("reconcile", `Quarantined dirty worktree ${name} at ${quarantinePath} before removal. Branch ${branch} was preserved.`, { worktree: name, path: quarantinePath, branch });
+    return quarantinePath;
+}
 /** True when `wtPath` has a git worktree checkout marker (`.git` file with gitdir pointer). */
 export function isLiveGitWorktreeCheckout(wtPath) {
     const gitPath = join(wtPath, ".git");
@@ -610,6 +680,7 @@ export function removeWorktree(basePath, name, opts = {}) {
     let wtPath = worktreePath(basePath, name);
     const branch = opts.branch ?? worktreeBranchName(name);
     const { deleteBranch = true, force = true } = opts;
+    let deleteBranchAfterRemoval = deleteBranch;
     // Resolve the ACTUAL worktree path from git's worktree list.
     // The computed path may differ when .gsd/ is (or was) a symlink to an
     // external state directory — git resolves symlinks at worktree creation
@@ -664,10 +735,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     if (!existsSync(wtPath)) {
         nativeWorktreePrune(basePath);
-        if (deleteBranch) {
+        if (deleteBranchAfterRemoval) {
             deleteBranchIfPresent(basePath, branch, "nativeBranchDelete failed");
         }
-        return;
+        return true;
     }
     // Submodule safety (#2337): detect submodules with uncommitted changes
     // before force-removing the worktree. Force removal destroys all uncommitted
@@ -721,6 +792,27 @@ export function removeWorktree(basePath, name, opts = {}) {
             }
         }
     }
+    // Dirty-worktree quarantine (#2365): once submodule (#2337) and nested-.git
+    // (#2616) rescue have run — they commit/clean the tree first — quarantine any
+    // uncommitted state that remains instead of force-deleting it. Gate on a live
+    // git checkout so a stale local directory left behind by state-sync (which
+    // has no `.git` file and is not a registered worktree) is removed normally
+    // rather than quarantined; otherwise its branch would never be deleted and
+    // the worktree would never be unregistered (#1852).
+    if (force && resolvedPathSafe && isLiveGitWorktreeCheckout(resolvedWtPath)) {
+        const dirtyState = inspectUncommittedWorktreeState(resolvedWtPath);
+        if (dirtyState.dirty) {
+            const quarantinePath = quarantineDirtyWorktree(basePath, name, branch, resolvedWtPath, dirtyState.status);
+            if (!quarantinePath) {
+                return false;
+            }
+            deleteBranchAfterRemoval = false;
+            if (!existsSync(resolvedWtPath)) {
+                nativeWorktreePrune(basePath);
+                return true;
+            }
+        }
+    }
     // Remove worktree — only use force/rmSync when the path is safely contained
     if (resolvedPathSafe) {
         // Remove worktree: try non-force first when submodules have changes,
@@ -778,9 +870,10 @@ export function removeWorktree(basePath, name, opts = {}) {
     }
     // Prune stale entries so git knows the worktree is gone
     nativeWorktreePrune(basePath);
-    if (deleteBranch) {
+    if (deleteBranchAfterRemoval) {
         deleteBranchIfPresent(basePath, branch, "final branch delete failed");
     }
+    return true;
 }
 /**
  * Paths to skip in all worktree diffs (internal/runtime artifacts).

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

@@ -6,7 +6,8 @@
 // back into the worktree. The worktree path is fully derivable from state, so we
 // resolve and chdir into it directly instead.
 import { readdirSync } from "node:fs";
-import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
+import { enterAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { getIsolationMode } from "./preferences.js";
 import { allWorktreesDirs } from "./worktree-manager.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";