gsd-pi 2.62.1 → 2.63.0-dev.351157b

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -994,10 +994,15 @@ export async function buildResearchSlicePrompt(
   const milestoneResearchPath = resolveMilestoneFile(base, mid, "RESEARCH");
   const milestoneResearchRel = relMilestoneFile(base, mid, "RESEARCH");
 
+  const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
+  const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
+
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
+  const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
+  if (sliceCtxInline) inlined.push(sliceCtxInline);
   const researchInline = await inlineFileOptional(milestoneResearchPath, milestoneResearchRel, "Milestone Research");
   if (researchInline) inlined.push(researchInline);
   const decisionsInline = await inlineDecisionsFromDb(base, mid);
@@ -1045,6 +1050,8 @@ export async function buildPlanSlicePrompt(
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
   const researchRel = relSliceFile(base, mid, sid, "RESEARCH");
+  const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
+  const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
 
   const inlined: string[] = [];
 
@@ -1053,6 +1060,8 @@ export async function buildPlanSlicePrompt(
   if (researchSliceAnchor) inlined.push(formatAnchorForPrompt(researchSliceAnchor));
 
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
+  if (sliceCtxInline) inlined.push(sliceCtxInline);
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
   if (researchInline) inlined.push(researchInline);
   if (inlineLevel !== "minimal") {
@@ -1253,9 +1262,13 @@ export async function buildCompleteSlicePrompt(
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN");
   const slicePlanRel = relSliceFile(base, mid, sid, "PLAN");
+  const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
+  const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
 
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
+  if (sliceCtxInline) inlined.push(sliceCtxInline);
   inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Slice Plan"));
   if (inlineLevel !== "minimal") {
     const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel);
@@ -1510,9 +1523,13 @@ export async function buildReplanSlicePrompt(
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN");
   const slicePlanRel = relSliceFile(base, mid, sid, "PLAN");
+  const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT");
+  const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT");
 
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
+  const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
+  if (sliceCtxInline) inlined.push(sliceCtxInline);
   inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Current Slice Plan"));
 
   // Find the blocker task summary — the completed task with blocker_discovered: true
@@ -1627,9 +1644,13 @@ export async function buildReassessRoadmapPrompt(
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
   const summaryPath = resolveSliceFile(base, mid, completedSliceId, "SUMMARY");
   const summaryRel = relSliceFile(base, mid, completedSliceId, "SUMMARY");
+  const sliceContextPath = resolveSliceFile(base, mid, completedSliceId, "CONTEXT");
+  const sliceContextRel = relSliceFile(base, mid, completedSliceId, "CONTEXT");
 
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Current Roadmap"));
+  const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)");
+  if (sliceCtxInline) inlined.push(sliceCtxInline);
   inlined.push(await inlineFile(summaryPath, summaryRel, `${completedSliceId} Summary`));
   if (inlineLevel !== "minimal") {
     const projectInline = await inlineProjectFromDb(base);

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -12,7 +12,7 @@ import { parseUnitId } from "./unit-id.js";
 import { atomicWriteSync } from "./atomic-write.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";
@@ -424,15 +424,16 @@ export function writeBlockerPlaceholder(
   ].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) {
-      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)}`);
-      }
+    if (unitType === "execute-task" && mid && sid && tid) {
+      try { updateTaskStatus(mid, sid, tid, "complete", new Date().toISOString()); } 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/src/resources/extensions/gsd/auto-start.ts

@@ -58,7 +58,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,
@@ -99,33 +99,24 @@ export interface BootstrapDeps {
  * 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: string): Promise<void> {
+/** 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: string): Promise<void> {
   const gsdDbPath = resolveProjectRootDbPath(basePath);
-  if (!existsSync(gsdDbPath)) return;
-  if (isDbAvailable()) return;
+  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: AutoSession,
   ctx: ExtensionCommandContext,

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -83,3 +83,22 @@ export function hasInteractiveToolInFlight(): boolean {
 export function clearInFlightTools(): void {
   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: string): boolean {
+  if (!errorMsg) return false;
+  return TOOL_INVOCATION_ERROR_RE.test(errorMsg);
+}

package/src/resources/extensions/gsd/auto-verification.ts

@@ -196,19 +196,30 @@ export async function runPostUnitVerification(
         failureContext: formatFailureContext(result),
         attempt: nextAttempt,
       };
+      const failedCmds = result.checks
+        .filter((c) => c.exitCode !== 0)
+        .map((c) => c.command);
+      const cmdSummary = failedCmds.length <= 3
+        ? failedCmds.join(", ")
+        : `${failedCmds.slice(0, 3).join(", ")}... and ${failedCmds.length - 3} more`;
       ctx.ui.notify(
-        `Verification failed — auto-fix attempt ${nextAttempt}/${maxRetries}`,
+        `Verification failed (${cmdSummary}) — auto-fix attempt ${nextAttempt}/${maxRetries}`,
         "warning",
       );
       // Return "retry" — the autoLoop while loop will re-iterate with the retry context
       return "retry";
     } else {
       // Gate failed, retries exhausted
-      const exhaustedAttempt = attempt + 1;
       s.verificationRetryCount.delete(s.currentUnit.id);
       s.pendingVerificationRetry = null;
+      const exhaustedFails = result.checks
+        .filter((c) => c.exitCode !== 0)
+        .map((c) => c.command);
+      const exhaustedSummary = exhaustedFails.length <= 3
+        ? exhaustedFails.join(", ")
+        : `${exhaustedFails.slice(0, 3).join(", ")}... and ${exhaustedFails.length - 3} more`;
       ctx.ui.notify(
-        `Verification gate FAILED after ${exhaustedAttempt > maxRetries ? exhaustedAttempt - 1 : exhaustedAttempt} retries — pausing for human review`,
+        `Verification gate FAILED after ${attempt} ${attempt === 1 ? "retry" : "retries"} (${exhaustedSummary}) — pausing for human review`,
         "error",
       );
       await pauseAuto(ctx, pi);

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -36,6 +36,7 @@ import {
   removeWorktree,
   resolveGitDir,
   worktreePath,
+  isInsideWorktreesDir,
 } from "./worktree-manager.js";
 import {
   detectWorktreeName,
@@ -1204,12 +1205,19 @@ export function teardownAutoWorktree(
         `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 });
-    } 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)}`);
+    // 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)}`);
+      }
+    } else {
+      console.error(
+        `[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`,
+      );
     }
   }
 }

package/src/resources/extensions/gsd/auto.ts

@@ -75,6 +75,7 @@ import {
   getOldestInFlightToolStart,
   hasInteractiveToolInFlight,
   clearInFlightTools,
+  isToolInvocationError,
 } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
@@ -185,8 +186,11 @@ import {
   postUnitPreVerification,
   postUnitPostVerification,
 } from "./auto-post-unit.js";
-import { bootstrapAutoSession, type BootstrapDeps } from "./auto-start.js";
+import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js";
 import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js";
+// Slice-level parallelism (#2340)
+import { getEligibleSlices } from "./slice-parallel-eligibility.js";
+import { startSliceParallel } from "./slice-parallel-orchestrator.js";
 import {
   WorktreeResolver,
   type WorktreeResolverDeps,
@@ -385,6 +389,19 @@ export function markToolEnd(toolCallId: string): void {
   _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: string, errorMsg: string): void {
+  if (!s.active) return;
+  if (isToolInvocationError(errorMsg)) {
+    s.lastToolInvocationError = `${toolName}: ${errorMsg}`;
+  }
+}
+
 export function getOldestInFlightToolAgeMs(): number {
   return _getOldestInFlightToolAgeMs();
 }
@@ -1205,6 +1222,9 @@ export async function startAuto(
       "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));
@@ -1351,6 +1371,7 @@ const widgetStateAccessors: WidgetStateAccessors = {
   getBasePath: () => s.basePath,
   isVerbose: () => s.verbose,
   isSessionSwitching: isSessionSwitchInFlight,
+  getCurrentDispatchedModelId: () => s.currentDispatchedModelId,
 };
 
 // ─── Preconditions ────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -501,28 +501,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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" }),
@@ -535,6 +517,26 @@ export function registerDbTools(pi: ExtensionAPI): void {
         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,
   };
@@ -594,13 +596,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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" }),
@@ -612,6 +611,11 @@ export function registerDbTools(pi: ExtensionAPI): void {
         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,
   };
@@ -743,18 +747,20 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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(
+      // ── 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.Object({
           command: Type.String({ description: "Verification command that was run" }),
           exitCode: Type.Number({ description: "Exit code of the command" }),
@@ -762,7 +768,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
           durationMs: Type.Number({ description: "Duration of the command in milliseconds" }),
         }),
         { description: "Array of verification evidence entries" },
-      ),
+      )),
     }),
     execute: taskCompleteExecute,
   };
@@ -823,59 +829,61 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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(
+      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.Object({
           id: Type.String({ description: "Requirement ID" }),
           how: Type.String({ description: "How it was advanced" }),
         }),
         { description: "Requirements advanced by this slice" },
-      ),
-      requirementsValidated: Type.Array(
+      )),
+      requirementsValidated: Type.Optional(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(
+      )),
+      requirementsInvalidated: Type.Optional(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(
+      )),
+      filesModified: Type.Optional(Type.Array(
         Type.Object({
           path: Type.String({ description: "File path" }),
           description: Type.String({ description: "What changed" }),
         }),
         { description: "Files modified with descriptions" },
-      ),
-      requires: Type.Array(
+      )),
+      requires: Type.Optional(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)" }),
+      )),
     }),
     execute: sliceCompleteExecute,
   };
@@ -972,8 +980,12 @@ export function registerDbTools(pi: ExtensionAPI): void {
       };
     }
     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" as const, text: `Error completing milestone: ${result.error}` }],
@@ -1012,19 +1024,21 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "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/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -32,6 +32,20 @@ export function resolveProjectRootDbPath(basePath: string): string {
     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}`;
@@ -57,6 +71,7 @@ export function resolveProjectRootDbPath(basePath: string): string {
     }
   }
 
+
   return join(basePath, ".gsd", "gsd.db");
 }