gsd-pi 2.43.0 → 2.44.0-dev.62b5d6c

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

@@ -1,21 +1,49 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, sep } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 
+/**
+ * Resolve the correct DB path for the current working directory.
+ * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
+ * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise
+ * returns `<basePath>/.gsd/gsd.db`.
+ */
+export function resolveProjectRootDbPath(basePath: string): string {
+  // Detect worktree: look for `.gsd/worktrees/` in the path segments.
+  // A worktree path looks like: /project/root/.gsd/worktrees/M001/...
+  // We need to resolve back to /project/root/.gsd/gsd.db
+  const marker = `${sep}.gsd${sep}worktrees${sep}`;
+  const idx = basePath.indexOf(marker);
+  if (idx !== -1) {
+    const projectRoot = basePath.slice(0, idx);
+    return join(projectRoot, ".gsd", "gsd.db");
+  }
+
+  // Also handle forward-slash paths on all platforms
+  const fwdMarker = "/.gsd/worktrees/";
+  const fwdIdx = basePath.indexOf(fwdMarker);
+  if (fwdIdx !== -1) {
+    const projectRoot = basePath.slice(0, fwdIdx);
+    return join(projectRoot, ".gsd", "gsd.db");
+  }
+
+  return join(basePath, ".gsd", "gsd.db");
+}
+
 export async function ensureDbOpen(): Promise<boolean> {
   try {
     const db = await import("../gsd-db.js");
     if (db.isDbAvailable()) return true;
 
     const basePath = process.cwd();
+    const dbPath = resolveProjectRootDbPath(basePath);
     const gsdDir = join(basePath, ".gsd");
-    const dbPath = join(gsdDir, "gsd.db");
 
-    // Open existing DB file
+    // Open existing DB file (may be at project root for worktrees)
     if (existsSync(dbPath)) {
       return db.openDatabase(dbPath);
     }

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -30,6 +30,13 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetWriteGateState();
     resetToolCallLoopGuard();
     await syncServiceTierStatus(ctx);
+
+    // Apply show_token_cost preference (#1515)
+    try {
+      const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+      const prefs = loadEffectiveGSDPreferences();
+      process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
+    } catch { /* non-fatal */ }
     if (isFirstSession) {
       isFirstSession = false;
     } else {

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -15,7 +15,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -35,6 +35,8 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
   { cmd: "history", desc: "View execution history" },
   { cmd: "undo", desc: "Revert last completed unit" },
+  { cmd: "undo-task", desc: "Reset a specific task's completion state (DB + markdown)" },
+  { cmd: "reset-slice", desc: "Reset a slice and all its tasks (DB + markdown)" },
   { cmd: "rate", desc: "Rate last unit's model tier (over/ok/under) — improves adaptive routing" },
   { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
   { cmd: "export", desc: "Export milestone/slice results" },

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -6,7 +6,7 @@ import { handleConfig } from "../../commands-config.js";
 import { handleDoctor, handleCapture, handleKnowledge, handleRunHook, handleSkillHealth, handleSteer, handleTriage, handleUpdate } from "../../commands-handlers.js";
 import { handleInspect } from "../../commands-inspect.js";
 import { handleLogs } from "../../commands-logs.js";
-import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleCleanupProjects, handleCleanupWorktrees } from "../../commands-maintenance.js";
+import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleCleanupProjects, handleCleanupWorktrees, handleRecover } from "../../commands-maintenance.js";
 import { handleExport } from "../../export.js";
 import { handleHistory } from "../../history.js";
 import { handleUndo } from "../../undo.js";
@@ -53,6 +53,16 @@ export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandCon
     await handleHistory(trimmed.replace(/^history\s*/, "").trim(), ctx, projectRoot());
     return true;
   }
+  if (trimmed === "undo-task" || trimmed.startsWith("undo-task ")) {
+    const { handleUndoTask } = await import("../../undo.js");
+    await handleUndoTask(trimmed.replace(/^undo-task\s*/, "").trim(), ctx, pi, projectRoot());
+    return true;
+  }
+  if (trimmed === "reset-slice" || trimmed.startsWith("reset-slice ")) {
+    const { handleResetSlice } = await import("../../undo.js");
+    await handleResetSlice(trimmed.replace(/^reset-slice\s*/, "").trim(), ctx, pi, projectRoot());
+    return true;
+  }
   if (trimmed === "undo" || trimmed.startsWith("undo ")) {
     await handleUndo(trimmed.replace(/^undo\s*/, "").trim(), ctx, pi, projectRoot());
     return true;
@@ -65,6 +75,10 @@ export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandCon
     await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
     return true;
   }
+  if (trimmed === "recover") {
+    await handleRecover(ctx, projectRoot());
+    return true;
+  }
   if (trimmed === "export" || trimmed.startsWith("export ")) {
     await handleExport(trimmed.replace(/^export\s*/, "").trim(), ctx, projectRoot());
     return true;

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -82,7 +82,7 @@ export async function handleDoctor(args: string, ctx: ExtensionCommandContext, p
       scope: effectiveScope,
       includeWarnings: true,
     });
-    const actionable = unresolved.filter(issue => issue.severity === "error" || issue.code === "all_tasks_done_missing_slice_uat" || issue.code === "slice_checked_missing_uat");
+    const actionable = unresolved.filter(issue => issue.severity === "error");
     if (actionable.length === 0) {
       ctx.ui.notify("Doctor heal found nothing actionable to hand off to the LLM.", "info");
       return;

package/src/resources/extensions/gsd/commands-maintenance.ts

@@ -1,7 +1,7 @@
 /**
- * GSD Maintenance — cleanup, skip, and dry-run handlers.
+ * GSD Maintenance — cleanup, skip, dry-run, and recover handlers.
  *
- * Contains: handleCleanupBranches, handleCleanupSnapshots, handleCleanupWorktrees, handleSkip, handleDryRun
+ * Contains: handleCleanupBranches, handleCleanupSnapshots, handleCleanupWorktrees, handleSkip, handleDryRun, handleRecover
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
@@ -44,8 +44,10 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
   try {
     const { listWorktrees } = await import("./worktree-manager.js");
     const { resolveMilestoneFile } = await import("./paths.js");
-    const { loadFile, parseRoadmap } = await import("./files.js");
+    const { loadFile } = await import("./files.js");
+    const { parseRoadmap } = await import("./parsers-legacy.js");
     const { isMilestoneComplete } = await import("./state.js");
+    const { isDbAvailable, getMilestone } = await import("./gsd-db.js");
 
     const attachedBranches = new Set(
       listWorktrees(basePath).map((wt) => wt.branch),
@@ -54,6 +56,22 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa
     for (const branch of milestoneBranches) {
       if (attachedBranches.has(branch)) continue;
       const milestoneId = branch.replace(/^milestone\//, "");
+
+      // DB-first: check milestone status directly
+      if (isDbAvailable()) {
+        const dbRow = getMilestone(milestoneId);
+        if (dbRow) {
+          if (dbRow.status !== "complete" && dbRow.status !== "done") continue;
+          // Milestone is complete per DB — proceed to delete branch
+          try {
+            nativeBranchDelete(basePath, branch, true);
+            deletedStaleMilestones++;
+          } catch { /* non-fatal */ }
+          continue;
+        }
+      }
+
+      // Filesystem fallback
       const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
       if (!roadmapPath) continue;
       let roadmapContent: string | null = null;
@@ -450,3 +468,68 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
 
   ctx.ui.notify(lines.join("\n"), "info");
 }
+
+/**
+ * `gsd recover` — Reconstruct DB hierarchy state from rendered markdown on disk.
+ *
+ * Deletes milestones, slices, and tasks table rows (preserves decisions,
+ * requirements, artifacts, memories), re-runs `migrateHierarchyToDb()` to
+ * repopulate from markdown, then calls `deriveState()` to verify sanity.
+ *
+ * Prints counts of recovered items and the resulting project phase.
+ */
+export async function handleRecover(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
+  const { isDbAvailable: dbAvailable, _getAdapter, transaction: dbTransaction } = await import("./gsd-db.js");
+  const { migrateHierarchyToDb } = await import("./md-importer.js");
+  const { invalidateStateCache } = await import("./state.js");
+
+  if (!dbAvailable()) {
+    ctx.ui.notify("gsd recover: No database open. Run a GSD command first to initialize the DB.", "error");
+    return;
+  }
+
+  try {
+    // 1. Delete + re-populate inside a single transaction for atomicity
+    const db = _getAdapter()!;
+    const counts = dbTransaction(() => {
+      db.exec("DELETE FROM tasks");
+      db.exec("DELETE FROM slices");
+      db.exec("DELETE FROM milestones");
+      return migrateHierarchyToDb(basePath);
+    });
+
+    // 3. Invalidate state cache so deriveState() picks up fresh DB data
+    invalidateStateCache();
+
+    // 4. Derive state to verify sanity
+    const state = await deriveState(basePath);
+
+    // 5. Report
+    const lines = [
+      `gsd recover: reconstructed hierarchy from markdown`,
+      `  Milestones: ${counts.milestones}`,
+      `  Slices:     ${counts.slices}`,
+      `  Tasks:      ${counts.tasks}`,
+      ``,
+      `  Phase:      ${state.phase}`,
+    ];
+    if (state.activeMilestone) {
+      lines.push(`  Active:     ${state.activeMilestone.id}: ${state.activeMilestone.title}`);
+    }
+    if (state.activeSlice) {
+      lines.push(`  Slice:      ${state.activeSlice.id}: ${state.activeSlice.title}`);
+    }
+    if (state.activeTask) {
+      lines.push(`  Task:       ${state.activeTask.id}: ${state.activeTask.title}`);
+    }
+
+    process.stderr.write(
+      `gsd-recover: recovered ${counts.milestones}M/${counts.slices}S/${counts.tasks}T hierarchy\n`,
+    );
+    ctx.ui.notify(lines.join("\n"), "success");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`gsd-recover: failed: ${msg}\n`);
+    ctx.ui.notify(`gsd recover failed: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -9,7 +9,8 @@
 import type { Theme } from "@gsd/pi-coding-agent";
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { deriveState } from "./state.js";
-import { loadFile, parseRoadmap, parsePlan } from "./files.js";
+import { loadFile } from "./files.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { getAutoDashboardData } from "./auto.js";
 import type { AutoDashboardData } from "./auto-dashboard.js";
@@ -159,9 +160,14 @@ export class GSDDashboardOverlay {
 
       const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
       const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-      if (roadmapContent) {
-        const roadmap = parseRoadmap(roadmapContent);
-        for (const s of roadmap.slices) {
+      // Normalize slices from DB
+      type NormSlice = { id: string; done: boolean; title: string; risk: string };
+      let normSlices: NormSlice[] = [];
+      if (isDbAvailable()) {
+        normSlices = getMilestoneSlices(mid).map(s => ({ id: s.id, done: s.status === "complete", title: s.title, risk: s.risk || "medium" }));
+      }
+
+      for (const s of normSlices) {
           const sliceView: SliceView = {
             id: s.id,
             title: s.title,
@@ -172,19 +178,18 @@ export class GSDDashboardOverlay {
           };
 
           if (sliceView.active) {
-            const planFile = resolveSliceFile(base, mid, s.id, "PLAN");
-            const planContent = planFile ? await loadFile(planFile) : null;
-            if (planContent) {
-              const plan = parsePlan(planContent);
+            // Normalize tasks from DB
+            if (isDbAvailable()) {
+              const dbTasks = getSliceTasks(mid, s.id);
               sliceView.taskProgress = {
-                done: plan.tasks.filter(t => t.done).length,
-                total: plan.tasks.length,
+                done: dbTasks.filter(t => t.status === "complete" || t.status === "done").length,
+                total: dbTasks.length,
               };
-              for (const t of plan.tasks) {
+              for (const t of dbTasks) {
                 sliceView.tasks.push({
                   id: t.id,
                   title: t.title,
-                  done: t.done,
+                  done: t.status === "complete" || t.status === "done",
                   active: state.activeTask?.id === t.id,
                 });
               }
@@ -192,7 +197,6 @@ export class GSDDashboardOverlay {
           }
 
           view.slices.push(sliceView);
-        }
       }
 
       this.milestoneData = view;

package/src/resources/extensions/gsd/db-writer.ts

@@ -9,6 +9,7 @@
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
 
 import { join, resolve } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
 import type { Decision, Requirement } from './types.js';
 import { resolveGsdRootFile } from './paths.js';
 import { saveFile } from './files.js';
@@ -17,6 +18,58 @@ import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
 
+// ─── Freeform Detection ───────────────────────────────────────────────────
+
+/**
+ * Detect whether a DECISIONS.md file is in canonical table format
+ * (generated by generateDecisionsMd).
+ *
+ * Returns true only if the file starts with the canonical header
+ * ("# Decisions Register") that generateDecisionsMd produces.
+ * Files with freeform content — even if they contain an appended
+ * decisions table section — return false so the freeform content
+ * is preserved.
+ */
+export function isDecisionsTableFormat(content: string): boolean {
+  // The canonical format always starts with "# Decisions Register"
+  const firstLine = content.split('\n')[0]?.trim() ?? '';
+  if (firstLine !== '# Decisions Register') return false;
+
+  // Additionally verify the file has the canonical table header
+  return content.includes('| # | When | Scope | Decision | Choice | Rationale | Revisable?');
+}
+
+/**
+ * Generate a minimal decisions table section (header + rows) for appending
+ * to a freeform DECISIONS.md file.
+ */
+function generateDecisionsAppendBlock(decisions: Decision[]): string {
+  const lines: string[] = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('## Decisions Table');
+  lines.push('');
+  lines.push('| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |');
+  lines.push('|---|------|-------|----------|--------|-----------|------------|---------|');
+
+  for (const d of decisions) {
+    const cells = [
+      d.id,
+      d.when_context,
+      d.scope,
+      d.decision,
+      d.choice,
+      d.rationale,
+      d.revisable,
+      d.made_by ?? 'agent',
+    ].map(cell => (cell ?? '').replace(/\|/g, '\\|'));
+    lines.push(`| ${cells.join(' | ')} |`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
 // ─── Markdown Generators ──────────────────────────────────────────────────
 
 /**
@@ -230,9 +283,40 @@ export async function saveDecisionToDb(
       }));
     }
 
-    const md = generateDecisionsMd(allDecisions);
     const filePath = resolveGsdRootFile(basePath, 'DECISIONS');
-    await saveFile(filePath, md);
+
+    // Check if existing DECISIONS.md has freeform (non-table) content.
+    // If so, preserve that content and append/update the decisions table
+    // at the end instead of overwriting the entire file.
+    let existingContent: string | null = null;
+    if (existsSync(filePath)) {
+      existingContent = readFileSync(filePath, 'utf-8');
+    }
+
+    let md: string;
+    if (existingContent && !isDecisionsTableFormat(existingContent)) {
+      // Freeform content detected — preserve it and append decisions table.
+      // Strip any previously appended decisions table section to avoid duplication.
+      const marker = '---\n\n## Decisions Table';
+      const markerIdx = existingContent.indexOf(marker);
+      const freeformPart = markerIdx >= 0
+        ? existingContent.substring(0, markerIdx).trimEnd()
+        : existingContent.trimEnd();
+      md = freeformPart + '\n' + generateDecisionsAppendBlock(allDecisions);
+    } else {
+      // Table format or no existing file — full regeneration (original behavior)
+      md = generateDecisionsMd(allDecisions);
+    }
+
+    try {
+      await saveFile(filePath, md);
+    } catch (diskErr) {
+      process.stderr.write(
+        `gsd-db: saveDecisionToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
+      );
+      adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
+      throw diskErr;
+    }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
     invalidateStateCache();
@@ -301,7 +385,15 @@ export async function updateRequirementInDb(
 
     const md = generateRequirementsMd(nonSuperseded);
     const filePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-    await saveFile(filePath, md);
+    try {
+      await saveFile(filePath, md);
+    } catch (diskErr) {
+      process.stderr.write(
+        `gsd-db: updateRequirementInDb — disk write failed, reverting DB row: ${(diskErr as Error).message}\n`,
+      );
+      db.upsertRequirement(existing);
+      throw diskErr;
+    }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
     invalidateStateCache();
@@ -351,7 +443,16 @@ export async function saveArtifactToDb(
     if (!fullPath.startsWith(gsdDir)) {
       throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
     }
-    await saveFile(fullPath, opts.content);
+    try {
+      await saveFile(fullPath, opts.content);
+    } catch (diskErr) {
+      process.stderr.write(
+        `gsd-db: saveArtifactToDb — disk write failed, rolling back DB row: ${(diskErr as Error).message}\n`,
+      );
+      const rollbackAdapter = db._getAdapter();
+      rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
+      throw diskErr;
+    }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
     invalidateStateCache();

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -1,10 +1,10 @@
 // GSD Dispatch Guard — prevents out-of-order slice dispatch
 
-import { readFileSync } from "node:fs";
-import { readdirSync } from "node:fs";
-import { resolveMilestoneFile, milestonesDir } from "./paths.js";
-import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
+import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { parseRoadmap } from "./parsers-legacy.js";
+import { readFileSync } from "node:fs";
 
 const SLICE_DISPATCH_TYPES = new Set([
   "research-slice",
@@ -14,28 +14,6 @@ const SLICE_DISPATCH_TYPES = new Set([
   "complete-slice",
 ]);
 
-/**
- * Read a roadmap file from disk (working tree) rather than from a git branch.
- *
- * Prior implementation used `git show <branch>:<path>` which read committed
- * state on a specific branch. This caused false-positive blockers when work
- * was committed on a milestone/worktree branch but the integration branch
- * (main) hadn't been updated yet — the guard would see prior slices as
- * incomplete on main even though they were done in the working tree (#530).
- *
- * Reading from disk always reflects the latest state, regardless of which
- * branch is checked out or whether changes have been committed.
- */
-function readRoadmapFromDisk(base: string, milestoneId: string): string | null {
-  try {
-    const absPath = resolveMilestoneFile(base, milestoneId, "ROADMAP");
-    if (!absPath) return null;
-    return readFileSync(absPath, "utf-8").trim();
-  } catch {
-    return null;
-  }
-}
-
 export function getPriorSliceCompletionBlocker(
   base: string,
   _mainBranch: string,
@@ -58,11 +36,35 @@ export function getPriorSliceCompletionBlocker(
     if (resolveMilestoneFile(base, mid, "PARKED")) continue;
     if (resolveMilestoneFile(base, mid, "SUMMARY")) continue;
 
-    // Read from disk (working tree) — always has the latest state
-    const roadmapContent = readRoadmapFromDisk(base, mid);
-    if (!roadmapContent) continue;
+    // Normalised slice list from DB or file fallback
+    type NormSlice = { id: string; done: boolean; depends: string[] };
+    let slices: NormSlice[] | null = null;
+
+    if (isDbAvailable()) {
+      const rows = getMilestoneSlices(mid);
+      if (rows.length > 0) {
+        slices = rows.map((r) => ({
+          id: r.id,
+          done: r.status === "complete",
+          depends: r.depends ?? [],
+        }));
+      }
+    }
+    if (!slices) {
+      // File-based fallback: parse roadmap checkboxes
+      const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+      if (!roadmapPath) continue;
+      let roadmapContent: string;
+      try { roadmapContent = readFileSync(roadmapPath, "utf-8"); } catch { continue; }
+      const parsed = parseRoadmap(roadmapContent);
+      if (parsed.slices.length === 0) continue;
+      slices = parsed.slices.map((s) => ({
+        id: s.id,
+        done: s.done,
+        depends: s.depends ?? [],
+      }));
+    }
 
-    const slices = parseRoadmapSlices(roadmapContent);
     if (mid !== targetMid) {
       const incomplete = slices.find((slice) => !slice.done);
       if (incomplete) {

package/src/resources/extensions/gsd/doctor-checks.ts

@@ -3,7 +3,9 @@ import { basename, dirname, join, sep } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { readRepoMeta, externalProjectsRoot, cleanNumberedGsdVariants } from "./repo-identity.js";
-import { loadFile, parseRoadmap } from "./files.js";
+import { loadFile } from "./files.js";
+import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
+import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { resolveMilestoneFile, milestonesDir, gsdRoot, resolveGsdRootFile, relGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { saveFile } from "./files.js";
@@ -51,12 +53,18 @@ export async function checkGitHealth(
       // Check if milestone is complete via roadmap
       let isComplete = false;
       if (milestoneEntry) {
-        const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-        const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-        if (roadmapContent) {
-          const roadmap = parseRoadmap(roadmapContent);
-          isComplete = isMilestoneComplete(roadmap);
+        if (isDbAvailable()) {
+          const dbSlices = getMilestoneSlices(milestoneId);
+          isComplete = dbSlices.length > 0 && dbSlices.every(s => s.status === "complete");
+        } else {
+          const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+          if (roadmapContent) {
+            const roadmap = parseLegacyRoadmap(roadmapContent);
+            isComplete = isMilestoneComplete(roadmap);
+          }
         }
+        // When DB unavailable and no roadmap, isComplete stays false
       }
 
       if (isComplete) {
@@ -98,11 +106,17 @@ export async function checkGitHealth(
 
           const milestoneId = branch.replace(/^milestone\//, "");
           const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-          if (!roadmapContent) continue;
-
-          const roadmap = parseRoadmap(roadmapContent);
-          if (isMilestoneComplete(roadmap)) {
+          let branchMilestoneComplete = false;
+          if (isDbAvailable()) {
+            const dbSlices = getMilestoneSlices(milestoneId);
+            branchMilestoneComplete = dbSlices.length > 0 && dbSlices.every(s => s.status === "complete");
+          } else {
+            const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+            if (!roadmapContent) continue;
+            const roadmap = parseLegacyRoadmap(roadmapContent);
+            branchMilestoneComplete = isMilestoneComplete(roadmap);
+          }
+          if (branchMilestoneComplete) {
             issues.push({
               severity: "info",
               code: "stale_milestone_branch",

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -37,6 +37,29 @@ const CMD_TIMEOUT = 5_000;
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
+/** Worktree sentinel — path segment that marks an auto-worktree directory. */
+const WORKTREE_PATH_SEGMENT = `${join(".gsd", "worktrees")}/`;
+
+/**
+ * Resolve the project root when running inside a `.gsd/worktrees/<name>/`
+ * auto-worktree. Returns `null` if not in a worktree.
+ *
+ * Detection order:
+ *   1. `GSD_WORKTREE` env var (set by the worktree launcher)
+ *   2. `.gsd/worktrees/` segment in basePath
+ */
+function resolveWorktreeProjectRoot(basePath: string): string | null {
+  const envRoot = process.env.GSD_WORKTREE;
+  if (envRoot) return envRoot;
+
+  const normalised = basePath.replace(/\\/g, "/");
+  const idx = normalised.indexOf(WORKTREE_PATH_SEGMENT.replace(/\\/g, "/"));
+  if (idx === -1) return null;
+
+  // Everything before `.gsd/worktrees/` is the project root
+  return basePath.slice(0, idx);
+}
+
 function tryExec(cmd: string, cwd: string): string | null {
   try {
     return execSync(cmd, {
@@ -111,6 +134,14 @@ function checkDependenciesInstalled(basePath: string): EnvironmentCheckResult |
 
   const nodeModules = join(basePath, "node_modules");
   if (!existsSync(nodeModules)) {
+    // In auto-worktrees node_modules is absent by design — the worktree
+    // symlinks to (or expects) the project root's copy.  Fall back to
+    // checking the project root before reporting an error (#2303).
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot && existsSync(join(projectRoot, "node_modules"))) {
+      return { name: "dependencies", status: "ok", message: "Dependencies installed (project root)" };
+    }
+
     return {
       name: "dependencies",
       status: "error",