gsd-pi 2.82.0-dev.3709f22a5 → 2.82.0-dev.4285182e8

package/README.md

@@ -350,7 +350,7 @@ This is what makes GSD different. Run it, walk away, come back to built software
 
 Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
 
-The database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns/lessons are `pattern`/`gotcha` memories. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
+The database is authoritative for milestones, slices, tasks, requirements, summaries, and completion status. Durable decisions and project knowledge are stored in the `memories` table: decisions are `architecture` memories, and KNOWLEDGE patterns/lessons are `pattern`/`gotcha` memories. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, artifact/projection writes are rendered under the active worktree-local `.gsd/`, while the project-root DB remains authoritative runtime state.
 
 `KNOWLEDGE.md` is hybrid: rules remain file-canonical, while patterns and lessons are stored in the `memories` table and rendered back into `KNOWLEDGE.md` on the next session-start projection. Existing pattern and lesson rows are backfilled into memories before projection, so newly captured patterns and lessons may appear in memory-backed prompt context before the file view refreshes.
 
@@ -503,7 +503,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd mcp`              | MCP server status and connectivity                                            |
 | `/gsd status`           | Progress dashboard                                                            |
 | `/gsd brief <mode>`     | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides)      |
-| `/gsd queue`            | Queue future milestones (safe during auto mode)                               |
+| `/gsd queue`            | Queue/reorder future milestones (`pending`, `queued`, or legacy `planned`; safe during auto mode) |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                                     |
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format                           |
 | `/gsd help`             | Categorized command reference for all GSD subcommands                         |

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-d2173e15ccf5aedf
+8102192ede112252

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -269,7 +269,7 @@ function makeErrorMessage(model, errorMsg) {
 export function isClaudeCodeAbortErrorMessage(message) {
     if (!message)
         return false;
-    return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+    return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user|aborterror)\b/i.test(message);
 }
 function isBareClaudeCodeAbortErrorMessage(message) {
     if (!message)

package/dist/resources/extensions/gsd/auto/loop.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Main auto-mode execution loop.
 /**
  * auto/loop.ts — Main auto-mode execution loop.
  *
@@ -789,11 +791,18 @@ export async function autoLoop(ctx, pi, s, deps, options) {
                 unitId: iterData.unitId,
             });
             const finalizeReason = finalizeResult.action === "break" ? finalizeResult.reason : undefined;
+            const finalizeStatus = finalizeReason === "step-wizard"
+                ? "completed"
+                : finalizeResult.action === "next"
+                    ? "completed"
+                    : finalizeResult.action === "continue"
+                        ? "retry"
+                        : "stopped";
             journalReporter.emit("post-unit-finalize-end", {
                 iteration,
                 unitType: iterData.unitType,
                 unitId: iterData.unitId,
-                status: finalizeResult.action === "next" ? "completed" : finalizeResult.action === "continue" ? "retry" : "stopped",
+                status: finalizeStatus,
                 action: finalizeResult.action,
                 ...(finalizeReason ? { reason: finalizeReason } : {}),
             });
@@ -837,6 +846,10 @@ export async function autoLoop(ctx, pi, s, deps, options) {
             }) || dispatchSettled;
             completeIteration();
             finishTurn("completed");
+            if (finalizeDecision.action === "complete-and-break") {
+                s.preserveStepSurfaceAfterLoopExit = true;
+                break;
+            }
         }
         catch (loopErr) {
             // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ──

package/dist/resources/extensions/gsd/auto/phases.js

@@ -1338,35 +1338,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         s.currentUnit.type === unitType &&
         s.currentUnit.id === unitId);
     const previousTier = s.currentUnitRouting?.tier;
-    // Scope workflow-logger buffer to this unit so post-finalize drains are
-    // per-unit. Without this, the module-level _buffer accumulates across every
-    // unit in the same Node process (see workflow-logger.ts module header).
-    _resetLogs();
     const dispatchKey = `${unitType}/${unitId}`;
-    s.unitDispatchCount.set(dispatchKey, (s.unitDispatchCount.get(dispatchKey) ?? 0) + 1);
-    s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() };
-    s.lastGitActionFailure = null;
-    s.lastGitActionStatus = null;
-    s.lastUnitAgentEndMessages = null;
-    setCurrentPhase(unitType, {
-        basePath: s.basePath,
-        traceId: ic.flowId,
-        turnId: `iter-${ic.iteration}`,
-        causedBy: "unit-start",
-    });
-    s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
-    const unitStartSeq = ic.nextSeq();
-    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
-    deps.captureAvailableSkills();
-    writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: s.currentUnit.startedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-        recoveryAttempts: 0, // Reset so re-dispatched units get full recovery budget (#2322)
-    });
+    const nextDispatchCount = (s.unitDispatchCount.get(dispatchKey) ?? 0) + 1;
     // Status bar (widget + preconditions deferred until after model selection — see #2899)
     ctx.ui.setStatus("gsd-auto", "auto");
     if (mid)
@@ -1420,7 +1393,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         finalPrompt = `${capped}\n\n---\n\n${finalPrompt}`;
         s.pendingCrashRecovery = null;
     }
-    else if ((s.unitDispatchCount.get(dispatchKey) ?? 0) > 1) {
+    else if (nextDispatchCount > 1) {
         const diagnostic = deps.getDeepDiagnostic(s.basePath);
         if (diagnostic) {
             const cappedDiag = diagnostic.length > MAX_RECOVERY_CHARS
@@ -1459,6 +1432,11 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         logWarning("engine", "Prompt reorder failed", { error: msg });
     }
     // Select and apply model (with tier escalation on retry — normal units only)
+    const prevUnitRouting = s.currentUnitRouting;
+    const prevUnitModel = s.currentUnitModel;
+    const prevDispatchedModelId = s.currentDispatchedModelId;
+    const prevSessionModel = ctx.model;
+    const prevSessionThinkingLevel = pi.getThinkingLevel();
     const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, sidecarItem ? undefined : { isRetry, previousTier }, undefined, s.manualSessionModelOverride, s.autoModeStartThinkingLevel);
     s.currentUnitRouting =
         modelResult.routing;
@@ -1502,12 +1480,58 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                 ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
                 : undefined,
         baseUrl: s.currentUnitModel?.baseUrl ?? ctx.model?.baseUrl,
+        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
     });
     if (compatibilityError) {
+        s.currentUnitRouting = prevUnitRouting;
+        s.currentUnitModel = prevUnitModel;
+        s.currentDispatchedModelId = prevDispatchedModelId;
+        if (s.checkpointSha) {
+            cleanupCheckpoint(s.basePath, unitId);
+            s.checkpointSha = null;
+        }
+        if (prevSessionModel) {
+            const ok = await pi.setModel(prevSessionModel, { persist: false });
+            if (!ok) {
+                ctx.ui.notify("Failed to restore previous session model after compatibility check failure.", "warning");
+            }
+            if (prevSessionThinkingLevel) {
+                pi.setThinkingLevel(prevSessionThinkingLevel);
+            }
+        }
         ctx.ui.notify(compatibilityError, "error");
         await deps.stopAuto(ctx, pi, compatibilityError);
         return { action: "break", reason: "workflow-capability" };
     }
+    // Scope workflow-logger buffer to this unit so post-finalize drains are
+    // per-unit. Without this, the module-level _buffer accumulates across every
+    // unit in the same Node process (see workflow-logger.ts module header).
+    _resetLogs();
+    const unitStartedAt = Date.now();
+    s.unitDispatchCount.set(dispatchKey, nextDispatchCount);
+    s.currentUnit = { type: unitType, id: unitId, startedAt: unitStartedAt };
+    s.lastGitActionFailure = null;
+    s.lastGitActionStatus = null;
+    s.lastUnitAgentEndMessages = null;
+    setCurrentPhase(unitType, {
+        basePath: s.basePath,
+        traceId: ic.flowId,
+        turnId: `iter-${ic.iteration}`,
+        causedBy: "unit-start",
+    });
+    s.lastToolInvocationError = null; // #2883: clear stale error from previous unit
+    const unitStartSeq = ic.nextSeq();
+    deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
+    deps.captureAvailableSkills();
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, unitStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: unitStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+        recoveryAttempts: 0, // Reset so re-dispatched units get full recovery budget (#2322)
+    });
     // Progress widget + preconditions — deferred to after model selection so the
     // widget's first render tick shows the correct model (#2899).
     deps.updateProgressWidget(ctx, unitType, unitId, state);

package/dist/resources/extensions/gsd/auto/session.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Mutable auto-mode session state container.
 /**
  * AutoSession — encapsulates all mutable auto-mode state into a single instance.
  *
@@ -26,6 +28,7 @@ export class AutoSession {
     active = false;
     paused = false;
     completionStopInProgress = false;
+    preserveStepSurfaceAfterLoopExit = false;
     stepMode = false;
     verbose = false;
     activeEngineId = null;
@@ -210,6 +213,7 @@ export class AutoSession {
         this.active = false;
         this.paused = false;
         this.completionStopInProgress = false;
+        this.preserveStepSurfaceAfterLoopExit = false;
         this.stepMode = false;
         this.verbose = false;
         this.activeEngineId = null;

package/dist/resources/extensions/gsd/auto/workflow-kernel.js

@@ -66,6 +66,9 @@ export function decideEngineDispatch(input) {
 export function decideFinalizeResult(input) {
     if (input.action === "break") {
         const reason = input.reason ?? "unknown";
+        if (reason === "step-wizard") {
+            return { action: "complete-and-break" };
+        }
         return {
             action: "stop",
             failureClass: reason === "git-closeout-failure" ? "git" : "closeout",

package/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -224,6 +224,7 @@ export async function dispatchDirectPhase(ctx, pi, phase, base) {
         unitType,
         authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined,
         baseUrl: ctx.model?.baseUrl,
+        activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
     });
     if (compatibilityError) {
         ctx.ui.notify(compatibilityError, "error");

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

@@ -299,9 +299,7 @@ export const DISPATCH_RULES = [
             const attempts = incrementUatCount(basePath, mid, sliceId);
             if (attempts > MAX_UAT_ATTEMPTS) {
                 return {
-                    action: "stop",
-                    reason: `run-uat for ${mid}/${sliceId} has been dispatched ${attempts - 1} times without producing a verdict. Verification commands may be broken — fix the UAT spec or manually write an ASSESSMENT verdict.`,
-                    level: "warning",
+                    action: "skip",
                 };
             }
             const uatFile = resolveSliceFile(basePath, mid, sliceId, "UAT");
@@ -616,7 +614,7 @@ export const DISPATCH_RULES = [
         },
     },
     {
-        name: "planning (require_slice_discussion) → pause for discussion (#3454)",
+        name: "planning (require_slice_discussion) → pause for discussion",
         match: async ({ state, mid, basePath, prefs }) => {
             if (state.phase !== "planning")
                 return null;
@@ -1023,7 +1021,7 @@ export const DISPATCH_RULES = [
                         mkdirSync(mDir, { recursive: true });
                     const validationPath = join(mDir, buildMilestoneFileName(mid, "VALIDATION"));
                     const skipSource = trivialVariant
-                        ? "trivial-scope pipeline variant (#4781)"
+                        ? "trivial-scope pipeline variant"
                         : "`skip_milestone_validation` preference";
                     const skipValidationReason = trivialVariant ? "trivial-scope" : "preference";
                     const content = [
@@ -1098,19 +1096,19 @@ export const DISPATCH_RULES = [
                     return { action: "skip" };
                 }
             }
-            // Safety guard (#2675, #5747): block completion when VALIDATION
-            // verdict is non-passing. The state machine treats these verdicts as
-            // terminal, but completing-milestone should NOT proceed — remediation
-            // or human attention is needed.
+            // Safety guard (#2675, #5747, #5920): block completion when VALIDATION
+            // verdict is anything other than pass. The state machine treats these
+            // verdicts as terminal, but completing-milestone should NOT proceed —
+            // remediation or human attention is needed.
             const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
             if (validationFile) {
                 const validationContent = await loadFile(validationFile);
                 if (validationContent) {
                     const verdict = extractVerdict(validationContent);
-                    if (verdict === "needs-remediation" || verdict === "needs-attention") {
+                    if (verdict !== "pass") {
                         return {
                             action: "stop",
-                            reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or update the verdict manually.`,
+                            reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or run \`/gsd verdict pass --rationale "..."\` to override.`,
                             level: "warning",
                         };
                     }
@@ -1125,16 +1123,12 @@ export const DISPATCH_RULES = [
                     level: "error",
                 };
             }
-            // Safety guard (#1703): verify the milestone produced implementation
-            // artifacts (non-.gsd/ files). A milestone with only plan files and
-            // zero implementation code should not be marked complete.
+            // Safety signal (#1703, #5097): detect milestones with only .gsd/
+            // artifacts. This no longer hard-blocks completion because some
+            // milestones are intentionally planning/documentation-only.
             const artifactCheck = hasImplementationArtifacts(basePath, mid);
             if (artifactCheck === "absent") {
-                return {
-                    action: "stop",
-                    reason: `Cannot complete milestone ${mid}: no implementation files found outside .gsd/. The milestone has only plan files — actual code changes are required.`,
-                    level: "error",
-                };
+                logWarning("dispatch", `Milestone ${mid} has no implementation files outside .gsd/ — continuing complete-milestone dispatch (planning-only/documentation-only milestone).`);
             }
             if (artifactCheck === "unknown") {
                 logWarning("dispatch", `Implementation artifact check inconclusive for ${mid} — proceeding (git context unavailable)`);

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -28,7 +28,7 @@ import { regenerateIfMissing } from "./workflow-projections.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { isDbAvailable, getDbPath, refreshOpenDatabaseFromDisk, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { renderPlanCheckboxes } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import { checkPostUnitHooks, isRetryPending, consumeRetryTrigger, persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js";
@@ -294,14 +294,14 @@ export function detectRogueFileWrites(unitType, unitId, basePath) {
  * looping indefinitely (#2007).
  */
 export const MAX_ARTIFACT_VERIFICATION_RETRIES = 3;
-export const STEP_COMPLETE_FALLBACK_MESSAGE = "Step complete. Run /clear, then /gsd to continue (or /gsd auto to run continuously).";
+export const STEP_COMPLETE_FALLBACK_MESSAGE = "Step complete. Run /clear if you want a clean view, then /gsd next to continue one step (or /gsd auto to run continuously).";
 export function buildStepCompleteMessage(nextState) {
     if (nextState.phase === "complete") {
         return "Step complete — milestone finished. Run /gsd status to review, or start the next milestone.";
     }
     const next = describeNextUnit(nextState);
     return `Step complete. Next: ${next.label}\n`
-        + `Run /clear, then /gsd to continue (or /gsd auto to run continuously).`;
+        + `Run /clear if you want a clean view, then /gsd next to continue one step (or /gsd auto to run continuously).`;
 }
 /**
  * Decide whether step mode should stop at the step wizard after a unit finishes.
@@ -553,6 +553,13 @@ export async function postUnitPreVerification(pctx, opts) {
     if (!opts?.skipSettleDelay) {
         await new Promise(r => setTimeout(r, 100));
     }
+    const dbPath = getDbPath();
+    if (isDbAvailable() && dbPath && dbPath !== ":memory:") {
+        const refreshed = refreshOpenDatabaseFromDisk();
+        if (!refreshed) {
+            logWarning("db", "post-unit database refresh failed; derived state may be stale");
+        }
+    }
     // Turn-level git action (commit | snapshot | status-only)
     if (s.currentUnit) {
         const unit = s.currentUnit;
@@ -999,7 +1006,7 @@ export async function postUnitPreVerification(pctx, opts) {
                 s.verificationRetryCount.delete(retryKey);
                 s.verificationRetryFailureHashes.delete(retryKey);
                 writeBlockerPlaceholder(s.currentUnit.type, s.currentUnit.id, s.basePath, reason);
-                ctx.ui.notify(`${s.currentUnit.type} ${s.currentUnit.id} — deterministic policy rejection, wrote blocker placeholder (no retries) (#4973)`, "warning");
+                ctx.ui.notify(`${s.currentUnit.type} ${s.currentUnit.id} — deterministic policy rejection, wrote blocker placeholder (no retries)`, "warning");
                 // Fall through to "continue" — do NOT enter the retry or db-unavailable paths.
             }
             else if (!triggerArtifactVerified && diagnoseWorktreeIntegrityFailure(s.basePath)) {
@@ -1458,8 +1465,8 @@ export async function postUnitPostVerification(pctx) {
         }
     }
     // Step mode → show wizard instead of dispatch.
-    // Without this notify(), /gsd in step mode finishes a unit and silently
-    // exits the loop, leaving the user with no hint to /clear and /gsd again.
+    // Without this notify(), /gsd next finishes a unit and silently exits the
+    // loop, leaving the user with no next-step command.
     if (s.stepMode) {
         let phaseAfterUnit = null;
         try {

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

@@ -162,9 +162,16 @@ export function hasImplementationArtifacts(basePath, milestoneId) {
         // Strategy: check `git diff --name-only` against the merge-base with the
         // main branch. This captures ALL files changed during the milestone's
         // lifetime while running on a milestone branch.
-        const integrationBranch = milestoneId
-            ? readIntegrationBranch(basePath, milestoneId) ?? detectMainBranch(basePath)
-            : detectMainBranch(basePath);
+        const recordedIntegrationBranch = milestoneId
+            ? readIntegrationBranch(basePath, milestoneId)
+            : null;
+        let integrationBranch;
+        if (recordedIntegrationBranch?.startsWith("milestone/")) {
+            integrationBranch = detectMainBranch(basePath);
+        }
+        else {
+            integrationBranch = recordedIntegrationBranch ?? detectMainBranch(basePath);
+        }
         const currentBranch = getCurrentBranch(basePath);
         const branchDiff = getChangedFilesSinceBranch(basePath, integrationBranch);
         if (!branchDiff.ok)
@@ -496,29 +503,49 @@ function commitMatchesMilestone(basePath, message, milestoneId, files) {
     // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone when
     // either the commit touched this milestone's artifacts, or — for projects
     // where .gsd/ is gitignored/external (#5033) — the message explicitly
-    // names the milestone or local GSD state proves the task belongs here.
+    // names the milestone, local GSD state proves the task belongs here, or the
+    // commit is implementation-bearing evidence itself (#5100).
     if (/^GSD-Task:\s*S[^/\s]+\/T\S+/m.test(message)) {
         if (files.some((file) => isMilestoneArtifactPath(file, milestoneId)))
             return true;
         if (commitMessageMentionsMilestone(message, milestoneId))
             return true;
-        if (commitTaskTrailerBelongsToMilestone(basePath, message, milestoneId))
+        const taskTrailerOwnership = getTaskOwnershipStatus(basePath, message, milestoneId);
+        if (taskTrailerOwnership === true)
+            return true;
+        if (taskTrailerOwnership === false)
+            return false;
+        // taskTrailerOwnership === null: unknown ownership. Apply fallback only
+        // in this case to avoid cross-milestone attribution.
+        if (MILESTONE_ID_RE.test(milestoneId) && classifyImplementationFiles(files) === "present")
             return true;
     }
     return false;
 }
-function commitTaskTrailerBelongsToMilestone(basePath, message, milestoneId) {
+/**
+ * Tri-state task ownership probe.
+ * true => DB or local files confirm this milestone owns the task.
+ * false => DB is available and this milestone is registered, but task is absent.
+ * null => ownership unknown (milestone not in DB yet, or no DB + no local files).
+ */
+function getTaskOwnershipStatus(basePath, message, milestoneId) {
     const match = message.match(/^GSD-Task:\s*(S[^/\s]+)\/(T[^\s]+)/m);
     if (!match)
-        return false;
+        return null;
     const [, sliceId, taskId] = match;
-    if (getTask(milestoneId, sliceId, taskId))
-        return true;
+    if (isDbAvailable()) {
+        if (!getMilestone(milestoneId))
+            return null;
+        return getTask(milestoneId, sliceId, taskId) ? true : false;
+    }
+    // DB unavailable: fallback to local task-file presence.
     const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
-    if (!tasksDir)
-        return false;
-    return existsSync(join(tasksDir, `${taskId}-PLAN.md`))
-        || existsSync(join(tasksDir, `${taskId}-SUMMARY.md`));
+    if (tasksDir
+        && (existsSync(join(tasksDir, `${taskId}-PLAN.md`))
+            || existsSync(join(tasksDir, `${taskId}-SUMMARY.md`)))) {
+        return true;
+    }
+    return null;
 }
 function commitMessageMentionsMilestone(message, milestoneId) {
     if (!MILESTONE_ID_RE.test(milestoneId))

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

@@ -21,10 +21,10 @@ import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock } from "./crash-recovery.js";
 import { acquireSessionLock, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
-import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeCheckoutBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit, nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchList, nativeBranchExists, nativeBranchListMerged, nativeBranchDelete, nativeWorktreeRemove, nativeCommitCountBetween, } from "./native-git-bridge.js";
 import { GitServiceImpl } from "./git-service.js";
 import { captureIntegrationBranch, detectWorktreeName, setActiveMilestoneId, } from "./worktree.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath, checkoutBranchWithStashGuard } from "./auto-worktree.js";
 import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js";
 import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js";
 import { emitWorktreeOrphaned } from "./worktree-telemetry.js";
@@ -901,7 +901,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 const integrationBranch = nativeDetectMainBranch(base);
                 const branchToCheckout = resolveIsolationNoneBranchCheckout(currentBranch, integrationBranch, isolationMode, isRepo);
                 if (branchToCheckout) {
-                    nativeCheckoutBranch(base, branchToCheckout);
+                    checkoutBranchWithStashGuard(base, branchToCheckout, "isolation-none-recovery");
                     logWarning("bootstrap", `Returned to "${branchToCheckout}" — HEAD was on stale milestone branch "${currentBranch}" (isolation: none does not use milestone branches).`);
                 }
             }

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

@@ -65,12 +65,25 @@ async function runValidateMilestonePostCheck(vctx, pauseAuto) {
     const { milestone: mid } = parseUnitId(s.currentUnit.id);
     if (!mid)
         return "continue";
+    const setToolFailureRetry = (message) => {
+        const retryKey = verificationRetryKey(s.currentUnit.type, s.currentUnit.id);
+        const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1;
+        s.verificationRetryCount.set(retryKey, attempt);
+        s.pendingVerificationRetry = {
+            unitId: s.currentUnit.id,
+            failureContext: message,
+            attempt,
+        };
+        return "retry";
+    };
     const validationFile = resolveMilestoneFile(s.basePath, mid, "VALIDATION");
-    if (!validationFile)
-        return "continue";
+    if (!validationFile) {
+        return setToolFailureRetry("You must call gsd_validate_milestone to persist the validation results. No VALIDATION.md was created.");
+    }
     const validationContent = await loadFile(validationFile);
-    if (!validationContent)
-        return "continue";
+    if (!validationContent) {
+        return setToolFailureRetry("You must call gsd_validate_milestone to persist the validation results. VALIDATION.md exists but is empty.");
+    }
     const verdict = extractVerdict(validationContent);
     if (verdict !== "needs-remediation") {
         await persistMilestoneValidationGate("pass", "none", `milestone validation verdict is ${verdict}; no remediation loop risk`, "", mid);

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

@@ -870,7 +870,63 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
             reused: true,
         });
     }
-    nativeCheckoutBranch(basePath, branch);
+    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 wrapped = new Error(`checkout to '${branch}' succeeded but stash restore failed; working tree changes remain in the stash list. Original error: ${msg}`);
+            const ref = popErr?.stashRef;
+            if (ref)
+                wrapped.stashRef = ref;
+            throw wrapped;
+        }
+    }
 }
 // ─── Public API ────────────────────────────────────────────────────────────
 /**
@@ -1727,14 +1783,6 @@ 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)}`);
     }
-    if (needsDbCycle && dbPathToReopen) {
-        try {
-            openDatabase(dbPathToReopen);
-        }
-        catch (err) {
-            logWarning("worktree", `post-stash db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
     // 7b. Clean up stale merge state before attempting squash merge (#2912).
     // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
     // or interrupted operation) causes `git merge --squash` to refuse with
@@ -1743,6 +1791,14 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     removeMergeStateFiles(originalBasePath_, "pre-merge");
     // 8. Squash merge — auto-resolve .gsd/ state file conflicts (#530)
     const mergeResult = nativeMergeSquash(originalBasePath_, milestoneBranch);
+    if (needsDbCycle && dbPathToReopen) {
+        try {
+            openDatabase(dbPathToReopen);
+        }
+        catch (err) {
+            logWarning("worktree", `post-merge db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     if (!mergeResult.success) {
         // Dirty working tree — the merge was rejected before it started (e.g.
         // untracked .gsd/ files left by syncStateToProjectRoot).  Preserve the