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

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

@@ -28,13 +28,17 @@ export function buildGsdHomeModel(state, closeout) {
     const workLabel = activeWorkLabel(state);
     const strandedQuick = closeout?.strandedQuick ?? null;
     const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+    const idleResidueHint = closeout?.idleResidueHint ?? null;
+    const hasIdleResidue = Boolean(idleResidueHint);
     const nextReason = complete
         ? "all milestones are complete"
         : blocked
             ? "the active milestone is blocked"
-            : !hasActiveWork
-                ? "there is no active milestone"
-                : "";
+            : hasIdleResidue
+                ? "milestone git residue needs recovery"
+                : !hasActiveWork
+                    ? "there is no active milestone"
+                    : "";
     const canAdvance = hasActiveWork && !blocked && !complete;
     const unmappedActive = complete ? countUnmappedActiveRequirements() : 0;
     const recommended = strandedQuick
@@ -43,11 +47,13 @@ export function buildGsdHomeModel(state, closeout) {
             ? "finish_milestone"
             : blocked
                 ? "fix_recover"
-                : canAdvance
-                    ? "continue_step"
-                    : complete && unmappedActive > 0
-                        ? "review_requirements_backlog"
-                        : "start_configure";
+                : hasIdleResidue
+                    ? "fix_recover"
+                    : canAdvance
+                        ? "continue_step"
+                        : complete && unmappedActive > 0
+                            ? "review_requirements_backlog"
+                            : "start_configure";
     const completionSummary = complete
         ? appendRequirementsBacklogToSummary(state, [
             `All milestones complete${state.lastCompletedMilestone ? ` after ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}` : ""}.`,
@@ -57,7 +63,9 @@ export function buildGsdHomeModel(state, closeout) {
         ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
         : unmergedMilestone
             ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
-            : completionSummary;
+            : idleResidueHint
+                ? [idleResidueHint.message]
+                : completionSummary;
     return {
         title: "GSD — What now?",
         summary: [
@@ -130,10 +138,12 @@ export function buildGsdHomeModel(state, closeout) {
                 label: "Fix or recover",
                 description: blocked
                     ? "Review the blocker and recovery commands for the active milestone."
-                    : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-                enabled: blocked,
+                    : hasIdleResidue
+                        ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
+                        : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
+                enabled: blocked || hasIdleResidue,
                 recommended: recommended === "fix_recover",
-                disabledReason: blocked ? undefined : "no blocker is active",
+                disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
             },
             {
                 id: "start_configure",

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

@@ -169,7 +169,7 @@ export function insertArtifact(a) {
 export function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
+    const result = getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
       verification_contract, verification_integration, verification_operational, verification_uat,
@@ -199,6 +199,7 @@ export function insertMilestone(m) {
         ":requirement_coverage": m.planning?.requirementCoverage ?? "",
         ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
     });
+    return (result.changes ?? 0) > 0;
 }
 export function upsertMilestonePlanning(milestoneId, planning) {
     if (!getDbOrNull())

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

@@ -0,0 +1,158 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance) {
+    if (guidance.steps.length === 0)
+        return guidance.summary;
+    const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+    return `${guidance.summary}\n\n${numbered}`;
+}
+const RECOVERY_REMEDIATION = {
+    "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+    "tool-contract": "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+    "tool-unavailable": "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+    "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+    "lifecycle-progression": "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+    "stale-worker": "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+    "worktree-invalid": "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+    "verification-drift": "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+    "reconciliation-drift": "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+    "illegal-transition": "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+    "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+    "provider-transient": "Retry after the provider/network condition clears.",
+    "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+export function recoveryRemediation(key) {
+    return RECOVERY_REMEDIATION[key];
+}
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+export function needsAttentionBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+        `Fix options:`,
+        `1. Review the validation details: \`/gsd status\``,
+        `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+        `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+        `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+    ].join("\n");
+}
+export function needsRemediationBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+        `Fix options:`,
+        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+        `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    ].join("\n");
+}
+// ─── Milestone closeout UAT sign-off blockers ───────────────────────────
+// The first sentence is the blocker finding; the numbered steps are the
+// resolution path. `verdict` is the recorded non-PASS verdict, or undefined
+// when no verdict has been recorded at all.
+export function uatSignoffBlockerGuidance(milestoneId, sliceId, verdict) {
+    const finding = verdict === undefined
+        ? `missing UAT PASS verdict for ${sliceId}`
+        : `UAT verdict for ${sliceId} is "${verdict}"`;
+    const sliceSpecificRerunStep = `If ${sliceId} is not the most recently completed slice, type a chat request to re-run UAT for ${sliceId}; run-uat will record the verdict through \`gsd_uat_result_save\`.`;
+    const steps = verdict === undefined
+        ? [
+            `1. Run UAT for the most recently completed slice to record a verdict: \`/gsd dispatch uat\``,
+            `2. ${sliceSpecificRerunStep}`,
+            `3. Review the UAT criteria and progress: \`/gsd status\``,
+            `4. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ]
+        : [
+            `1. Review the failing UAT findings: \`/gsd status\` (the ${sliceId} ASSESSMENT records what failed)`,
+            `2. Fix the issue, then re-run UAT for the most recently completed slice to record a fresh verdict: \`/gsd dispatch uat\``,
+            `3. ${sliceSpecificRerunStep}`,
+            `4. If the fix needs new implementation work, add remediation slices: \`/gsd dispatch reassess\``,
+            `5. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ];
+    return [
+        `Cannot complete milestone ${milestoneId}: ${finding}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+        `Fix options:`,
+        ...steps,
+    ].join("\n");
+}
+// ─── Worktree isolation degradation ─────────────────────────────────────
+// The first sentence of each notice is load-bearing for log matching and
+// tests — keep it intact and append guidance after it.
+function restoreIsolationHint(milestoneId) {
+    return `To restore isolation: close any processes using the old worktree, merge salvageable work with \`/gsd worktree merge ${milestoneId}\` or remove the stale worktree with \`/gsd worktree remove ${milestoneId}\`, then run \`/gsd doctor fix\`.`;
+}
+export function worktreeCreationFailedGuidance(milestoneId, error) {
+    return [
+        `Auto-worktree creation for ${milestoneId} failed: ${error}. Continuing in project root.`,
+        `Worktree isolation is degraded for this session.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+export function isolationDegradedFallbackGuidance(milestoneId) {
+    return [
+        `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+        `Work continues safely on the milestone branch in the project root.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+/** Hard entry blockers from auto-start: bootstrap stopped, user must act. */
+export function milestoneEntryBlockedGuidance(milestoneId, reason) {
+    const finding = reason === "creation-failed"
+        ? `worktree/branch creation failed. Isolation is degraded.`
+        : `isolation is degraded from a prior worktree failure.`;
+    return [
+        `Cannot enter milestone ${milestoneId}: ${finding}`,
+        restoreIsolationHint(milestoneId),
+        `Then run \`/gsd auto\` to retry.`,
+    ].join("\n");
+}
+// ─── Crash recovery resume hints ────────────────────────────────────────
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType, unitId) {
+    if (unitType === "starting" && unitId === "bootstrap") {
+        return `No work was lost. Run /gsd auto to restart.`;
+    }
+    if (unitType.includes("research") || unitType.includes("plan")) {
+        return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+    }
+    if (unitType.includes("execute")) {
+        return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+    }
+    if (unitType.includes("complete")) {
+        return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+    }
+    return undefined;
+}
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+const DOCTOR_FIX_HINTS = {
+    db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+    conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+    worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+    worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+    provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+    provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+export function doctorFixHint(code) {
+    return DOCTOR_FIX_HINTS[code];
+}

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

@@ -44,13 +44,14 @@ import { buildCloseoutMenuActions, buildIdleMenuSummary, getPrimaryCloseoutRecom
 import { buildRequirementsBacklogDiscussContext, countUnmappedActiveRequirements, showRequirementsBacklogReview, } from "./requirements-backlog.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
-import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
+import { supportsStructuredQuestions } from "./workflow-mcp.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";
@@ -382,7 +383,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 +398,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,
@@ -1529,6 +1532,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/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-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) {