@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

package/dist/resources/extensions/gsd/guided-flow.js

@@ -42,15 +42,21 @@ export { nextMilestoneIdReserved } from "./milestone-id-reservation.js";
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { buildCloseoutMenuActions, buildIdleMenuSummary, getPrimaryCloseoutRecommendation, handleCloseoutChoice, loadCloseoutContext, } from "./closeout-wizard.js";
 import { buildRequirementsBacklogDiscussContext, countUnmappedActiveRequirements, showRequirementsBacklogReview, } from "./requirements-backlog.js";
-import { selectAndApplyModel } from "./auto-model-selection.js";
+import { selectAndApplyModel, getRegisteredToolSnapshot } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { detectWorkflowMcpLaunchConfig, resolveWorkflowMcpProjectRoot, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { usesWorkflowMcpTransport } from "./question-transport.js";
+import { getCachedWorkflowMcpProbe, probeAndCacheWorkflowMcp, warmWorkflowMcpProbeInBackground, workflowMcpProbeAdvertisesSurface, WORKFLOW_MCP_PROBE_TIMEOUT_MS, } from "./workflow-mcp-readiness-cache.js";
+import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { getPendingGate } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
-import { scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
 export { maybeHandleEmptyIntentTurn, maybeHandleReadyPhraseWithoutFiles, resetEmptyTurnCounter, } from "./guided-unit-completion.js";
 export { _getPendingAutoStart, clearPendingAutoStart, getDiscussionMilestoneId, setPendingAutoStart, } from "./pending-auto-start.js";
 export { checkAutoStartAfterDiscuss } from "./discussion-handoff.js";
@@ -368,6 +374,67 @@ async function dispatchNextDeepProjectSetupStage(entry) {
 export function resolveGuidedDispatchProjectRoot(basePath) {
     return basePath ?? process.cwd();
 }
+/**
+ * Wait until the workflow MCP server is reachable and advertising its tool
+ * surface. Returns failure details when timed out, or null when ready (or MCP
+ * is not the transport). Called inside dispatchWorkflow() so every guided-flow
+ * dispatch path is gated automatically.
+ */
+const MCP_READINESS_TIMEOUT_MS = 15_000;
+const MCP_READINESS_POLL_MS = 200;
+async function awaitWorkflowMcpReadiness(pi, ctx, basePath, options = {}) {
+    const provider = ctx.model?.provider;
+    const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined;
+    if (!usesWorkflowMcpTransport(authMode, ctx.model?.baseUrl))
+        return null;
+    const projectRoot = resolveWorkflowMcpProjectRoot(basePath);
+    const launch = detectWorkflowMcpLaunchConfig(projectRoot);
+    if (!launch)
+        return null;
+    const requiredTools = options.unitType
+        ? getRequiredWorkflowToolsForUnit(options.unitType).filter(isWorkflowToolSurfaceName)
+        : [];
+    const coversExpectedSurface = (tools) => requiredTools.length > 0
+        ? probeCoversRequiredWorkflowTools(tools, requiredTools)
+        : workflowMcpProbeAdvertisesSurface(tools);
+    const serverPrefix = `mcp__${launch.name}__`;
+    const systemPrompt = () => typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : "";
+    const systemPromptCoversExpectedSurface = () => {
+        const prompt = systemPrompt();
+        return requiredTools.length > 0
+            ? requiredTools.every((tool) => prompt.includes(`${serverPrefix}${tool}`))
+            : prompt.includes(serverPrefix);
+    };
+    const sessionAlreadyReady = () => coversExpectedSurface(getRegisteredToolSnapshot(pi)) ||
+        systemPromptCoversExpectedSurface();
+    if (sessionAlreadyReady())
+        return null;
+    if (coversExpectedSurface(getCachedWorkflowMcpProbe(projectRoot)?.tools ?? [])) {
+        return null;
+    }
+    const probe = options.probe ?? probeAndCacheWorkflowMcp;
+    const probeTimeoutMs = options.probeTimeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS;
+    ctx.ui.setStatus("gsd-step", `Waiting for ${launch.name} MCP server…`);
+    let lastError;
+    const deadline = Date.now() + (options.timeoutMs ?? MCP_READINESS_TIMEOUT_MS);
+    const pollMs = options.pollMs ?? MCP_READINESS_POLL_MS;
+    while (Date.now() < deadline) {
+        if (sessionAlreadyReady()) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        const result = await probe(projectRoot, { timeoutMs: probeTimeoutMs });
+        if (result.ok && coversExpectedSurface(result.tools)) {
+            ctx.ui.setStatus("gsd-step", "");
+            return null;
+        }
+        lastError = result.error;
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    ctx.ui.setStatus("gsd-step", "");
+    return lastError ? { server: launch.name, error: lastError } : { server: launch.name };
+}
+export const _awaitWorkflowMcpReadinessForTest = awaitWorkflowMcpReadiness;
 /**
  * Read GSD-WORKFLOW.md and dispatch it to the LLM with a contextual note.
  * This is the only way the wizard triggers work — everything else is the LLM's job.
@@ -382,7 +449,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
     const projectRoot = resolveGuidedDispatchProjectRoot(resolvedOptions.basePath);
     const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
     const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
-    const getTransportSupportError = resolvedOptions.deps?.getTransportSupportError ?? getWorkflowTransportSupportError;
+    const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
+        ?? getUnitWorkflowDispatchReadinessError;
     // Route through the dynamic routing pipeline (complexity classification,
     // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
     if (ctx && unitType) {
@@ -396,7 +464,8 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                 routing: result.routing,
             });
         }
-        const compatibilityError = getTransportSupportError(result.appliedModel?.provider ?? ctx.model?.provider, getRequiredWorkflowToolsForGuidedUnit(unitType), {
+        const compatibilityError = getDispatchReadinessError({
+            provider: result.appliedModel?.provider ?? ctx.model?.provider,
             projectRoot,
             surface: "guided flow",
             unitType,
@@ -415,6 +484,25 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
             ctx.ui.notify(compatibilityError, "error");
             return;
         }
+        // ── Live MCP readiness gate ────────────────────────────────────────
+        // Units with required workflow tools must not dispatch until the MCP
+        // surface covers that exact contract; otherwise the model can race into
+        // "No such tool available" before recovery sees a clean readiness error.
+        warmWorkflowMcpProbeInBackground(projectRoot);
+        const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+        const strictBlocking = requiredWorkflowTools.length > 0
+            && (process.env.GSD_GUIDED_MCP_BLOCKING ?? "").trim() !== "0";
+        if (strictBlocking) {
+            // If the workflow MCP server is configured but still connecting, wait
+            // for it instead of dispatching into a child session that will abort.
+            const readinessFailure = await awaitWorkflowMcpReadiness(pi, ctx, projectRoot, { unitType });
+            if (readinessFailure) {
+                const detail = readinessFailure.error ? ` ${readinessFailure.error}` : "";
+                ctx.ui.notify(`GSD workflow server "${readinessFailure.server}" did not connect in time.${detail} ` +
+                    `Run \`/gsd mcp check ${readinessFailure.server}\` for details.`, "warning");
+                return;
+            }
+        }
     }
     // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
@@ -1297,6 +1385,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
 }
 export async function showSmartEntry(ctx, pi, basePath, options) {
     const stepMode = options?.step ?? true;
+    warmWorkflowMcpProbeInBackground(basePath);
     // ── Clear stale milestone ID reservations from previous cancelled sessions ──
     // Reservations only need to survive within a single /gsd interaction.
     // Without this, each cancelled session permanently bumps the next ID. (#2488)
@@ -1529,6 +1618,21 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 deletePendingAutoStart(basePath);
             }
             else {
+                if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+                    // The discussion already produced CONTEXT but the agent_end handoff
+                    // never consumed the entry — e.g. an external-engine post-hoc gate
+                    // re-arm wiped the depth verification after the save (write-gate
+                    // two-process sync). CONTEXT can only be written through a verified
+                    // depth gate, so a gate still pending for this milestone is stale:
+                    // clear it and re-run the handoff instead of dead-ending.
+                    const gateBasePath = entry.scope.workspace.projectRoot;
+                    const pendingGateId = getPendingGate(gateBasePath);
+                    if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+                        clearPendingGate(gateBasePath);
+                    }
+                    if (checkAutoStartAfterDiscuss(basePath))
+                        return;
+                }
                 ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
                 return;
             }

package/dist/resources/extensions/gsd/health-widget.js

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Always-on ambient health signal rendered below the editor.
 import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
-import { runEnvironmentChecks } from "./doctor-environment.js";
+import { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
@@ -9,7 +9,28 @@ import { projectRoot } from "./commands/context.js";
 import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
 export const HEALTH_WIDGET_ACTIVE_HINTS = "  /gsd auto to run  ·  /gsd status to inspect  ·  /gsd report for snapshots  ·  /gsd notifications for history  ·  /gsd help";
 // ── Data loader ────────────────────────────────────────────────────────────────
-function loadHealthWidgetData(basePath) {
+// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
+// so it is treated like the other expensive checks: skipped on first paint,
+// run only by the background refresh.
+function loadLastCommitInfo(basePath) {
+    try {
+        if (nativeIsRepo(basePath)) {
+            const branch = nativeGetCurrentBranch(basePath);
+            const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+            if (epoch > 0) {
+                return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return { epoch: null, message: null };
+}
+function loadHealthWidgetData(basePath, options) {
+    // `includeChecks` gates the expensive subprocess-backed checks (provider +
+    // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
+    // synchronous render passes `false` so first paint is never blocked on them;
+    // the async refresh (off the first-paint path) runs the full suite.
+    const includeChecks = options?.includeChecks ?? true;
     let budgetCeiling;
     let budgetSpent = 0;
     let providerIssue = null;
@@ -28,13 +49,57 @@ function loadHealthWidgetData(basePath) {
         }
     }
     catch { /* non-fatal */ }
+    if (includeChecks) {
+        try {
+            const providerResults = runProviderChecks();
+            providerIssue = summariseProviderIssues(providerResults);
+        }
+        catch { /* non-fatal */ }
+        try {
+            const envResults = runEnvironmentChecks(basePath);
+            for (const r of envResults) {
+                if (r.status === "error")
+                    environmentErrorCount++;
+                else if (r.status === "warning")
+                    environmentWarningCount++;
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    // ── Last commit info ── (git spawns — gated like the other expensive checks)
+    if (includeChecks) {
+        const commit = loadLastCommitInfo(basePath);
+        lastCommitEpoch = commit.epoch;
+        lastCommitMessage = commit.message;
+    }
+    return {
+        projectState,
+        budgetCeiling,
+        budgetSpent,
+        providerIssue,
+        environmentErrorCount,
+        environmentWarningCount,
+        lastCommitEpoch,
+        lastCommitMessage,
+        lastRefreshed: Date.now(),
+    };
+}
+// Non-blocking variant used by the widget's background refresh: the cheap fields
+// come from the synchronous snapshot, then provider + environment checks are
+// layered in off the event-loop critical path (env checks run concurrently via
+// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
+// its initial enrichment or its 60s refresh.
+async function loadHealthWidgetDataAsync(basePath) {
+    const data = loadHealthWidgetData(basePath, { includeChecks: false });
+    let providerIssue = data.providerIssue;
+    let environmentErrorCount = 0;
+    let environmentWarningCount = 0;
     try {
-        const providerResults = runProviderChecks();
-        providerIssue = summariseProviderIssues(providerResults);
+        providerIssue = summariseProviderIssues(runProviderChecks());
     }
     catch { /* non-fatal */ }
     try {
-        const envResults = runEnvironmentChecks(basePath);
+        const envResults = await runEnvironmentChecksAsync(basePath);
         for (const r of envResults) {
             if (r.status === "error")
                 environmentErrorCount++;
@@ -43,27 +108,14 @@ function loadHealthWidgetData(basePath) {
         }
     }
     catch { /* non-fatal */ }
-    // ── Last commit info ──
-    try {
-        if (nativeIsRepo(basePath)) {
-            const branch = nativeGetCurrentBranch(basePath);
-            const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-            if (epoch > 0) {
-                lastCommitEpoch = epoch;
-                lastCommitMessage = nativeCommitSubject(basePath, branch || "HEAD") || null;
-            }
-        }
-    }
-    catch { /* non-fatal */ }
+    const commit = loadLastCommitInfo(basePath);
     return {
-        projectState,
-        budgetCeiling,
-        budgetSpent,
+        ...data,
         providerIssue,
         environmentErrorCount,
         environmentWarningCount,
-        lastCommitEpoch,
-        lastCommitMessage,
+        lastCommitEpoch: commit.epoch,
+        lastCommitMessage: commit.message,
         lastRefreshed: Date.now(),
     };
 }
@@ -77,8 +129,13 @@ export function initHealthWidget(ctx) {
     if (!ctx.hasUI)
         return;
     const basePath = projectRoot();
-    // String-array fallback — used in RPC mode (factory is a no-op there)
-    const initialData = loadHealthWidgetData(basePath);
+    // String-array fallback — used in RPC mode (factory is a no-op there).
+    // Skip the expensive provider/environment doctor checks here: this runs
+    // synchronously on the interactive-startup path, where running them would
+    // block first paint by ~0.9s (lsof/docker probes, otherwise run again
+    // immediately by the factory below). The factory's async refresh fills in
+    // real health once the screen is up.
+    const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
     ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
     // Factory-based widget for TUI mode — replaces the string-array above
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
@@ -91,7 +148,7 @@ export function initHealthWidget(ctx) {
                 return;
             refreshInFlight = true;
             try {
-                data = loadHealthWidgetData(basePath);
+                data = await loadHealthWidgetDataAsync(basePath);
                 cachedLines = undefined;
                 if (!isDisposed)
                     _tui.requestRender();
@@ -101,9 +158,11 @@ export function initHealthWidget(ctx) {
                 refreshInFlight = false;
             }
         };
-        // Fire first enrichment immediately. requestRender() inside is a no-op
-        // if the widget has not yet rendered, so this is safe before factory return.
-        void refresh();
+        // Fire the first full enrichment off the first-paint path. setTimeout(0)
+        // yields to the initial render + input loop, so the expensive doctor checks
+        // (provider + environment) never delay the moment the user sees the UI.
+        // requestRender() inside refresh repaints the widget once data is ready.
+        setTimeout(() => { void refresh(); }, 0);
         const refreshTimer = setInterval(() => {
             void refresh();
         }, REFRESH_INTERVAL_MS);

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -717,6 +717,16 @@ export function detectStaleRenders(basePath) {
     }
     return stale;
 }
+/**
+ * Render-verification helper: does the rendered ROADMAP markdown mark a slice
+ * as done? Used by completion code to verify/repair the *projection* after a
+ * DB write — never as a source of truth for dispatch or completion decisions
+ * (ADR-017). Lives here so decision-path modules need not import
+ * parsers-legacy directly.
+ */
+export function roadmapRenderMarksSliceDone(roadmapContent, sliceId) {
+    return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
+}
 export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanData) {
     const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
         ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);

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

@@ -0,0 +1,10 @@
+// mcp-bridge.ts — stable runtime seam for MCP server consumption (phase 1).
+export { loadWriteGateSnapshot, shouldBlockPendingGateInSnapshot, shouldBlockQueueExecutionInSnapshot, } from "./bootstrap/write-gate.js";
+export { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+export { _getAdapter, checkpointDatabase, closeDatabase, getAllMilestones, getDb, getGateResults, getMilestoneSlices, getPendingGates, getSliceTasks, insertDecision, insertMilestone, insertSlice, openDatabase, upsertMilestonePlanning, } from "./gsd-db.js";
+export { invalidateStateCache, isReusableGhostMilestone } from "./state.js";
+export { loadEffectiveGSDPreferences } from "./preferences.js";
+export { saveDecisionToDb, saveRequirementToDb, updateRequirementInDb, } from "./db-writer.js";
+export { rebuildState } from "./doctor.js";
+export { queryJournal } from "./journal.js";
+export { claimReservedId, findMilestoneIds, getReservedMilestoneIds, milestoneIdSort, nextMilestoneId, } from "./milestone-ids.js";

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

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 function isRecord(value) {
@@ -63,29 +64,11 @@ function isWorkflowMcpServerConfig(config) {
     const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
     return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
 }
-function isBrowserMcpServerConfig(config) {
-    if (!isRecord(config))
-        return false;
-    const command = typeof config.command === "string" ? config.command : "";
-    if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
-        return true;
-    }
-    const env = config.env;
-    if (isRecord(env)) {
-        if (typeof env.GSD_BROWSER_CLI_PATH === "string"
-            || typeof env.GSD_BROWSER_BIN_PATH === "string"
-            || typeof env.GSD_BROWSER_MCP_COMMAND === "string") {
-            return true;
-        }
-    }
-    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
-    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
-}
 export function discoverWorkflowMcpServerName(projectDir) {
     return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
 }
 export function discoverBrowserMcpServerName(projectDir) {
-    return discoverMcpServers(projectDir).find((server) => isBrowserMcpServerConfig(server.config))?.name;
+    return discoverMcpServers(projectDir).find((server) => isGsdBrowserMcpServerConfig(server.config))?.name;
 }
 export function discoverMcpServerNames(projectDir) {
     return discoverMcpServers(projectDir).map((server) => server.name);

package/dist/resources/extensions/gsd/mcp-tool-name.js

@@ -1,20 +1,12 @@
 // Project/App: gsd-pi
-// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+// File Purpose: GSD-facing face over the shared @gsd/pi-ai MCP tool-name helpers.
+import { parseMcpToolName as parsePiAiMcpToolName, stripMcpToolPrefix } from "@gsd/pi-ai";
 const MCP_TOOL_PREFIX = "mcp__";
 export function parseMcpToolName(toolName) {
-    if (!toolName.startsWith(MCP_TOOL_PREFIX))
-        return null;
-    const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
-    if (toolSeparator < 0)
-        return null;
-    return {
-        serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
-        toolName: toolName.slice(toolSeparator + 2),
-    };
-}
-export function stripMcpToolPrefix(toolName) {
-    return parseMcpToolName(toolName)?.toolName ?? toolName;
+    const parsed = parsePiAiMcpToolName(toolName);
+    return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
 }
+export { stripMcpToolPrefix };
 export function toMcpToolName(serverName, toolName) {
     return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
 }

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -211,7 +211,7 @@ export function reportConsolidationGaps(basePath) {
         const report = scanConsolidationGaps(basePath);
         if (report.totalGaps === 0)
             return report;
-        appendNotification(report.summary, "warning", "workflow-logger");
+        appendNotification(report.summary, "warning", "workflow-logger", { kind: "memory-consolidation" });
         logWarning("memory-consolidation", report.summary);
         return report;
     }

package/dist/resources/extensions/gsd/migrate/safety.js

@@ -8,6 +8,7 @@ import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
 import { closeWorkflowDatabase } from "../db-workspace.js";
 import { readPausedSessionMetadata } from "../interrupted-session.js";
 import { gsdRoot } from "../paths.js";
+import { canonicalWorktreesDir } from "../worktree-placement.js";
 export class MigrationBlockedError extends Error {
     constructor(message) {
         super(message);
@@ -78,8 +79,10 @@ export function assertMigrationHasSlices(preview) {
     throw new MigrationBlockedError("Migration blocked - the legacy project would produce zero slices. Add a ROADMAP.md or phases/ content before migrating.");
 }
 function hasWorktreeState(targetRoot) {
+    // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+    // migration targets may have .gsd in the external-state layout.
     const containers = [
-        join(targetRoot, ".gsd-worktrees"),
+        canonicalWorktreesDir(targetRoot),
         join(gsdRoot(targetRoot), "worktrees"),
     ];
     for (const worktreesDir of containers) {

package/dist/resources/extensions/gsd/milestone-closeout.js

@@ -4,13 +4,16 @@
 // - preflight: dispatch git clean before complete-milestone agent (auto-dispatch)
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
+import { existsSync } from "node:fs";
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { getMilestone, getClosedSliceIds, getLatestAssessmentByScope, getMilestoneSlices, isDbAvailable, } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
+import { uatSignoffBlockerGuidance } from "./guidance.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
@@ -19,6 +22,60 @@ import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(_basePath, milestoneId) {
+    if (!isDbAvailable())
+        return false;
+    const milestone = getMilestone(milestoneId);
+    if (!milestone)
+        return false;
+    if (isClosedStatus(milestone.status)) {
+        return true;
+    }
+    const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (validation?.status !== "pass") {
+        return false;
+    }
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0)
+        return false;
+    return slices.every((slice) => isClosedStatus(slice.status));
+}
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(basePath, milestoneId) {
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) {
+        return { ok: false, error: `milestone not found: ${milestoneId}` };
+    }
+    const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+    if (summaryPath && existsSync(summaryPath)) {
+        return { ok: true };
+    }
+    const result = await handleCompleteMilestone({
+        milestoneId,
+        title: milestone.title,
+        oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+        narrative: "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+            "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+        verificationPassed: true,
+        triggerReason: "closeout-projection-repair",
+    }, basePath);
+    if ("error" in result) {
+        return { ok: false, error: result.error };
+    }
+    const writtenSummaryPath = result.summaryPath;
+    if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+        return { ok: false, error: "milestone SUMMARY projection write failed" };
+    }
+    return { ok: true };
+}
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -65,38 +122,42 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
     if (isDbAvailable()) {
         const milestone = getMilestone(mid);
         if (milestone && isClosedStatus(milestone.status)) {
-            return { action: "skip" };
+            const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+            const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+            const summaryMissing = !summaryPath || !existsSync(summaryPath);
+            if (summaryMissing) {
+                const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+                if (!repair.ok) {
+                    logWarning("dispatch", `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`);
+                }
+                else {
+                    return { action: "skip" };
+                }
+            }
+            else {
+                return { action: "skip" };
+            }
         }
     }
     const closeoutGitStop = commitPendingMilestoneCloseoutChanges(basePath, mid);
     if (closeoutGitStop)
         return closeoutGitStop;
     if (prefs?.uat_dispatch) {
-        let closedSliceIds;
-        if (isDbAvailable()) {
-            closedSliceIds = getMilestoneSlices(mid)
-                .filter((slice) => isClosedStatus(slice.status))
-                .map((slice) => slice.id);
-        }
-        else {
-            const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-            const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-            if (!roadmapContent) {
-                return {
-                    action: "stop",
-                    reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because ROADMAP is unavailable while DB is not accessible.`,
-                    level: "warning",
-                };
-            }
-            const roadmap = parseRoadmap(roadmapContent);
-            closedSliceIds = roadmap.slices.filter((slice) => slice.done).map((slice) => slice.id);
+        // DB-authoritative (ADR-017): UAT sign-off gating never parses the
+        // ROADMAP projection. Without a DB we cannot verify — stop conservatively.
+        if (!isDbAvailable()) {
+            return {
+                action: "stop",
+                reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because the workflow DB is not accessible.`,
+                level: "warning",
+            };
         }
-        for (const sliceId of closedSliceIds) {
+        for (const sliceId of getClosedSliceIds(mid)) {
             const result = await readUatGateVerdict(basePath, mid, sliceId);
             if (!result) {
                 return {
                     action: "stop",
-                    reason: `Cannot complete milestone ${mid}: missing UAT PASS verdict for ${sliceId}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+                    reason: uatSignoffBlockerGuidance(mid, sliceId),
                     level: "warning",
                 };
             }
@@ -104,7 +165,7 @@ export async function evaluateCompleteMilestoneDispatch(ctx) {
             if (!isAcceptableUatVerdict(verdict, uatType)) {
                 return {
                     action: "stop",
-                    reason: `Cannot complete milestone ${mid}: UAT verdict for ${sliceId} is "${verdict}". Manual UAT sign-off (PASS) is required before milestone closure.`,
+                    reason: uatSignoffBlockerGuidance(mid, sliceId, verdict),
                     level: "warning",
                 };
             }

package/dist/resources/extensions/gsd/milestone-planning-persistence.js

@@ -5,7 +5,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { transaction, getMilestone, getMilestoneSlices, getSlice, insertMilestone, insertSlice, upsertMilestonePlanning, upsertSlicePlanning, } from "./gsd-db.js";
 import { invalidateStateCache } from "./state.js";
 import { renderRoadmapFromDb } from "./markdown-renderer.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 import { writeManifest } from "./workflow-manifest.js";
 import { appendEvent } from "./workflow-events.js";
 import { logWarning } from "./workflow-logger.js";
@@ -109,7 +109,7 @@ async function renderPlanArtifacts(basePath, params) {
 }
 async function runPostPlanHooks(basePath, params) {
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "plan-milestone",

package/dist/resources/extensions/gsd/milestone-reopen-events.js

@@ -1,11 +1,9 @@
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import { workflowEventArchivePath, workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 export function latestExplicitReopenAt(basePath, milestoneId) {
-    const root = gsdRoot(basePath);
     const candidates = [
-        join(root, "event-log.jsonl"),
-        join(root, `event-log-${milestoneId}.jsonl.archived`),
+        workflowEventLogPath(basePath),
+        workflowEventArchivePath(basePath, milestoneId),
     ];
     let latest = null;
     for (const file of candidates) {