gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2d3fd6e71

package/dist/resources/extensions/gsd/uok/plan-v2.js

@@ -48,6 +48,9 @@ export function hasFinalizedMilestoneContext(basePath, milestoneId) {
 export function isMissingFinalizedContextResult(result) {
     return !result.ok && result.finalizedContextIncluded === false;
 }
+export function isEmptyPlanV2GraphResult(result) {
+    return !result.ok && result.emptyGraph === true;
+}
 function countSliceResearchArtifacts(basePath, milestoneId, slices) {
     let count = 0;
     for (const slice of slices) {
@@ -138,6 +141,7 @@ export function compileUnitGraphFromState(basePath, state) {
         ok: true,
         graphPath: outPath,
         nodeCount: nodes.length,
+        sliceCount: slices.length,
         clarifyRoundLimit,
         researchSynthesized: output.pipeline.researchSynthesized,
         draftContextIncluded: output.pipeline.draftContextIncluded,
@@ -149,7 +153,16 @@ export function ensurePlanV2Graph(basePath, state) {
     if (!compiled.ok)
         return compiled;
     if ((compiled.nodeCount ?? 0) <= 0) {
-        return { ok: false, reason: "compiled graph is empty" };
+        if ((state.phase === "validating-milestone" || state.phase === "completing-milestone") &&
+            (compiled.sliceCount ?? 0) > 0) {
+            return compiled;
+        }
+        return {
+            ...compiled,
+            ok: false,
+            reason: "compiled graph is empty",
+            emptyGraph: true,
+        };
     }
     return compiled;
 }

package/dist/resources/extensions/gsd/user-input-boundary.js

@@ -0,0 +1,157 @@
+const USER_APPROVAL_UNIT_TYPES = new Set([
+    "discuss-project",
+    "discuss-requirements",
+    "discuss-milestone",
+    "research-decision",
+]);
+const REMOTE_QUESTION_FAILURE_RE = /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
+const APPROVAL_WAIT_RE = /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
+const APPROVAL_QUESTION_RE = /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
+const APPROVAL_RIGHT_QUESTION_RE = /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
+const APPROVAL_CHANGE_QUESTION_RE = /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
+const RESEARCH_DECISION_QUESTION_RE = /\b(?:research|skip)\b/i;
+function extractTextFromMessage(msg) {
+    if (!msg || typeof msg !== "object")
+        return "";
+    const content = msg.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const typed = block;
+        if (typed.type === "text" && typeof typed.text === "string") {
+            parts.push(typed.text);
+        }
+    }
+    return parts.join("\n");
+}
+function lastAssistantText(messages) {
+    if (!Array.isArray(messages))
+        return "";
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (!msg || typeof msg !== "object")
+            continue;
+        if (msg.role !== "assistant")
+            continue;
+        const text = extractTextFromMessage(msg).trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+function anyMessageMatches(messages, pattern) {
+    if (!Array.isArray(messages))
+        return false;
+    return messages.some((msg) => {
+        if (!msg || typeof msg !== "object")
+            return false;
+        if (msg.role === "user")
+            return false;
+        return pattern.test(extractTextFromMessage(msg));
+    });
+}
+function hasApprovalQuestion(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "?")
+            continue;
+        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
+        const fragment = text.slice(previousBreak + 1, i + 1);
+        if (APPROVAL_QUESTION_RE.test(fragment))
+            return true;
+        if (APPROVAL_RIGHT_QUESTION_RE.test(fragment))
+            return true;
+        if (APPROVAL_CHANGE_QUESTION_RE.test(fragment))
+            return true;
+    }
+    return false;
+}
+function hasResearchDecisionQuestion(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] !== "?")
+            continue;
+        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
+        const fragment = text.slice(previousBreak + 1, i + 1);
+        if (RESEARCH_DECISION_QUESTION_RE.test(fragment))
+            return true;
+    }
+    return false;
+}
+export function approvalGateIdForUnit(unitType, unitId) {
+    if (!unitType)
+        return null;
+    if (unitType === "discuss-project")
+        return "depth_verification_project_confirm";
+    if (unitType === "discuss-requirements")
+        return "depth_verification_requirements_confirm";
+    if (unitType === "research-decision")
+        return "depth_verification_research_decision_confirm";
+    if (unitType === "discuss-milestone") {
+        const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
+            ? unitId
+            : "milestone";
+        return `depth_verification_${safeUnitId}_confirm`;
+    }
+    return null;
+}
+const CHANGE_REQUEST_RESPONSE_RE = /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
+const APPROVAL_RESPONSE_RE = /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
+const RESEARCH_DECISION_RESPONSE_RE = /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
+export function isExplicitApprovalResponse(input, pendingGateId) {
+    const text = input?.trim() ?? "";
+    if (!text)
+        return false;
+    if (pendingGateId?.includes("research_decision")) {
+        return RESEARCH_DECISION_RESPONSE_RE.test(text);
+    }
+    if (CHANGE_REQUEST_RESPONSE_RE.test(text))
+        return false;
+    return APPROVAL_RESPONSE_RE.test(text);
+}
+export function isAwaitingUserInput(messages) {
+    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
+        return true;
+    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
+        return true;
+    const text = lastAssistantText(messages);
+    if (!text)
+        return false;
+    if (APPROVAL_WAIT_RE.test(text))
+        return true;
+    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (lines.some((line) => line.endsWith("?")))
+        return true;
+    return hasApprovalQuestion(text);
+}
+export function isAwaitingApprovalBoundary(messages) {
+    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
+        return true;
+    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
+        return true;
+    const text = lastAssistantText(messages);
+    if (!text)
+        return false;
+    if (APPROVAL_WAIT_RE.test(text))
+        return true;
+    return hasApprovalQuestion(text);
+}
+export function shouldPauseForUserApprovalQuestion(unitType, messages) {
+    if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType))
+        return false;
+    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
+        return true;
+    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
+        return true;
+    const text = lastAssistantText(messages);
+    if (!text)
+        return false;
+    if (APPROVAL_WAIT_RE.test(text))
+        return true;
+    if (unitType === "research-decision")
+        return hasResearchDecisionQuestion(text);
+    return hasApprovalQuestion(text);
+}

package/dist/resources/extensions/gsd/watch/header-renderer.js

@@ -6,6 +6,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { visibleWidth, truncateToWidth } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { gsdHome } from "../gsd-home.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 /**
  * GSD ASCII logo — inlined here because the canonical src/logo.ts is outside
@@ -104,7 +105,7 @@ export function readMcpServerNames(projectRoot) {
     const configPaths = [
         join(projectRoot, ".mcp.json"),
         join(projectRoot, ".gsd", "mcp.json"),
-        join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+        join(gsdHome(), "mcp.json"),
     ];
     const names = [];
     const seen = new Set();

package/dist/resources/extensions/gsd/workflow-install.js

@@ -14,11 +14,11 @@
  * clean up and future `/gsd workflow update` can refresh.
  */
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
-import { homedir } from "node:os";
 import { extname, join, resolve, sep as pathSep } from "node:path";
 import { createHash } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 import { validateDefinition } from "./definition-loader.js";
+import { gsdHome } from "./gsd-home.js";
 // ─── Constants ───────────────────────────────────────────────────────────
 const MAX_RESPONSE_BYTES = 256 * 1024;
 const FETCH_TIMEOUT_MS = 15_000;
@@ -42,8 +42,7 @@ function writeProvenance(dir, data) {
     writeFileSync(provenancePath(dir), JSON.stringify(data, null, 2) + "\n", "utf-8");
 }
 export function globalInstallDir() {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    return join(gsdHome, "workflows");
+    return join(gsdHome(), "workflows");
 }
 export function projectInstallDir(basePath) {
     return join(basePath, ".gsd", "workflows");

package/dist/resources/extensions/gsd/workflow-manifest.js

@@ -42,7 +42,7 @@ export function snapshotState() {
     // Wrap all reads in a deferred transaction so the snapshot is consistent
     // (all SELECTs see the same DB state even if a concurrent write lands between them).
     return readTransaction(() => {
-        const rawMilestones = db.prepare("SELECT * FROM milestones ORDER BY id").all();
+        const rawMilestones = db.prepare("SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id").all();
         const milestones = rawMilestones.map((r) => ({
             id: r["id"],
             title: r["title"],
@@ -61,6 +61,7 @@ export function snapshotState() {
             definition_of_done: JSON.parse(r["definition_of_done"] || "[]"),
             requirement_coverage: r["requirement_coverage"] ?? "",
             boundary_map_markdown: r["boundary_map_markdown"] ?? "",
+            sequence: Number(r["sequence"] ?? 0),
         }));
         const rawSlices = db.prepare("SELECT * FROM slices ORDER BY milestone_id, sequence, id").all();
         const slices = rawSlices.map((r) => ({

package/dist/resources/extensions/gsd/workflow-mcp-auto-prep.js

@@ -13,31 +13,13 @@ function getAuthModeSafe(ctx, provider) {
         return undefined;
     }
 }
-function hasClaudeCodeProvider(ctx) {
-    return getAuthModeSafe(ctx, "claude-code") === "externalCli";
-}
-function isClaudeCodeProviderReady(ctx) {
-    const readyCheck = ctx.modelRegistry?.isProviderRequestReady;
-    if (typeof readyCheck !== "function")
-        return false;
-    try {
-        return readyCheck("claude-code");
-    }
-    catch {
-        return false;
-    }
-}
 export function shouldAutoPrepareWorkflowMcp(ctx) {
     const provider = ctx.model?.provider;
     const baseUrl = ctx.model?.baseUrl;
     const authMode = getAuthModeSafe(ctx, provider);
-    if (usesWorkflowMcpTransport(authMode, baseUrl))
-        return true;
-    if (provider === "claude-code")
-        return true;
-    if (hasClaudeCodeProvider(ctx))
-        return true;
-    return isClaudeCodeProviderReady(ctx);
+    if (provider !== "claude-code")
+        return false;
+    return usesWorkflowMcpTransport(authMode, baseUrl) || authMode === "externalCli";
 }
 export function prepareWorkflowMcpForProject(ctx, projectRoot) {
     if (!shouldAutoPrepareWorkflowMcp(ctx))

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -167,7 +167,7 @@ function buildWorkflowLaunchEnv(projectRoot, gsdCliPath, explicitEnv, workflowCl
         : explicitEnv?.NODE_OPTIONS;
     return {
         ...(explicitEnv ?? {}),
-        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
+        ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
         ...(executorModulePath ? { GSD_WORKFLOW_EXECUTORS_MODULE: executorModulePath } : {}),
         ...(writeGateModulePath ? { GSD_WORKFLOW_WRITE_GATE_MODULE: writeGateModulePath } : {}),
         ...(nodeOptions ? { NODE_OPTIONS: nodeOptions } : {}),
@@ -181,7 +181,10 @@ export function detectWorkflowMcpLaunchConfig(projectRoot = process.cwd(), env =
     const explicitArgs = parseJsonEnv(env, "GSD_WORKFLOW_MCP_ARGS");
     const explicitEnv = parseJsonEnv(env, "GSD_WORKFLOW_MCP_ENV");
     const explicitCwd = env.GSD_WORKFLOW_MCP_CWD?.trim();
-    const gsdCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+    const gsdCliPath = explicitEnv?.GSD_CLI_PATH?.trim()
+        || explicitEnv?.GSD_BIN_PATH?.trim()
+        || env.GSD_CLI_PATH?.trim()
+        || env.GSD_BIN_PATH?.trim();
     const workflowProjectRoot = explicitEnv?.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
         env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
         env.GSD_PROJECT_ROOT?.trim() ||
@@ -243,6 +246,12 @@ export function buildWorkflowMcpServers(projectRoot = process.cwd(), env = proce
 }
 export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
     switch (unitType) {
+        case "discuss-project":
+            return ["ask_user_questions", "gsd_summary_save"];
+        case "discuss-requirements":
+            return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+        case "research-decision":
+            return ["ask_user_questions"];
         case "discuss-milestone":
             return ["gsd_summary_save", "gsd_plan_milestone"];
         case "discuss-slice":
@@ -264,6 +273,12 @@ export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
 }
 export function getRequiredWorkflowToolsForAutoUnit(unitType) {
     switch (unitType) {
+        case "discuss-project":
+            return ["ask_user_questions", "gsd_summary_save"];
+        case "discuss-requirements":
+            return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+        case "research-decision":
+            return ["ask_user_questions"];
         case "discuss-milestone":
             return ["gsd_summary_save", "gsd_plan_milestone"];
         case "research-milestone":
@@ -277,9 +292,9 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType) {
         case "execute-task":
         case "execute-task-simple":
         case "reactive-execute":
-            return ["gsd_complete_task"];
+            return ["gsd_task_complete"];
         case "complete-slice":
-            return ["gsd_complete_slice"];
+            return ["gsd_slice_complete"];
         case "replan-slice":
             return ["gsd_replan_slice"];
         case "reassess-roadmap":
@@ -297,9 +312,30 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType) {
 export function usesWorkflowMcpTransport(authMode, baseUrl) {
     return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
 }
+function hasAskUserQuestionsTool(activeTools) {
+    return activeTools.some((toolName) => {
+        if (toolName === "ask_user_questions")
+            return true;
+        if (!toolName.startsWith("mcp__"))
+            return false;
+        const toolSeparator = toolName.indexOf("__", "mcp__".length);
+        return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === "ask_user_questions";
+    });
+}
+function workflowMcpStructuredQuestionsOptIn(env = process.env) {
+    const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
+    return value === "1" || value === "true";
+}
 export function supportsStructuredQuestions(activeTools, options = {}) {
-    if (!activeTools.includes("ask_user_questions"))
+    if (!hasAskUserQuestionsTool(activeTools))
         return false;
+    if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) {
+        // Claude Code local workflow-MCP exposes ask_user_questions, but form
+        // elicitation can return an immediate cancel outside GSD's chat turn. Keep
+        // checkpoints in plain chat unless a caller deliberately opts into testing
+        // that transport.
+        return workflowMcpStructuredQuestionsOptIn(options.env);
+    }
     return true;
 }
 export function getWorkflowTransportSupportError(provider, requiredTools, options = {}) {

package/dist/resources/extensions/gsd/workflow-migration.js

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import { _getAdapter, bulkInsertLegacyHierarchy } from "./gsd-db.js";
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { logWarning } from "./workflow-logger.js";
+import { resolveMilestoneFile } from "./paths.js";
 // ─── needsAutoMigration ───────────────────────────────────────────────────
 /**
  * Returns true when engine tables are empty AND a .gsd/milestones/ directory
@@ -82,11 +83,11 @@ export function migrateFromMarkdown(basePath) {
     for (const mId of milestoneDirs) {
         const mDir = join(milestonesDir, mId);
         // Determine milestone status: done if a milestone-level SUMMARY.md exists
-        const milestoneSummaryPath = join(mDir, "SUMMARY.md");
+        const milestoneSummaryPath = resolveMilestoneFile(basePath, mId, "SUMMARY") ?? join(mDir, "SUMMARY.md");
         const milestoneDone = existsSync(milestoneSummaryPath);
         const milestoneStatus = milestoneDone ? "done" : "active";
         // Parse ROADMAP.md for slices list
-        const roadmapPath = join(mDir, "ROADMAP.md");
+        const roadmapPath = resolveMilestoneFile(basePath, mId, "ROADMAP") ?? join(mDir, "ROADMAP.md");
         let roadmapSlices = [];
         if (existsSync(roadmapPath)) {
             try {
@@ -231,7 +232,7 @@ export function validateMigration(basePath) {
         mdMilestoneCount = milestoneDirs.length;
         for (const mId of milestoneDirs) {
             const mDir = join(milestonesDir, mId);
-            const roadmapPath = join(mDir, "ROADMAP.md");
+            const roadmapPath = resolveMilestoneFile(basePath, mId, "ROADMAP") ?? join(mDir, "ROADMAP.md");
             if (existsSync(roadmapPath)) {
                 try {
                     const content = readFileSync(roadmapPath, "utf-8");

package/dist/resources/extensions/gsd/workflow-plugins.js

@@ -15,24 +15,22 @@
 import { readFileSync, readdirSync, existsSync, statSync, } from "node:fs";
 import { join, dirname, extname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { parse as parseYaml } from "yaml";
 import { loadRegistry } from "./workflow-templates.js";
+import { gsdHome } from "./gsd-home.js";
 // ─── Path resolution ─────────────────────────────────────────────────────
 function resolveBundledDir() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
     const local = join(moduleDir, "workflow-templates");
     if (existsSync(local))
         return local;
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd", "workflow-templates");
+    const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd", "workflow-templates");
     if (existsSync(agentGsdDir))
         return agentGsdDir;
     return local;
 }
 function globalPluginsDir() {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    return join(gsdHome, "workflows");
+    return join(gsdHome(), "workflows");
 }
 function projectPluginsDir(basePath) {
     return join(basePath, ".gsd", "workflows");

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -5,7 +5,7 @@ import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
 import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, openDatabase, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
 import { invalidateStateCache } from "./state.js";
-import { clearPathCache } from "./paths.js";
+import { clearPathCache, resolveGsdPathContract } from "./paths.js";
 import { clearParseCache } from "./files.js";
 import { writeManifest } from "./workflow-manifest.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -407,7 +407,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
     atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
     // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
-    openDatabase(join(mainBasePath, ".gsd", "gsd.db"));
+    openDatabase(resolveGsdPathContract(mainBasePath).projectDb);
     replayEvents(merged);
     // Step 9: Write manifest
     try {
@@ -540,7 +540,7 @@ pick) {
     const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
     writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
     // Replay resolved events through the DB (updates DB state)
-    openDatabase(join(basePath, ".gsd", "gsd.db"));
+    openDatabase(resolveGsdPathContract(basePath).projectDb);
     replayEvents(eventsToReplay);
     invalidateStateCache();
     clearPathCache();

package/dist/resources/extensions/gsd/workflow-templates.js

@@ -7,7 +7,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { gsdHome } from "./gsd-home.js";
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
 /** Resolve the GSD extension dir with fallback to ~/.gsd/agent/extensions/gsd/. */
@@ -15,8 +15,7 @@ function resolveGsdExtensionDir() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
     if (existsSync(join(moduleDir, "workflow-templates")))
         return moduleDir;
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+    const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd");
     if (existsSync(join(agentGsdDir, "workflow-templates")))
         return agentGsdDir;
     return moduleDir;

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

@@ -0,0 +1,59 @@
+// GSD-2 + Workspace handle: single source of truth for path resolution per milestone
+import { join, resolve } from "node:path";
+import { resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+function tryRealpath(p) {
+    return normalizeRealPath(p);
+}
+/**
+ * Create an immutable GsdWorkspace handle from a raw base path.
+ * Resolves both the project root and (when applicable) the worktree root,
+ * normalizes them via realpath, and freezes the result.
+ */
+export function createWorkspace(rawBasePath) {
+    const resolvedBase = resolve(rawBasePath);
+    const isWorktree = isGsdWorktreePath(resolvedBase);
+    const projectRootRaw = resolveWorktreeProjectRoot(resolvedBase);
+    const projectRoot = tryRealpath(resolve(projectRootRaw));
+    const worktreeRoot = isWorktree ? tryRealpath(resolvedBase) : null;
+    // Derive a canonical base from the already-realpath-normalized paths so that
+    // resolveGsdPathContract always receives a canonical path. Using the raw
+    // resolvedBase here can produce a non-canonical projectGsd when the input
+    // path contains symlinks, causing contract.projectGsd to diverge from the
+    // realpath-normalized projectRoot / identityKey.
+    const canonicalBase = isWorktree ? (worktreeRoot ?? resolvedBase) : projectRoot;
+    const contract = Object.freeze(resolveGsdPathContract(canonicalBase));
+    const identityKey = tryRealpath(projectRoot);
+    const mode = isWorktree ? "worktree" : "project";
+    const workspace = Object.freeze({
+        projectRoot,
+        worktreeRoot,
+        mode,
+        contract,
+        identityKey,
+        lockRoot: projectRoot,
+    });
+    return workspace;
+}
+/**
+ * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
+ * with path-returning closures that resolve via the authoritative projectGsd.
+ *
+ * All milestone-content paths route to contract.projectGsd (canonical),
+ * since that is the authoritative source of truth regardless of worktree mode.
+ */
+export function scopeMilestone(workspace, milestoneId) {
+    const { contract } = workspace;
+    const gsd = contract.projectGsd;
+    const scope = Object.freeze({
+        workspace,
+        milestoneId,
+        contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
+        roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+        stateFile: () => join(gsd, "STATE.md"),
+        dbPath: () => contract.projectDb,
+        milestoneDir: () => join(gsd, "milestones", milestoneId),
+        metaJson: () => join(gsd, `${milestoneId}-META.json`),
+    });
+    return scope;
+}

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

@@ -13,7 +13,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { autoCommitCurrentBranch, getMainBranch, nudgeGitBranchCache } from "./worktree.js";
 import { runWorktreePostCreateHook } from "./auto-worktree.js";
 import { showConfirm } from "../shared/tui.js";
-import { gsdRoot, milestonesDir } from "./paths.js";
+import { gsdRoot, milestonesDir, resolveGsdPathContract } from "./paths.js";
 import { createWorktree, listWorktrees, removeWorktree, mergeWorktreeToMain, diffWorktreeAll, diffWorktreeNumstat, getWorktreeGSDDiff, getWorktreeCodeDiff, getWorktreeLog, worktreeBranchName, worktreePath, } from "./worktree-manager.js";
 import { inferCommitType } from "./git-service.js";
 import { existsSync, realpathSync, readdirSync, rmSync, unlinkSync } from "node:fs";
@@ -530,8 +530,9 @@ async function handleMerge(basePath, name, ctx, pi, targetBranch) {
         const commitType = inferCommitType(name);
         const commitMessage = `${commitType}: merge worktree ${name}\n\nGSD-Worktree: ${name}`;
         // Reconcile worktree DB into main DB before squash merge
-        const wtDbPath = join(worktreePath(basePath, name), ".gsd", "gsd.db");
-        const mainDbPath = join(basePath, ".gsd", "gsd.db");
+        const contract = resolveGsdPathContract(worktreePath(basePath, name), basePath);
+        const wtDbPath = join(contract.worktreeGsd ?? join(contract.workRoot, ".gsd"), "gsd.db");
+        const mainDbPath = contract.projectDb;
         if (existsSync(wtDbPath) && existsSync(mainDbPath)) {
             try {
                 const { reconcileWorktreeDb } = await import("./gsd-db.js");

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

@@ -638,9 +638,9 @@ export function diffWorktreeGSD(basePath, name) {
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath, name) {
+export function diffWorktreeAll(basePath, name, branchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
-    const branch = worktreeBranchName(name);
+    const branch = branchOverride ?? worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
     return parseDiffNameStatus(entries);
@@ -649,9 +649,9 @@ export function diffWorktreeAll(basePath, name) {
  * Get per-file line addition/deletion stats for what will change on main.
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
-export function diffWorktreeNumstat(basePath, name) {
+export function diffWorktreeNumstat(basePath, name, branchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
-    const branch = worktreeBranchName(name);
+    const branch = branchOverride ?? worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
     const stats = [];
@@ -697,9 +697,9 @@ export function getWorktreeLog(basePath, name) {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath, name, commitMessage) {
+export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverride) {
     basePath = normalizeBasePathForWorktreeOps(basePath);
-    const branch = worktreeBranchName(name);
+    const branch = branchOverride ?? worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const current = nativeGetCurrentBranch(basePath);
     if (current !== mainBranch) {