@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -1,14 +1,148 @@
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import {
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  isMemoriesFtsAvailable,
+  _getAdapter,
+} from "./gsd-db.js";
+import { MEMORIES_FTS_REBUILT_KEY } from "./db-memory-fts-schema.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
-import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, gsdRoot, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
 import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 import { flushWorkflowProjections } from "./projection-flush.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { parsePlan } from "./parsers-legacy.js";
+
+function relativeFile(basePath: string, filePath: string): string {
+  return relative(basePath, filePath).split("\\").join("/");
+}
+
+function reportCheckboxDbStatusDivergence(
+  issues: DoctorIssue[],
+  basePath: string,
+  filePath: string,
+  scope: "slice" | "task",
+  unitId: string,
+  status: string,
+  checkboxDone: boolean,
+): void {
+  const dbDone = isClosedStatus(status);
+  if (checkboxDone === dbDone) return;
+
+  issues.push({
+    severity: "error",
+    code: "checkbox_db_status_divergence",
+    scope,
+    unitId,
+    message: `${scope === "slice" ? "Slice" : "Task"} ${unitId} is ${dbDone ? "closed" : "open"} in the database (status: ${status}) but the markdown checkbox is ${checkboxDone ? "checked" : "unchecked"}.`,
+    file: relativeFile(basePath, filePath),
+    fixable: false,
+  });
+}
+
+function checkProjectionCheckboxDbStatus(basePath: string, milestoneIds: string[], issues: DoctorIssue[]): void {
+  for (const milestoneId of milestoneIds) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const slices = getMilestoneSlices(milestoneId);
+
+    if (roadmapPath && existsSync(roadmapPath)) {
+      try {
+        const roadmap = readFileSync(roadmapPath, "utf-8");
+        const sliceDoneById = new Map(parseRoadmapSlices(roadmap).map((entry) => [entry.id, entry.done]));
+        for (const slice of slices) {
+          const checkboxDone = sliceDoneById.get(slice.id);
+          if (checkboxDone === undefined) continue;
+          reportCheckboxDbStatusDivergence(
+            issues,
+            basePath,
+            roadmapPath,
+            "slice",
+            `${milestoneId}/${slice.id}`,
+            slice.status,
+            checkboxDone,
+          );
+        }
+      } catch {
+        // Non-fatal — checkbox drift diagnostics must never block doctor.
+      }
+    }
+
+    for (const slice of slices) {
+      const planPath = resolveSliceFile(basePath, milestoneId, slice.id, "PLAN");
+      if (!planPath || !existsSync(planPath)) continue;
+      try {
+        const plan = readFileSync(planPath, "utf-8");
+        // parsePlan reads the authoritative task checkboxes (the flat-phase
+        // <tasks> block / ## Tasks section), so a stray task-style checkbox
+        // line elsewhere in PLAN.md (e.g. a Must-Haves or Verification bullet
+        // above <tasks>) can no longer hide real drift or fake a divergence.
+        const taskDoneById = new Map(parsePlan(plan).tasks.map((entry) => [entry.id, entry.done]));
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+          const checkboxDone = taskDoneById.get(task.id);
+          if (checkboxDone === undefined) continue;
+          reportCheckboxDbStatusDivergence(
+            issues,
+            basePath,
+            planPath,
+            "task",
+            `${milestoneId}/${slice.id}/${task.id}`,
+            task.status,
+            checkboxDone,
+          );
+        }
+      } catch {
+        // Non-fatal — checkbox drift diagnostics must never block doctor.
+      }
+    }
+  }
+}
+
+function isClearedByMilestoneShellProjectionFlush(
+  basePath: string,
+  issue: DoctorIssue,
+  reRenderedMilestoneIds: Set<string>,
+): boolean {
+  if (issue.code !== "checkbox_db_status_divergence") return false;
+  if (issue.scope !== "slice") return false;
+
+  const milestoneId = issue.unitId.split("/")[0] ?? "";
+  if (!reRenderedMilestoneIds.has(milestoneId)) return false;
+
+  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (!roadmapPath || !issue.file) return false;
+
+  return issue.file === relativeFile(basePath, roadmapPath);
+}
+
+function artifactExistsOnDisk(basePath: string, artifactPath: string): boolean {
+  if (isAbsolute(artifactPath)) return existsSync(artifactPath);
+  return [
+    join(gsdProjectionRoot(basePath), artifactPath),
+    join(gsdRoot(basePath), artifactPath),
+  ].some((candidate) => existsSync(candidate));
+}
+
+function artifactUnitId(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): string {
+  if (!row.milestone_id) return "project";
+  if (row.slice_id && row.task_id) return `${row.milestone_id}/${row.slice_id}/${row.task_id}`;
+  if (row.slice_id) return `${row.milestone_id}/${row.slice_id}`;
+  return row.milestone_id;
+}
+
+function artifactScope(row: { milestone_id: string | null; slice_id: string | null; task_id: string | null }): DoctorIssue["scope"] {
+  if (row.task_id) return "task";
+  if (row.slice_id) return "slice";
+  if (row.milestone_id) return "milestone";
+  return "project";
+}
 
 export async function checkEngineHealth(
   basePath: string,
@@ -34,6 +168,32 @@ export async function checkEngineHealth(
     if (isDbAvailable()) {
       const adapter = _getAdapter()!;
 
+      try {
+        if (isMemoriesFtsAvailable(adapter)) {
+          const runtimeKv = adapter
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='runtime_kv'")
+            .get();
+          const marker = runtimeKv
+            ? adapter.prepare(
+                "SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+              ).get({ ":key": MEMORIES_FTS_REBUILT_KEY })
+            : undefined;
+          if (!marker) {
+            issues.push({
+              severity: "warning",
+              code: "memories_fts_rebuild_missing",
+              scope: "project",
+              unitId: "project",
+              message: `Memory full-text index exists but runtime_kv has no ${MEMORIES_FTS_REBUILT_KEY} marker. The index may be stale or incomplete, so memory search can silently degrade to the LIKE fallback.`,
+              file: ".gsd/gsd.db",
+              fixable: false,
+            });
+          }
+        }
+      } catch {
+        // Non-fatal — memory FTS health check failed
+      }
+
       // a. Orphaned tasks (task.slice_id points to non-existent slice)
       try {
         const orphanedTasks = adapter
@@ -196,7 +356,41 @@ export async function checkEngineHealth(
         // Non-fatal — completed-milestone reopen check failed
       }
 
-      // f. Completion artifacts disagree with open DB hierarchy rows.
+      // f. Artifact rows reference files that no longer exist on disk.
+      try {
+        const artifactRows = adapter
+          .prepare(
+            `SELECT path, artifact_type, milestone_id, slice_id, task_id
+             FROM artifacts
+             WHERE path != ''
+             ORDER BY path`,
+          )
+          .all() as Array<{
+            path: string;
+            artifact_type: string;
+            milestone_id: string | null;
+            slice_id: string | null;
+            task_id: string | null;
+          }>;
+
+        for (const row of artifactRows) {
+          if (artifactExistsOnDisk(basePath, row.path)) continue;
+          const unitId = artifactUnitId(row);
+          issues.push({
+            severity: "error",
+            code: "artifact_file_missing",
+            scope: artifactScope(row),
+            unitId,
+            message: `Artifact ${row.path} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+            file: row.path,
+            fixable: false,
+          });
+        }
+      } catch {
+        // Non-fatal — artifact file existence check failed
+      }
+
+      // g. Completion artifacts disagree with open DB hierarchy rows.
       try {
         const rows = adapter
           .prepare(
@@ -225,6 +419,7 @@ export async function checkEngineHealth(
 
         const seen = new Set<string>();
         for (const row of rows) {
+          if (!artifactExistsOnDisk(basePath, row.path)) continue;
           const reopenAt = latestExplicitReopenAt(basePath, row.milestone_id);
           if (!isAfter(row.imported_at, reopenAt)) continue;
           const isSliceSummary = row.slice_id && !row.task_id && row.slice_status && !["complete", "done", "skipped", "closed"].includes(row.slice_status);
@@ -256,9 +451,24 @@ export async function checkEngineHealth(
     // Non-fatal — DB constraint checks failed entirely
   }
 
+  // Checkbox-vs-DB divergence detection runs before projection drift auto-fix
+  // so stale re-renders cannot overwrite manually edited markdown first. Runs
+  // inside its own try/catch: getAllMilestones / getMilestoneSlices /
+  // getSliceTasks issue prepared queries that can throw on a corrupt or locked
+  // DB, and like every other DB-touching check here this diagnostic must never
+  // block doctor.
+  try {
+    if (isDbAvailable()) {
+      checkProjectionCheckboxDbStatus(basePath, getAllMilestones().map((milestone) => milestone.id), issues);
+    }
+  } catch {
+    // Non-fatal: checkbox-vs-DB divergence check must never block doctor
+  }
+
   // ── Projection drift detection ──────────────────────────────────────────
   // If the DB is available, check whether markdown projections are stale
   // relative to the event log and re-render them.
+  const reRenderedMilestoneIds: string[] = [];
   try {
     if (isDbAvailable()) {
       const eventLogPath = workflowEventLogPath(basePath);
@@ -273,6 +483,7 @@ export async function checkEngineHealth(
             try {
               await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
+              reRenderedMilestoneIds.push(milestone.id);
             } catch {
               // Non-fatal — projection re-render failed
             }
@@ -283,6 +494,7 @@ export async function checkEngineHealth(
             try {
               await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
+              reRenderedMilestoneIds.push(milestone.id);
             } catch {
               // Non-fatal — projection re-render failed
             }
@@ -293,4 +505,20 @@ export async function checkEngineHealth(
   } catch {
     // Non-fatal — projection drift check must never block doctor
   }
+
+  if (reRenderedMilestoneIds.length > 0) {
+    const reRendered = new Set(reRenderedMilestoneIds);
+    for (let i = issues.length - 1; i >= 0; i--) {
+      const issue = issues[i]!;
+      // flushWorkflowProjections re-renders milestone shell projections (not
+      // slice PLAN.md files), so only clear stale ROADMAP checkbox diagnostics.
+      if (isClearedByMilestoneShellProjectionFlush(basePath, issue, reRendered)) {
+        issues.splice(i, 1);
+        continue;
+      }
+      if (issue.code === "artifact_file_missing" && issue.file && artifactExistsOnDisk(basePath, issue.file)) {
+        issues.splice(i, 1);
+      }
+    }
+  }
 }

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

@@ -15,7 +15,7 @@ import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegr
 import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { listUnmergedGitPaths } from "./git-conflict-state.js";
+import { listUnmergedGitPaths, probeGitConflictState, reconcileGitConflictsOnSignal } from "./git-conflict-state.js";
 import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 /**
@@ -152,6 +152,7 @@ export async function checkGitHealth(
   fixesApplied: string[],
   shouldFix: (code: DoctorIssueCode) => boolean,
   isolationMode: "none" | "worktree" | "branch" = "none",
+  dryRun = false,
 ): Promise<void> {
   // Degrade gracefully if not a git repo
   if (!nativeIsRepo(basePath)) {
@@ -159,7 +160,7 @@ export async function checkGitHealth(
   }
 
   const gitDir = resolveGitDir(basePath);
-  const unmergedPaths = listUnmergedGitPaths(basePath);
+  let unmergedPaths = listUnmergedGitPaths(basePath);
   if (unmergedPaths === null) {
     issues.push({
       severity: "error",
@@ -172,6 +173,27 @@ export async function checkGitHealth(
     return;
   }
 
+  // ── Auto-resolve safe conflicts before reporting ──────────────────────
+  // A failed worktree merge (e.g. during complete-slice) can leave conflict
+  // markers for paths that are always safe to accept from the milestone side
+  // (.gsd/ state and build artifacts). Run the same reconciliation the
+  // preflight/auto-worktree paths use before the doctor hard-blocks auto-mode,
+  // so only genuinely-manual conflicts remain. This also clears stale
+  // merge-state markers (e.g. MERGE_HEAD) in the same pass when auto-resolve
+  // empties the unmerged set (#849).
+  if (unmergedPaths.length > 0 && !dryRun) {
+    try {
+      const reconcileFixes = reconcileGitConflictsOnSignal(basePath, probeGitConflictState(basePath));
+      if (reconcileFixes.length > 0) {
+        fixesApplied.push(...reconcileFixes);
+        const refreshed = listUnmergedGitPaths(basePath);
+        if (refreshed !== null) unmergedPaths = refreshed;
+      }
+    } catch {
+      // Non-fatal — fall through to report the unmerged paths as-is
+    }
+  }
+
   // ── Orphaned auto-worktrees & Stale milestone branches ────────────────
   // These checks only apply in worktree/branch modes — skip in none mode
   // where no milestone worktrees or branches are created.

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

@@ -12,6 +12,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { access, readFile } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
@@ -166,15 +167,11 @@ const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
   "google-antigravity",
 ]);
 
-/**
- * Check if a CLI provider's binary exists anywhere in PATH.
- * Fast filesystem scan — no subprocess, no network, sub-1ms.
- */
-function isCliBinaryInPath(providerId: string): boolean {
-  const binaries = CLI_BINARY_MAP[providerId];
-  if (!binaries) return false;
+let asyncCliBinaryPathCache: Map<string, boolean> | null = null;
 
-  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+function cliExecutableNames(providerId: string): string[] {
+  const binaries = CLI_BINARY_MAP[providerId];
+  if (!binaries) return [];
 
   // On Windows, command shims are commonly installed as .cmd/.exe/.bat/.com.
   // Scan PATHEXT candidates in addition to the bare binary name.
@@ -196,9 +193,51 @@ function isCliBinaryInPath(providerId: string): boolean {
     }
   }
 
+  return executableNames;
+}
+
+/**
+ * Check if a CLI provider's binary exists anywhere in PATH.
+ * Fast filesystem scan — no subprocess, no network, sub-1ms.
+ */
+function isCliBinaryInPath(providerId: string): boolean {
+  const cached = asyncCliBinaryPathCache?.get(providerId);
+  if (cached !== undefined) return cached;
+
+  const executableNames = cliExecutableNames(providerId);
+  if (executableNames.length === 0) return false;
+
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+
   return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 
+async function isCliBinaryInPathAsync(providerId: string): Promise<boolean> {
+  const executableNames = cliExecutableNames(providerId);
+  if (executableNames.length === 0) return false;
+
+  const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const candidates = pathDirs.flatMap(dir => executableNames.map(name => join(dir, name)));
+  if (candidates.length === 0) return false;
+
+  try {
+    await Promise.any(candidates.map(candidate => access(candidate)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadCliBinaryPathCache(): Promise<Map<string, boolean>> {
+  const entries = await Promise.all(
+    Object.keys(CLI_BINARY_MAP).map(async providerId => [
+      providerId,
+      await isCliBinaryInPathAsync(providerId),
+    ] as const),
+  );
+  return new Map(entries);
+}
+
 function modelsJsonPaths(): string[] {
   const home = homedir();
   return [
@@ -208,7 +247,13 @@ function modelsJsonPaths(): string[] {
   ];
 }
 
+let asyncModelsJsonApiKeyCache: Set<string> | null = null;
+
 function hasModelsJsonApiKey(providerId: string): boolean {
+  if (asyncModelsJsonApiKeyCache) {
+    return asyncModelsJsonApiKeyCache.has(providerId);
+  }
+
   for (const path of modelsJsonPaths()) {
     if (!existsSync(path)) continue;
     try {
@@ -226,7 +271,27 @@ function hasModelsJsonApiKey(providerId: string): boolean {
   return false;
 }
 
-function resolveKey(providerId: string): KeyLookup {
+async function loadModelsJsonApiKeyCache(): Promise<Set<string>> {
+  const providersWithKeys = new Set<string>();
+  for (const path of modelsJsonPaths()) {
+    try {
+      const parsed = JSON.parse(await readFile(path, "utf-8")) as {
+        providers?: Record<string, { apiKey?: unknown }>;
+      };
+      for (const [providerId, provider] of Object.entries(parsed.providers ?? {})) {
+        const apiKey = provider.apiKey;
+        if (typeof apiKey === "string" && apiKey.trim().length > 0) {
+          providersWithKeys.add(providerId);
+        }
+      }
+    } catch {
+      // Missing or malformed models.json should not break dashboard health checks.
+    }
+  }
+  return providersWithKeys;
+}
+
+function resolveKeyFromAuthOrEnv(providerId: string): KeyLookup | null {
   const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
 
   if (providerId === "anthropic-vertex" && process.env.ANTHROPIC_VERTEX_PROJECT_ID) {
@@ -276,6 +341,13 @@ function resolveKey(providerId: string): KeyLookup {
     return { found: true, source: "env", backedOff: false };
   }
 
+  return null;
+}
+
+function resolveKey(providerId: string): KeyLookup {
+  const direct = resolveKeyFromAuthOrEnv(providerId);
+  if (direct) return direct;
+
   if (hasModelsJsonApiKey(providerId)) {
     return { found: true, source: "models.json", backedOff: false };
   }
@@ -495,6 +567,28 @@ export function runProviderChecks(): ProviderCheckResult[] {
   return results;
 }
 
+/**
+ * Non-blocking equivalent of `runProviderChecks` for the health-widget
+ * background refresh. PATH checks and custom models.json discovery use async
+ * filesystem APIs so periodic widget refreshes do not stall the input loop.
+ */
+export async function runProviderChecksAsync(): Promise<ProviderCheckResult[]> {
+  const [cliCache, modelsJsonCache] = await Promise.all([
+    loadCliBinaryPathCache(),
+    loadModelsJsonApiKeyCache(),
+  ]);
+  const previousCliCache = asyncCliBinaryPathCache;
+  const previousModelsJsonCache = asyncModelsJsonApiKeyCache;
+  asyncCliBinaryPathCache = cliCache;
+  asyncModelsJsonApiKeyCache = modelsJsonCache;
+  try {
+    return runProviderChecks();
+  } finally {
+    asyncCliBinaryPathCache = previousCliCache;
+    asyncModelsJsonApiKeyCache = previousModelsJsonCache;
+  }
+}
+
 /**
  * Format provider check results as a human-readable report string.
  */

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

@@ -12,7 +12,7 @@ import { getActiveAutoWorkers } from "./db/auto-workers.js";
 import { normalizeRealPath } from "./paths.js";
 import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
-import { recoverFailedMigration } from "./migrate-external.js";
+import { isCurrentGsdStateIntactForMigratingCleanup, recoverFailedMigration } from "./migrate-external.js";
 import { splitCompletedKey } from "./forensics.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { getAllMilestones, isDbAvailable } from "./gsd-db.js";
@@ -20,19 +20,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 const MAX_UAT_ATTEMPTS = 3;
 
-function isCurrentGsdStateIntactForMigratingCleanup(basePath: string): boolean {
-  try {
-    const stateFile = resolveGsdRootFile(basePath, "STATE");
-    const milestonesPath = milestonesDir(basePath);
-    const dbPath = join(gsdRoot(basePath), "gsd.db");
-    const hasDbFile = existsSync(dbPath);
-    const hasNonEmptyDb = hasDbFile && statSync(dbPath).size > 0;
-    return existsSync(stateFile) && existsSync(milestonesPath) && hasNonEmptyDb;
-  } catch {
-    return false;
-  }
-}
-
 function hasAssessmentVerdict(basePath: string, mid: string, sid: string): boolean {
   const assessmentPath = join(gsdRoot(basePath), "milestones", mid, "slices", sid, `${sid}-ASSESSMENT.md`);
   if (!existsSync(assessmentPath)) return false;
@@ -421,6 +408,9 @@ export async function checkRuntimeHealth(
       if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
         missing.push(".gsd-worktrees/");
       }
+      if (!existingLines.has(".gsd-backups/") && !existingLines.has(".gsd-backups")) {
+        missing.push(".gsd-backups/");
+      }
       if (!hasBlanketIgnore) {
         missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
       }
@@ -467,7 +457,7 @@ export async function checkRuntimeHealth(
 
         if (shouldFix("failed_migration")) {
           if (recoverFailedMigration(basePath)) {
-            fixesApplied.push("recovered failed migration (.gsd.migrating → .gsd)");
+            fixesApplied.push("recovered failed external state migration");
           } else if (isCurrentGsdStateIntactForMigratingCleanup(basePath)) {
             try {
               rmSync(migratingPath, { recursive: true, force: true });

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

@@ -2,6 +2,7 @@
 export type DoctorSeverity = "info" | "warning" | "error";
 export type DoctorIssueCode =
   | "invalid_preferences"
+  | "missing_roadmap"
   | "missing_tasks_dir"
   | "missing_slice_plan"
   | "all_slices_done_missing_milestone_validation"
@@ -83,10 +84,13 @@ export type DoctorIssueCode =
   | "db_orphaned_task"
   | "db_orphaned_slice"
   | "db_done_task_no_summary"
+  | "artifact_file_missing"
   | "artifact_db_status_divergence"
+  | "checkbox_db_status_divergence"
   | "completed_milestone_reopened"
   | "db_duplicate_id"
   | "db_unavailable"
+  | "memories_fts_rebuild_missing"
   | "projection_drift"
   // Milestone filesystem/DB drift (#4996)
   | "orphan_milestone_dir"

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

@@ -5,7 +5,8 @@ import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHave
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { openExistingWorkflowDatabase } from "./db-workspace.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, legacyMilestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
@@ -194,7 +195,8 @@ export async function selectDoctorScope(basePath: string, requestedScope?: strin
   }
 
   const milestonesPath = milestonesDir(basePath);
-  if (!existsSync(milestonesPath)) return undefined;
+  const legacyMilestonesPath = legacyMilestonesDir(basePath);
+  if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath)) return undefined;
 
   for (const milestone of state.registry) {
     const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
@@ -363,7 +365,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const isolationMode: "none" | "worktree" | "branch" = options?.isolationMode ??
     (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
-  await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
+  await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode, dryRun);
   const gitMs = Date.now() - t0git;
 
   // Runtime health checks — timed
@@ -387,7 +389,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   await checkEngineHealth(basePath, issues, fixesApplied);
 
   const milestonesPath = milestonesDir(basePath);
-  if (!existsSync(milestonesPath)) {
+  const legacyMilestonesPath2 = legacyMilestonesDir(basePath);
+  if (!existsSync(milestonesPath) && !existsSync(legacyMilestonesPath2)) {
     const report: DoctorReport = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
     await appendDoctorHistory(basePath, report);
     return report;
@@ -432,7 +435,15 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  for (const milestone of state.registry) {
+  // When DB is unavailable, state.registry is empty. Fall back to a direct
+  // filesystem scan so the doctor can still report issues (e.g. missing ROADMAP)
+  // for milestone dirs that exist on disk.
+  const milestoneEntries: Array<{ id: string; title: string }> =
+    state.registry.length > 0
+      ? state.registry
+      : findMilestoneIds(basePath).map(id => ({ id, title: id }));
+
+  for (const milestone of milestoneEntries) {
     const milestoneId = milestone.id;
     const milestonePath = resolveMilestonePath(basePath, milestoneId);
     if (!milestonePath) continue;
@@ -471,7 +482,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
 
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-    if (!roadmapContent) continue;
+    if (!roadmapContent) {
+      issues.push({
+        severity: "error",
+        code: "missing_roadmap",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Milestone ${milestoneId} is missing its ROADMAP.md file.`,
+        fixable: false,
+      });
+      continue;
+    }
 
     // Normalize slices: prefer DB, fall back to parser
     type NormSlice = RoadmapSliceEntry & { pending?: boolean; skipped?: boolean };
@@ -612,6 +633,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         // Pending slices haven't been planned yet — tasks/ is created on demand.
         // Skipped slices may legitimately never create tasks/.
         if (slice.pending || slice.skipped) continue;
+        // Flat-phase: tasks are embedded in plan files; no tasks/ subdir expected.
+        if (!existsSync(legacyMilestonesDir(basePath))) continue;
         issues.push({
           severity: slice.done ? "warning" : "error",
           code: "missing_tasks_dir",
@@ -781,7 +804,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         code: "all_slices_done_missing_milestone_validation",
         scope: "milestone",
         unitId: milestoneId,
-        message: `All slices are done but ${milestoneId}-VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
+        message: `All slices are done but the milestone VALIDATION.md is missing \u2014 milestone is in validating-milestone phase`,
         file: relMilestoneFile(basePath, milestoneId, "VALIDATION"),
         fixable: false,
       });