gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

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

@@ -38,10 +38,9 @@ import { deactivateGSD } from "../shared/gsd-phase-state.js";
 import { initMetrics, resetMetrics, getLedger, getProjectTotals, formatCost, formatTokenCount, } from "./metrics.js";
 import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { preflightCleanRoot, postflightPopStash } from "./clean-root-preflight.js";
-import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
@@ -57,11 +56,13 @@ import { getErrorMessage } from "./error-utils.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
+import { isClosedStatus } from "./status-guards.js";
 import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS } from "../shared/cmux-events.js";
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 function makeCmuxEmitters(pi) {
     return {
         syncCmuxSidebar: (preferences, state) => pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences, state }),
@@ -75,18 +76,20 @@ import { runPostUnitVerification } from "./auto-verification.js";
 import { autoCommitUnit, postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
 import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { initHealthWidget } from "./health-widget.js";
-import { runLegacyAutoLoop, runUokKernelLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
+import { runLegacyAutoLoop, runUokKernelLoop } from "./auto/loop.js";
+import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto/resolve.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
+import { validateDirectory } from "./validate-directory.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
-// ─── Session State ─────────────────────────────────────────────────────────
-import { AutoSession, } from "./auto/session.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
+import { autoSession as s } from "./auto-runtime-state.js";
+import { gsdHome } from "./gsd-home.js";
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
 // This file must NOT declare module-level `let` or `var` variables for state.
-// The single `s` instance below is the only mutable module-level binding.
+// The single shared `s` instance below is the only mutable AutoSession binding.
 //
 // When adding features or fixing bugs:
 //   - New mutable state → add a property to AutoSession, not a module-level variable
@@ -95,7 +98,6 @@ export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session
 //
 // Tests in auto-session-encapsulation.test.ts enforce this invariant.
 // ─────────────────────────────────────────────────────────────────────────────
-const s = new AutoSession();
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 function captureProjectRootEnv(projectRoot) {
@@ -180,11 +182,7 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
 }
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath) {
-    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-    if (prefs?.isolation === "worktree")
-        return true;
-    // Default is false — worktree isolation requires explicit opt-in
-    return false;
+    return getIsolationMode(basePath) === "worktree";
 }
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
 /** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
@@ -877,8 +875,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
             milestoneLock: s.sessionMilestoneLock ?? undefined,
         };
         const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-        mkdirSync(runtimeDir, { recursive: true });
-        writeFileSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
+        atomicWriteSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
     }
     catch (err) {
         // Non-fatal — resume will still work via full bootstrap, just without worktree context
@@ -895,6 +892,19 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
         }
         s.currentUnit = null;
     }
+    // Keep STATE.md aligned with the DB-backed state before releasing pause state.
+    // Without this, an interrupted deep run can leave STATE.md saying "no active
+    // milestone" even after the DB/disk reconciliation has recovered the next unit.
+    if (s.basePath) {
+        try {
+            await rebuildState(s.basePath);
+        }
+        catch (e) {
+            debugLog("pause-rebuild-state-failed", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
     if (lockBase()) {
         releaseSessionLock(lockBase());
         clearLock(lockBase());
@@ -1094,6 +1104,11 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     // Escape stale worktree cwd from a previous milestone (#608).
     base = escapeStaleWorktree(base);
+    const dirCheck = validateDirectory(base);
+    if (dirCheck.severity === "blocked") {
+        ctx.ui.notify(dirCheck.reason, "error");
+        return;
+    }
     // Heal .gsd.migrating before any branching — covers both fresh-start and
     // resume paths (#4416). The matching call in auto-start.ts covers the
     // bootstrap-only path; this call ensures the resume path is also protected.
@@ -1141,15 +1156,31 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         || !!freshStartAssessment.lock);
                 if (shouldResumePausedSession) {
                     // Validate the milestone still exists and isn't already complete (#1664).
+                    // DB status is authoritative when available; SUMMARY.md is a legacy
+                    // fallback only for unmigrated/offline projects.
                     const mDir = resolveMilestonePath(base, meta.milestoneId);
-                    const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
                     let summaryIsTerminal = false;
-                    if (summaryFile) {
-                        try {
-                            summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                    let dbAvailable = isDbAvailable();
+                    let milestoneRow = dbAvailable ? getMilestone(meta.milestoneId) : null;
+                    if (!milestoneRow) {
+                        const opened = await ensureDbOpen(base);
+                        dbAvailable = opened || isDbAvailable();
+                        if (dbAvailable) {
+                            milestoneRow = getMilestone(meta.milestoneId);
                         }
-                        catch {
-                            summaryIsTerminal = false;
+                    }
+                    if (dbAvailable) {
+                        summaryIsTerminal = !!milestoneRow && isClosedStatus(milestoneRow.status);
+                    }
+                    else {
+                        const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
+                        if (summaryFile) {
+                            try {
+                                summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                            }
+                            catch {
+                                summaryIsTerminal = false;
+                            }
                         }
                     }
                     if (!mDir || summaryIsTerminal) {
@@ -1297,7 +1328,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
         // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
         // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent");
+        const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
         const pkgRoot = process.env.GSD_PKG_ROOT;
         const resourceLoaderPath = pkgRoot
             ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
@@ -1408,10 +1439,21 @@ const widgetStateAccessors = {
  * Ensure directories, branches, and other prerequisites exist before
  * dispatching a unit. The LLM should never need to mkdir or git checkout.
  */
-function ensurePreconditions(unitType, unitId, base, state) {
+export function ensurePreconditions(unitType, unitId, base, state) {
     const { milestone: mid, slice: sid } = parseUnitId(unitId);
     const mDir = resolveMilestonePath(base, mid);
     if (!mDir) {
+        // Fix #4996: When dispatching a slice unit against an unrecognised milestone,
+        // only create the directory if the milestone has a DB row.
+        // Without this guard, forward-referenced unit IDs (e.g. from REQUIREMENTS.md)
+        // silently scaffold empty stub directories that later skew nextMilestoneId.
+        if (sid !== undefined) {
+            const hasDbRow = isDbAvailable() && getMilestone(mid) != null;
+            if (!hasDbRow) {
+                logWarning("engine", `ensurePreconditions: skipping mkdir for unrecognised milestone ${mid} referenced by slice unit ${unitId} — no DB row exists`, { file: "auto.ts" });
+                return;
+            }
+        }
         const newDir = join(milestonesDir(base), mid);
         mkdirSync(join(newDir, "slices"), { recursive: true });
     }
@@ -1432,15 +1474,18 @@ function ensurePreconditions(unitType, unitId, base, state) {
     }
 }
 export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, triggerUnitId, hookPrompt, hookModel, targetBasePath) {
+    const wasActive = s.active;
+    const previousBasePath = s.basePath;
+    const previousCurrentUnit = s.currentUnit ? { ...s.currentUnit } : null;
     if (!s.active) {
         s.active = true;
         s.stepMode = true;
         s.cmdCtx = ctx;
-        s.basePath = targetBasePath;
         s.autoStartTime = Date.now();
         s.currentUnit = null;
         s.pendingQuickTasks = [];
     }
+    s.basePath = targetBasePath;
     const hookUnitType = `hook/${hookName}`;
     const hookStartedAt = Date.now();
     s.currentUnit = {
@@ -1448,6 +1493,27 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         id: triggerUnitId,
         startedAt: hookStartedAt,
     };
+    // Ensure cwd matches basePath BEFORE newSession() captures it (#1389).
+    // newSession() snapshots process.cwd() during construction; chdir-ing
+    // afterward leaves the session rooted to whatever cwd was when the call
+    // was made. Must be synchronous — no awaits between chdir and newSession.
+    try {
+        if (process.cwd() !== s.basePath)
+            process.chdir(s.basePath);
+    }
+    catch (err) {
+        const msg = `Failed to chdir before hook newSession (basePath: ${s.basePath}): ${err instanceof Error ? err.message : String(err)}`;
+        logWarning("engine", msg, { file: "auto.ts", basePath: s.basePath, error: err instanceof Error ? err.message : String(err) });
+        ctx.ui.notify(`${msg}. Cancelling hook dispatch to avoid running in the wrong directory.`, "error");
+        if (wasActive) {
+            s.basePath = previousBasePath;
+            s.currentUnit = previousCurrentUnit;
+        }
+        else {
+            s.reset();
+        }
+        return false;
+    }
     const result = await s.cmdCtx.newSession();
     if (result.cancelled) {
         await stopAuto(ctx, pi);
@@ -1490,14 +1556,6 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
     }, hookHardTimeoutMs);
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
     ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
-    // Ensure cwd matches basePath before hook dispatch (#1389)
-    try {
-        if (process.cwd() !== s.basePath)
-            process.chdir(s.basePath);
-    }
-    catch (err) {
-        logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-    }
     debugLog("dispatchHookUnit", {
         phase: "send-message",
         promptLength: hookPrompt.length,

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -1,11 +1,12 @@
 import { logWarning } from "../workflow-logger.js";
-import { checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
+import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
-import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
+import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto/resolve.js";
 import { resolveModelId } from "../auto-model-selection.js";
+import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
@@ -30,6 +31,14 @@ export const MAX_TRANSIENT_AUTO_RESUMES = 8;
 export function resetTransientRetryState() {
     resetRetryState(retryState);
 }
+function resolveAgentEndBasePath() {
+    try {
+        return resolveProjectRoot(process.cwd());
+    }
+    catch {
+        return undefined;
+    }
+}
 async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -67,6 +76,15 @@ export async function handleAgentEnd(pi, event, ctx) {
     // falsely report files as missing — producing a spurious "ready signal
     // rejected" loop even though the files are on disk.
     clearPathCache();
+    try {
+        if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+            return;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
+    }
     if (checkAutoStartAfterDiscuss()) {
         clearDiscussionFlowState();
         return;

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -1,11 +1,13 @@
 import { Type } from "@sinclair/typebox";
 import { Text } from "@gsd/pi-tui";
-import { findMilestoneIds, nextMilestoneId, claimReservedId, getReservedMilestoneIds } from "../guided-flow.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
-import { executeCompleteMilestone, executePlanMilestone, executePlanSlice, executeReplanSlice, executeReassessRoadmap, executeSaveGateResult, executeSliceComplete, executeSummarySave, executeTaskComplete, executeValidateMilestone, } from "../tools/workflow-tool-executors.js";
+async function loadWorkflowExecutors() {
+    return import("../tools/workflow-tool-executors.js");
+}
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
  * The alias description and promptGuidelines direct the LLM to prefer the canonical name.
@@ -19,6 +21,16 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+function requirementRootWriteGuard(operation) {
+    const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+    if (!guard.block)
+        return null;
+    return {
+        content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
+        details: { operation, error: "root_artifact_write_blocked" },
+        isError: true,
+    };
+}
 /**
  * Read a tool result's structured payload, accommodating MCP's `details` →
  * `structuredContent` rename (#4472, #4477). In-process executions still
@@ -118,6 +130,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
     // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
     const requirementUpdateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("update_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -200,6 +215,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
     // ─── gsd_requirement_save ─────────────────────────────────────────────
     const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("save_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -241,13 +259,28 @@ export function registerDbTools(pi) {
             "Requirement IDs are auto-assigned — never provide an ID manually.",
         promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
         promptGuidelines: [
-            "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+            "Use gsd_requirement_save when recording a new capability, quality attribute, constraint, or anti-feature requirement.",
+            "Use one of these classes: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, anti-feature.",
             "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
             "class, description, why, and source are required. All other fields are optional.",
             "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
         ],
         parameters: Type.Object({
-            class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+            class: StringEnum([
+                "core-capability",
+                "primary-user-loop",
+                "launchability",
+                "continuity",
+                "failure-visibility",
+                "integration",
+                "quality-attribute",
+                "operability",
+                "admin/support",
+                "compliance/security",
+                "differentiator",
+                "constraint",
+                "anti-feature",
+            ], { description: "Requirement class" }),
             description: Type.String({ description: "Short description of the requirement" }),
             why: Type.String({ description: "Why this requirement matters" }),
             source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
@@ -280,6 +313,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
     // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
     const summarySaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSummarySave } = await loadWorkflowExecutors();
         return executeSummarySave(params, process.cwd());
     };
     const summarySaveTool = {
@@ -289,17 +323,18 @@ export function registerDbTools(pi) {
             "Computes the file path from milestone/slice/task IDs automatically.",
         promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
         promptGuidelines: [
-            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).",
-            "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT).",
+            "milestone_id is required for milestone/slice/task artifacts. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT.",
             "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.",
+            "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
+            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
             "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
         ],
         parameters: Type.Object({
-            milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            milestone_id: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001). Omit only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT artifacts." })),
             slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
             task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-            artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }),
+            artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT", "PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Artifact type to save" }),
             content: Type.String({ description: "The full markdown content of the artifact" }),
         }),
         execute: summarySaveExecute,
@@ -330,6 +365,7 @@ export function registerDbTools(pi) {
         try {
             // Claim a reserved ID if the guided-flow already previewed one to the user.
             // This guarantees the ID shown in the UI matches the one materialised on disk.
+            const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId } = await import("../guided-flow.js");
             const reserved = claimReservedId();
             if (reserved) {
                 await ensureMilestoneDbRow(reserved);
@@ -408,6 +444,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
     // ─── gsd_plan_milestone (gsd_milestone_plan alias) ─────────────────────
     const planMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executePlanMilestone } = await loadWorkflowExecutors();
         return executePlanMilestone(params, process.cwd());
     };
     const planMilestoneTool = {
@@ -472,6 +509,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, planMilestoneTool, "gsd_milestone_plan", "gsd_plan_milestone");
     // ─── gsd_plan_slice (gsd_slice_plan alias) ─────────────────────────────
     const planSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executePlanSlice } = await loadWorkflowExecutors();
         return executePlanSlice(params, process.cwd());
     };
     const planSliceTool = {
@@ -585,6 +623,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, planTaskTool, "gsd_task_plan", "gsd_plan_task");
     // ─── gsd_task_complete (gsd_complete_task alias) ────────────────────────
     const taskCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeTaskComplete } = await loadWorkflowExecutors();
         return executeTaskComplete(params, process.cwd());
     };
     const taskCompleteTool = {
@@ -647,6 +686,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, taskCompleteTool, "gsd_complete_task", "gsd_task_complete");
     // ─── gsd_slice_complete (gsd_complete_slice alias) ─────────────────────
     const sliceCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSliceComplete } = await loadWorkflowExecutors();
         return executeSliceComplete(params, process.cwd());
     };
     const sliceCompleteTool = {
@@ -811,6 +851,7 @@ export function registerDbTools(pi) {
     });
     // ─── gsd_complete_milestone ────────────────────────────────────────────
     const milestoneCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeCompleteMilestone } = await loadWorkflowExecutors();
         return executeCompleteMilestone(params, process.cwd());
     };
     const milestoneCompleteTool = {
@@ -851,6 +892,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
     // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
     const milestoneValidateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeValidateMilestone } = await loadWorkflowExecutors();
         return executeValidateMilestone(params, process.cwd());
     };
     const milestoneValidateTool = {
@@ -883,6 +925,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeReplanSlice } = await loadWorkflowExecutors();
         return executeReplanSlice(params, process.cwd());
     };
     const replanSliceTool = {
@@ -925,6 +968,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, replanSliceTool, "gsd_slice_replan", "gsd_replan_slice");
     // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
     const reassessRoadmapExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeReassessRoadmap } = await loadWorkflowExecutors();
         return executeReassessRoadmap(params, process.cwd());
     };
     const reassessRoadmapTool = {
@@ -1157,6 +1201,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
     // ─── gsd_save_gate_result ──────────────────────────────────────────────
     const saveGateResultExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSaveGateResult } = await loadWorkflowExecutors();
         return executeSaveGateResult(params, process.cwd());
     };
     const saveGateResultTool = {

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { setLogBasePath, logWarning } from "../workflow-logger.js";
+import { resolveGsdPathContract } from "../paths.js";
 /**
  * Resolve the correct DB path for the current working directory.
  * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
@@ -10,67 +11,15 @@ import { setLogBasePath, logWarning } from "../workflow-logger.js";
  * returns `<basePath>/.gsd/gsd.db`.
  */
 export function resolveProjectRootDbPath(basePath) {
-    // Detect worktree: look for `.gsd/worktrees/` in the path segments.
-    // A worktree path looks like: /project/root/.gsd/worktrees/M001/...
-    // We need to resolve back to /project/root/.gsd/gsd.db
-    const marker = `${sep}.gsd${sep}worktrees${sep}`;
-    const idx = basePath.indexOf(marker);
-    if (idx !== -1) {
-        const projectRoot = basePath.slice(0, idx);
-        return join(projectRoot, ".gsd", "gsd.db");
-    }
-    // Also handle forward-slash paths on all platforms
-    const fwdMarker = "/.gsd/worktrees/";
-    const fwdIdx = basePath.indexOf(fwdMarker);
-    if (fwdIdx !== -1) {
-        const projectRoot = basePath.slice(0, fwdIdx);
-        return join(projectRoot, ".gsd", "gsd.db");
-    }
-    // External-state layout: ~/.gsd/projects/<hash>/worktrees/<MID>/...
-    // Resolve to ~/.gsd/projects/<hash>/gsd.db (the canonical project DB) (#2952).
-    // Must be checked before the generic symlink-resolved handler: both match
-    // /.gsd/projects/<hash>/worktrees/ but require different resolution targets.
-    const extRe = /[/\\]\.gsd[/\\]projects[/\\][a-f0-9]+[/\\]worktrees(?:[/\\]|$)/;
-    const extMatch = extRe.exec(basePath);
-    if (extMatch) {
-        const matchStr = extMatch[0];
-        // Find the "/worktrees" portion within the match and slice up to it
-        const wtIdx = matchStr.search(/[/\\]worktrees(?:[/\\]|$)/);
-        const projectStateRoot = basePath.slice(0, extMatch.index + wtIdx);
-        return join(projectStateRoot, "gsd.db");
-    }
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/M001/...
-    // The project root is everything before /.gsd/projects/ (#2517)
-    const symlinkMarker = `${sep}.gsd${sep}projects${sep}`;
-    const symlinkIdx = basePath.indexOf(symlinkMarker);
-    if (symlinkIdx !== -1) {
-        const afterProjects = basePath.slice(symlinkIdx + symlinkMarker.length);
-        // Expect: <hash>/worktrees/...
-        const worktreeSeg = `${sep}worktrees${sep}`;
-        if (afterProjects.includes(worktreeSeg)) {
-            const projectRoot = basePath.slice(0, symlinkIdx);
-            return join(projectRoot, ".gsd", "gsd.db");
-        }
-    }
-    // Forward-slash variant for symlink-resolved layout
-    const fwdSymlinkMarker = "/.gsd/projects/";
-    const fwdSymlinkIdx = basePath.indexOf(fwdSymlinkMarker);
-    if (fwdSymlinkIdx !== -1) {
-        const afterProjects = basePath.slice(fwdSymlinkIdx + fwdSymlinkMarker.length);
-        if (afterProjects.includes("/worktrees/")) {
-            const projectRoot = basePath.slice(0, fwdSymlinkIdx);
-            return join(projectRoot, ".gsd", "gsd.db");
-        }
-    }
-    return join(basePath, ".gsd", "gsd.db");
+    return resolveGsdPathContract(basePath).projectDb;
 }
 export async function ensureDbOpen(basePath = process.cwd()) {
     try {
         const db = await import("../gsd-db.js");
-        const dbPath = resolveProjectRootDbPath(basePath);
-        const gsdDir = join(basePath, ".gsd");
-        // Derive the project root from the DB path (strip .gsd/gsd.db)
-        const projectRoot = join(dbPath, "..", "..");
+        const contract = resolveGsdPathContract(basePath);
+        const dbPath = contract.projectDb;
+        const gsdDir = contract.projectGsd;
+        const projectRoot = dirname(dirname(dbPath));
         // Open existing DB file (may be at project root for worktrees)
         if (existsSync(dbPath)) {
             const opened = db.openDatabase(dbPath);
@@ -78,26 +27,9 @@ export async function ensureDbOpen(basePath = process.cwd()) {
                 setLogBasePath(projectRoot);
             return opened;
         }
-        // No DB file — create + migrate from Markdown if .gsd/ has content
+        // No DB file — create an empty authoritative DB. Markdown migration is
+        // explicit-only; runtime startup must not import projections into state.
         if (existsSync(gsdDir)) {
-            const hasDecisions = existsSync(join(gsdDir, "DECISIONS.md"));
-            const hasRequirements = existsSync(join(gsdDir, "REQUIREMENTS.md"));
-            const hasMilestones = existsSync(join(gsdDir, "milestones"));
-            if (hasDecisions || hasRequirements || hasMilestones) {
-                const opened = db.openDatabase(dbPath);
-                if (opened) {
-                    setLogBasePath(projectRoot);
-                    try {
-                        const { migrateFromMarkdown } = await import("../md-importer.js");
-                        migrateFromMarkdown(basePath);
-                    }
-                    catch (err) {
-                        logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${err.message}`);
-                    }
-                }
-                return opened;
-            }
-            // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
             const opened = db.openDatabase(dbPath);
             if (opened)
                 setLogBasePath(projectRoot);

package/dist/resources/extensions/gsd/bootstrap/exec-tools.js

@@ -3,11 +3,6 @@
 // Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
 // `context_mode.enabled: true` is set in preferences.
 import { Type } from "@sinclair/typebox";
-import { executeGsdExec } from "../tools/exec-tool.js";
-import { executeExecSearch } from "../tools/exec-search-tool.js";
-import { executeResume } from "../tools/resume-tool.js";
-import { loadEffectiveGSDPreferences } from "../preferences.js";
-import { logWarning } from "../workflow-logger.js";
 export function registerExecTools(pi) {
     pi.registerTool({
         name: "gsd_exec",
@@ -35,6 +30,11 @@ export function registerExecTools(pi) {
             })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const [{ executeGsdExec }, { loadEffectiveGSDPreferences }, { logWarning }] = await Promise.all([
+                import("../tools/exec-tool.js"),
+                import("../preferences.js"),
+                import("../workflow-logger.js"),
+            ]);
             let prefs = null;
             try {
                 prefs = loadEffectiveGSDPreferences();
@@ -67,6 +67,7 @@ export function registerExecTools(pi) {
             limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const { executeExecSearch } = await import("../tools/exec-search-tool.js");
             return executeExecSearch(params, {
                 baseDir: process.cwd(),
             });
@@ -85,6 +86,7 @@ export function registerExecTools(pi) {
         ],
         parameters: Type.Object({}),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const { executeResume } = await import("../tools/resume-tool.js");
             return executeResume(params, {
                 baseDir: process.cwd(),
             });