gsd-pi 2.63.0 → 2.64.0

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

@@ -9,7 +9,7 @@
 import { parseUnitId } from "./unit-id.js";
 import { clearParseCache } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getTask, getSlice, getSliceTasks, updateTaskStatus } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getSliceTasks, updateTaskStatus, updateSliceStatus } from "./gsd-db.js";
 import { isValidationTerminal } from "./state.js";
 import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -377,17 +377,25 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
         `Review and replace this file before relying on downstream artifacts.`,
     ].join("\n");
     writeFileSync(absPath, content, "utf-8");
-    // Mark the task as complete in the DB so verifyExpectedArtifact passes.
+    // Mark the task/slice as complete in the DB so verifyExpectedArtifact passes.
     // Without this, the DB status stays "pending" and the dispatch loop
-    // re-derives the same task indefinitely (#2531).
-    if (unitType === "execute-task" && isDbAvailable()) {
+    // re-derives the same unit indefinitely (#2531, #2653).
+    if (isDbAvailable()) {
         const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
-        if (mid && sid && tid) {
+        if (unitType === "execute-task" && mid && sid && tid) {
             try {
                 updateTaskStatus(mid, sid, tid, "complete", new Date().toISOString());
             }
-            catch (err) { /* non-fatal */
-                logError("recovery", `DB status update failed: ${err instanceof Error ? err.message : String(err)}`);
+            catch (e) {
+                logWarning("recovery", `updateTaskStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        if (unitType === "complete-slice" && mid && sid) {
+            try {
+                updateSliceStatus(mid, sid, "complete", new Date().toISOString());
+            }
+            catch (e) {
+                logWarning("recovery", `updateSliceStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
     }

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

@@ -30,7 +30,7 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, openDatabase } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -48,34 +48,23 @@ import { resolveDefaultSessionModel } from "./preferences-models.js";
  * Returns false if the bootstrap aborted (e.g., guided flow returned,
  * concurrent session detected). Returns true when ready to dispatch.
  */
-/**
- * Open the project-root DB before the first deriveState call (#2841).
- * When auto-mode starts cold (no prior DB handle), state derivation that
- * touches DB-backed helpers (queue-order, task status) silently falls back
- * to markdown-only data, producing stale or incomplete state.  Opening the
- * DB first ensures deriveState sees the full picture on its very first run.
- */
-async function openProjectDbIfPresent(basePath) {
+/** Guard: tracks consecutive bootstrap attempts that found phase === "complete".
+ *  Prevents the recursive dialog loop described in #1348 where
+ *  bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto
+ *  cycles indefinitely when the discuss workflow doesn't produce a milestone. */
+let _consecutiveCompleteBootstraps = 0;
+const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2;
+export async function openProjectDbIfPresent(basePath) {
     const gsdDbPath = resolveProjectRootDbPath(basePath);
-    if (!existsSync(gsdDbPath))
-        return;
-    if (isDbAvailable())
+    if (!existsSync(gsdDbPath) || isDbAvailable())
         return;
     try {
-        const { openDatabase } = await import("./gsd-db.js");
         openDatabase(gsdDbPath);
     }
     catch (err) {
-        /* non-fatal — DB lifecycle block below will retry */
-        logWarning("engine", `DB open failed: ${err instanceof Error ? err.message : String(err)}`);
+        logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/** Guard: tracks consecutive bootstrap attempts that found phase === "complete".
- *  Prevents the recursive dialog loop described in #1348 where
- *  bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto
- *  cycles indefinitely when the discuss workflow doesn't produce a milestone. */
-let _consecutiveCompleteBootstraps = 0;
-const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2;
 export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, deps) {
     const { shouldUseWorktreeIsolation, registerSigtermHandler, lockBase, buildResolver, } = deps;
     const lockResult = acquireSessionLock(base);

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

@@ -77,8 +77,9 @@ export function startUnitSupervision(sctx) {
         }
     }
     const estimateMinutes = taskEstimate ? parseEstimateMinutes(taskEstimate) : null;
+    const MAX_TIMEOUT_SCALE = 6; // Cap at 6x (60min task). Prevents 2h+ tasks from creating 120min+ timeout windows.
     const timeoutScale = estimateMinutes && estimateMinutes > 0
-        ? Math.max(1, estimateMinutes / 10) // 10min task = 1x, 30min = 3x, 2h = 12x
+        ? Math.min(MAX_TIMEOUT_SCALE, Math.max(1, estimateMinutes / 10))
         : 1;
     const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
     const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000; // idle not scaled — idle is idle

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -75,3 +75,20 @@ export function hasInteractiveToolInFlight() {
 export function clearInFlightTools() {
     inFlightTools.clear();
 }
+// ─── Tool invocation error classification (#2883) ────────────────────────
+/**
+ * Patterns that indicate a tool invocation failed due to malformed or truncated
+ * JSON arguments — as opposed to a normal business-logic error from the tool
+ * handler. When these errors occur, retrying the same unit will produce the same
+ * failure, so the retry loop must be broken.
+ */
+const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}' in JSON|Unexpected end of JSON|Unexpected token.*in JSON/i;
+/**
+ * Returns true if the error message indicates a tool invocation failure due to
+ * malformed/truncated arguments (as opposed to a normal tool execution error).
+ */
+export function isToolInvocationError(errorMsg) {
+    if (!errorMsg)
+        return false;
+    return TOOL_INVOCATION_ERROR_RE.test(errorMsg);
+}

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

@@ -14,7 +14,7 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 import { gsdRoot } from "./paths.js";
-import { createWorktree, removeWorktree, resolveGitDir, worktreePath, } from "./worktree-manager.js";
+import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
@@ -1025,13 +1025,19 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
         logWarning("reconcile", `Worktree directory still exists after teardown: ${wtDir}. ` +
             `This is likely an orphaned directory consuming disk space. ` +
             `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId });
-        // Attempt a direct filesystem removal as a fallback
-        try {
-            rmSync(wtDir, { recursive: true, force: true });
+        // Attempt a direct filesystem removal as a fallback — but ONLY if the
+        // path is safely inside .gsd/worktrees/ to prevent #2365 data loss.
+        if (isInsideWorktreesDir(originalBasePath, wtDir)) {
+            try {
+                rmSync(wtDir, { recursive: true, force: true });
+            }
+            catch (err) {
+                // Non-fatal — the warning above tells the user how to clean up
+                logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
-        catch (err) {
-            // Non-fatal — the warning above tells the user how to clean up
-            logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            console.error(`[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`);
         }
     }
 }

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

@@ -23,7 +23,7 @@ import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSes
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
 import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, } from "./auto-budget.js";
-import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, } from "./auto-tool-tracking.js";
+import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, isToolInvocationError, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { selectAndApplyModel, resolveModelId } from "./auto-model-selection.js";
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
@@ -57,7 +57,7 @@ import { clearCmuxSidebar, logCmuxEvent, syncCmuxSidebar } from "../cmux/index.j
 import { startUnitSupervision } from "./auto-timers.js";
 import { runPostUnitVerification } from "./auto-verification.js";
 import { postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js";
-import { bootstrapAutoSession } from "./auto-start.js";
+import { bootstrapAutoSession, openProjectDbIfPresent } from "./auto-start.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight } from "./auto-loop.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
@@ -192,6 +192,19 @@ export function markToolStart(toolCallId, toolName) {
 export function markToolEnd(toolCallId) {
     _markToolEnd(toolCallId);
 }
+/**
+ * Record a tool invocation error on the current session (#2883).
+ * Called from tool_execution_end when a GSD tool fails with isError.
+ * Only stores the error if it matches the tool-invocation-error pattern
+ * (malformed/truncated JSON), not normal business-logic errors.
+ */
+export function recordToolInvocationError(toolName, errorMsg) {
+    if (!s.active)
+        return;
+    if (isToolInvocationError(errorMsg)) {
+        s.lastToolInvocationError = `${toolName}: ${errorMsg}`;
+    }
+}
 export function getOldestInFlightToolAgeMs() {
     return _getOldestInFlightToolAgeMs();
 }
@@ -909,6 +922,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         ctx.ui.setFooter(hideFooter);
         ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
         restoreHookState(s.basePath);
+        // Open the project DB before rebuild/derive so resume uses DB-backed
+        // state instead of falling back to stale markdown parsing (#2940).
+        await openProjectDbIfPresent(s.basePath);
         try {
             await rebuildState(s.basePath);
             syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
@@ -1005,6 +1021,7 @@ const widgetStateAccessors = {
     getBasePath: () => s.basePath,
     isVerbose: () => s.verbose,
     isSessionSwitching: isSessionSwitchInFlight,
+    getCurrentDispatchedModelId: () => s.currentDispatchedModelId,
 };
 // ─── Preconditions ────────────────────────────────────────────────────────────
 /**

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

@@ -486,28 +486,10 @@ export function registerDbTools(pi) {
             "Use the canonical name gsd_plan_milestone; gsd_milestone_plan is only an alias.",
         ],
         parameters: Type.Object({
+            // ── Core identification + content (required) ──────────────────────
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             title: Type.String({ description: "Milestone title" }),
-            status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })),
-            dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Milestone dependencies" })),
             vision: Type.String({ description: "Milestone vision" }),
-            successCriteria: Type.Array(Type.String(), { description: "Top-level success criteria bullets" }),
-            keyRisks: Type.Array(Type.Object({
-                risk: Type.String({ description: "Risk statement" }),
-                whyItMatters: Type.String({ description: "Why the risk matters" }),
-            }), { description: "Structured risk entries" }),
-            proofStrategy: Type.Array(Type.Object({
-                riskOrUnknown: Type.String({ description: "Risk or unknown to retire" }),
-                retireIn: Type.String({ description: "Where it will be retired" }),
-                whatWillBeProven: Type.String({ description: "What proof will be produced" }),
-            }), { description: "Structured proof strategy entries" }),
-            verificationContract: Type.String({ description: "Verification contract text" }),
-            verificationIntegration: Type.String({ description: "Integration verification text" }),
-            verificationOperational: Type.String({ description: "Operational verification text" }),
-            verificationUat: Type.String({ description: "UAT verification text" }),
-            definitionOfDone: Type.Array(Type.String(), { description: "Definition of done bullets" }),
-            requirementCoverage: Type.String({ description: "Requirement coverage text" }),
-            boundaryMapMarkdown: Type.String({ description: "Boundary map markdown block" }),
             slices: Type.Array(Type.Object({
                 sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
                 title: Type.String({ description: "Slice title" }),
@@ -520,6 +502,26 @@ export function registerDbTools(pi) {
                 integrationClosure: Type.String({ description: "Slice integration closure" }),
                 observabilityImpact: Type.String({ description: "Slice observability impact" }),
             }), { description: "Planned slices for the milestone" }),
+            // ── Enrichment metadata (optional — defaults to empty) ────────────
+            status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })),
+            dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Milestone dependencies" })),
+            successCriteria: Type.Optional(Type.Array(Type.String(), { description: "Top-level success criteria bullets" })),
+            keyRisks: Type.Optional(Type.Array(Type.Object({
+                risk: Type.String({ description: "Risk statement" }),
+                whyItMatters: Type.String({ description: "Why the risk matters" }),
+            }), { description: "Structured risk entries" })),
+            proofStrategy: Type.Optional(Type.Array(Type.Object({
+                riskOrUnknown: Type.String({ description: "Risk or unknown to retire" }),
+                retireIn: Type.String({ description: "Where it will be retired" }),
+                whatWillBeProven: Type.String({ description: "What proof will be produced" }),
+            }), { description: "Structured proof strategy entries" })),
+            verificationContract: Type.Optional(Type.String({ description: "Verification contract text" })),
+            verificationIntegration: Type.Optional(Type.String({ description: "Integration verification text" })),
+            verificationOperational: Type.Optional(Type.String({ description: "Operational verification text" })),
+            verificationUat: Type.Optional(Type.String({ description: "UAT verification text" })),
+            definitionOfDone: Type.Optional(Type.Array(Type.String(), { description: "Definition of done bullets" })),
+            requirementCoverage: Type.Optional(Type.String({ description: "Requirement coverage text" })),
+            boundaryMapMarkdown: Type.Optional(Type.String({ description: "Boundary map markdown block" })),
         }),
         execute: planMilestoneExecute,
     };
@@ -575,13 +577,10 @@ export function registerDbTools(pi) {
             "Use the canonical name gsd_plan_slice; gsd_slice_plan is only an alias.",
         ],
         parameters: Type.Object({
+            // ── Core identification + content (required) ──────────────────────
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
             goal: Type.String({ description: "Slice goal" }),
-            successCriteria: Type.String({ description: "Slice success criteria block" }),
-            proofLevel: Type.String({ description: "Slice proof level" }),
-            integrationClosure: Type.String({ description: "Slice integration closure" }),
-            observabilityImpact: Type.String({ description: "Slice observability impact" }),
             tasks: Type.Array(Type.Object({
                 taskId: Type.String({ description: "Task ID (e.g. T01)" }),
                 title: Type.String({ description: "Task title" }),
@@ -593,6 +592,11 @@ export function registerDbTools(pi) {
                 expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
                 observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
             }), { description: "Planned tasks for the slice" }),
+            // ── Enrichment metadata (optional — defaults to empty) ────────────
+            successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })),
+            proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),
+            integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })),
+            observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })),
         }),
         execute: planSliceExecute,
     };
@@ -674,8 +678,11 @@ export function registerDbTools(pi) {
             };
         }
         try {
+            // Coerce string items to objects for verificationEvidence (#3541).
+            const coerced = { ...params };
+            coerced.verificationEvidence = (params.verificationEvidence ?? []).map((v) => typeof v === "string" ? { command: v, exitCode: -1, verdict: "unknown (coerced from string)", durationMs: 0 } : v);
             const { handleCompleteTask } = await import("../tools/complete-task.js");
-            const result = await handleCompleteTask(params, process.cwd());
+            const result = await handleCompleteTask(coerced, process.cwd());
             if ("error" in result) {
                 return {
                     content: [{ type: "text", text: `Error completing task: ${result.error}` }],
@@ -716,23 +723,28 @@ export function registerDbTools(pi) {
             "Idempotent — calling with the same params twice will upsert (INSERT OR REPLACE) without error.",
         ],
         parameters: Type.Object({
+            // ── Core identification + content (required) ──────────────────────
             taskId: Type.String({ description: "Task ID (e.g. T01)" }),
             sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             oneLiner: Type.String({ description: "One-line summary of what was accomplished" }),
             narrative: Type.String({ description: "Detailed narrative of what happened during the task" }),
             verification: Type.String({ description: "What was verified and how — commands run, tests passed, behavior confirmed" }),
-            deviations: Type.String({ description: "Deviations from the task plan, or 'None.'" }),
-            knownIssues: Type.String({ description: "Known issues discovered but not fixed, or 'None.'" }),
-            keyFiles: Type.Array(Type.String(), { description: "List of key files created or modified" }),
-            keyDecisions: Type.Array(Type.String(), { description: "List of key decisions made during this task" }),
-            blockerDiscovered: Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" }),
-            verificationEvidence: Type.Array(Type.Object({
-                command: Type.String({ description: "Verification command that was run" }),
-                exitCode: Type.Number({ description: "Exit code of the command" }),
-                verdict: Type.String({ description: "Pass/fail verdict (e.g. '✅ pass', '❌ fail')" }),
-                durationMs: Type.Number({ description: "Duration of the command in milliseconds" }),
-            }), { description: "Array of verification evidence entries" }),
+            // ── Enrichment metadata (optional — defaults to empty) ────────────
+            deviations: Type.Optional(Type.String({ description: "Deviations from the task plan, or 'None.'" })),
+            knownIssues: Type.Optional(Type.String({ description: "Known issues discovered but not fixed, or 'None.'" })),
+            keyFiles: Type.Optional(Type.Array(Type.String(), { description: "List of key files created or modified" })),
+            keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "List of key decisions made during this task" })),
+            blockerDiscovered: Type.Optional(Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" })),
+            verificationEvidence: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    command: Type.String({ description: "Verification command that was run" }),
+                    exitCode: Type.Number({ description: "Exit code of the command" }),
+                    verdict: Type.String({ description: "Pass/fail verdict (e.g. '✅ pass', '❌ fail')" }),
+                    durationMs: Type.Number({ description: "Duration of the command in milliseconds" }),
+                }),
+                Type.String({ description: "Fallback: verification summary string" }),
+            ]), { description: "Array of verification evidence entries" })),
         }),
         execute: taskCompleteExecute,
     };
@@ -748,8 +760,46 @@ export function registerDbTools(pi) {
             };
         }
         try {
+            // Coerce string items to objects for fields where LLMs sometimes pass
+            // plain strings instead of the expected { key, value } shape (#3541).
+            // Parses "key — value" or "key - value" format when possible.
+            const splitPair = (s) => {
+                const m = s.match(/^(.+?)\s*(?:—|-)\s+(.+)$/);
+                return m ? [m[1].trim(), m[2].trim()] : [s.trim(), ""];
+            };
+            const coerced = { ...params };
+            coerced.filesModified = (params.filesModified ?? []).map((f) => {
+                if (typeof f !== "string")
+                    return f;
+                const [path, description] = splitPair(f);
+                return { path, description };
+            });
+            coerced.requires = (params.requires ?? []).map((r) => {
+                if (typeof r !== "string")
+                    return r;
+                const [slice, provides] = splitPair(r);
+                return { slice, provides };
+            });
+            coerced.requirementsAdvanced = (params.requirementsAdvanced ?? []).map((r) => {
+                if (typeof r !== "string")
+                    return r;
+                const [id, how] = splitPair(r);
+                return { id, how };
+            });
+            coerced.requirementsValidated = (params.requirementsValidated ?? []).map((r) => {
+                if (typeof r !== "string")
+                    return r;
+                const [id, proof] = splitPair(r);
+                return { id, proof };
+            });
+            coerced.requirementsInvalidated = (params.requirementsInvalidated ?? []).map((r) => {
+                if (typeof r !== "string")
+                    return r;
+                const [id, what] = splitPair(r);
+                return { id, what };
+            });
             const { handleCompleteSlice } = await import("../tools/complete-slice.js");
-            const result = await handleCompleteSlice(params, process.cwd());
+            const result = await handleCompleteSlice(coerced, process.cwd());
             if ("error" in result) {
                 return {
                     content: [{ type: "text", text: `Error completing slice: ${result.error}` }],
@@ -789,44 +839,61 @@ export function registerDbTools(pi) {
             "Idempotent — calling with the same params twice will not crash.",
         ],
         parameters: Type.Object({
+            // ── Core identification + content (required) ──────────────────────
             sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             sliceTitle: Type.String({ description: "Title of the slice" }),
             oneLiner: Type.String({ description: "One-line summary of what the slice accomplished" }),
             narrative: Type.String({ description: "Detailed narrative of what happened across all tasks" }),
             verification: Type.String({ description: "What was verified across all tasks" }),
-            deviations: Type.String({ description: "Deviations from the slice plan, or 'None.'" }),
-            knownLimitations: Type.String({ description: "Known limitations or gaps, or 'None.'" }),
-            followUps: Type.String({ description: "Follow-up work discovered during execution, or 'None.'" }),
-            keyFiles: Type.Array(Type.String(), { description: "Key files created or modified" }),
-            keyDecisions: Type.Array(Type.String(), { description: "Key decisions made during this slice" }),
-            patternsEstablished: Type.Array(Type.String(), { description: "Patterns established by this slice" }),
-            observabilitySurfaces: Type.Array(Type.String(), { description: "Observability surfaces added" }),
-            provides: Type.Array(Type.String(), { description: "What this slice provides to downstream slices" }),
-            requirementsSurfaced: Type.Array(Type.String(), { description: "New requirements surfaced" }),
-            drillDownPaths: Type.Array(Type.String(), { description: "Paths to task summaries for drill-down" }),
-            affects: Type.Array(Type.String(), { description: "Downstream slices affected" }),
-            requirementsAdvanced: Type.Array(Type.Object({
-                id: Type.String({ description: "Requirement ID" }),
-                how: Type.String({ description: "How it was advanced" }),
-            }), { description: "Requirements advanced by this slice" }),
-            requirementsValidated: Type.Array(Type.Object({
-                id: Type.String({ description: "Requirement ID" }),
-                proof: Type.String({ description: "What proof validates it" }),
-            }), { description: "Requirements validated by this slice" }),
-            requirementsInvalidated: Type.Array(Type.Object({
-                id: Type.String({ description: "Requirement ID" }),
-                what: Type.String({ description: "What changed" }),
-            }), { description: "Requirements invalidated or re-scoped" }),
-            filesModified: Type.Array(Type.Object({
-                path: Type.String({ description: "File path" }),
-                description: Type.String({ description: "What changed" }),
-            }), { description: "Files modified with descriptions" }),
-            requires: Type.Array(Type.Object({
-                slice: Type.String({ description: "Dependency slice ID" }),
-                provides: Type.String({ description: "What was consumed from it" }),
-            }), { description: "Upstream slice dependencies consumed" }),
             uatContent: Type.String({ description: "UAT test content (markdown body)" }),
+            // ── Enrichment metadata (optional — defaults to empty) ────────────
+            deviations: Type.Optional(Type.String({ description: "Deviations from the slice plan, or 'None.'" })),
+            knownLimitations: Type.Optional(Type.String({ description: "Known limitations or gaps, or 'None.'" })),
+            followUps: Type.Optional(Type.String({ description: "Follow-up work discovered during execution, or 'None.'" })),
+            keyFiles: Type.Optional(Type.Array(Type.String(), { description: "Key files created or modified" })),
+            keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "Key decisions made during this slice" })),
+            patternsEstablished: Type.Optional(Type.Array(Type.String(), { description: "Patterns established by this slice" })),
+            observabilitySurfaces: Type.Optional(Type.Array(Type.String(), { description: "Observability surfaces added" })),
+            provides: Type.Optional(Type.Array(Type.String(), { description: "What this slice provides to downstream slices" })),
+            requirementsSurfaced: Type.Optional(Type.Array(Type.String(), { description: "New requirements surfaced" })),
+            drillDownPaths: Type.Optional(Type.Array(Type.String(), { description: "Paths to task summaries for drill-down" })),
+            affects: Type.Optional(Type.Array(Type.String(), { description: "Downstream slices affected" })),
+            requirementsAdvanced: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    id: Type.String({ description: "Requirement ID" }),
+                    how: Type.String({ description: "How it was advanced" }),
+                }),
+                Type.String({ description: "Fallback: 'ID — how' string" }),
+            ]), { description: "Requirements advanced by this slice" })),
+            requirementsValidated: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    id: Type.String({ description: "Requirement ID" }),
+                    proof: Type.String({ description: "What proof validates it" }),
+                }),
+                Type.String({ description: "Fallback: 'ID — proof' string" }),
+            ]), { description: "Requirements validated by this slice" })),
+            requirementsInvalidated: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    id: Type.String({ description: "Requirement ID" }),
+                    what: Type.String({ description: "What changed" }),
+                }),
+                Type.String({ description: "Fallback: 'ID — what' string" }),
+            ]), { description: "Requirements invalidated or re-scoped" })),
+            filesModified: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    path: Type.String({ description: "File path" }),
+                    description: Type.String({ description: "What changed" }),
+                }),
+                Type.String({ description: "Fallback: file path string" }),
+            ]), { description: "Files modified with descriptions" })),
+            requires: Type.Optional(Type.Array(Type.Union([
+                Type.Object({
+                    slice: Type.String({ description: "Dependency slice ID" }),
+                    provides: Type.String({ description: "What was consumed from it" }),
+                }),
+                Type.String({ description: "Fallback: slice ID string" }),
+            ]), { description: "Upstream slice dependencies consumed" })),
         }),
         execute: sliceCompleteExecute,
     };
@@ -912,8 +979,11 @@ export function registerDbTools(pi) {
             };
         }
         try {
+            // ── Input sanitization: normalize markdown parameters (#3013) ──────
+            const { sanitizeCompleteMilestoneParams } = await import("./sanitize-complete-milestone.js");
+            const sanitized = sanitizeCompleteMilestoneParams(params);
             const { handleCompleteMilestone } = await import("../tools/complete-milestone.js");
-            const result = await handleCompleteMilestone(params, process.cwd());
+            const result = await handleCompleteMilestone(sanitized, process.cwd());
             if ("error" in result) {
                 return {
                     content: [{ type: "text", text: `Error completing milestone: ${result.error}` }],
@@ -951,19 +1021,21 @@ export function registerDbTools(pi) {
             "On success, returns summaryPath where the MILESTONE-SUMMARY.md was written.",
         ],
         parameters: Type.Object({
+            // ── Core identification + content (required) ──────────────────────
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             title: Type.String({ description: "Milestone title" }),
             oneLiner: Type.String({ description: "One-sentence summary of what the milestone achieved" }),
             narrative: Type.String({ description: "Detailed narrative of what happened during the milestone" }),
-            successCriteriaResults: Type.String({ description: "Markdown detailing how each success criterion was met or not met" }),
-            definitionOfDoneResults: Type.String({ description: "Markdown detailing how each definition-of-done item was met" }),
-            requirementOutcomes: Type.String({ description: "Markdown detailing requirement status transitions with evidence" }),
-            keyDecisions: Type.Array(Type.String(), { description: "Key architectural/pattern decisions made during the milestone" }),
-            keyFiles: Type.Array(Type.String(), { description: "Key files created or modified during the milestone" }),
-            lessonsLearned: Type.Array(Type.String(), { description: "Lessons learned during the milestone" }),
+            verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }),
+            // ── Enrichment metadata (optional — defaults to empty) ────────────
+            successCriteriaResults: Type.Optional(Type.String({ description: "Markdown detailing how each success criterion was met or not met" })),
+            definitionOfDoneResults: Type.Optional(Type.String({ description: "Markdown detailing how each definition-of-done item was met" })),
+            requirementOutcomes: Type.Optional(Type.String({ description: "Markdown detailing requirement status transitions with evidence" })),
+            keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "Key architectural/pattern decisions made during the milestone" })),
+            keyFiles: Type.Optional(Type.Array(Type.String(), { description: "Key files created or modified during the milestone" })),
+            lessonsLearned: Type.Optional(Type.Array(Type.String(), { description: "Lessons learned during the milestone" })),
             followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
             deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
-            verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }),
         }),
         execute: milestoneCompleteExecute,
     };

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

@@ -26,6 +26,19 @@ export function resolveProjectRootDbPath(basePath) {
         const projectRoot = basePath.slice(0, fwdIdx);
         return join(projectRoot, ".gsd", "gsd.db");
     }
+    // External-state layout: ~/.gsd/projects/<hash>/worktrees/<MID>/...
+    // Resolve to ~/.gsd/projects/<hash>/gsd.db (the canonical project DB) (#2952).
+    // Must be checked before the generic symlink-resolved handler: both match
+    // /.gsd/projects/<hash>/worktrees/ but require different resolution targets.
+    const extRe = /[/\\]\.gsd[/\\]projects[/\\][a-f0-9]+[/\\]worktrees(?:[/\\]|$)/;
+    const extMatch = extRe.exec(basePath);
+    if (extMatch) {
+        const matchStr = extMatch[0];
+        // Find the "/worktrees" portion within the match and slice up to it
+        const wtIdx = matchStr.search(/[/\\]worktrees(?:[/\\]|$)/);
+        const projectStateRoot = basePath.slice(0, extMatch.index + wtIdx);
+        return join(projectStateRoot, "gsd.db");
+    }
     // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/M001/...
     // The project root is everything before /.gsd/projects/ (#2517)
     const symlinkMarker = `${sep}.gsd${sep}projects${sep}`;