@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -1,19 +1,363 @@
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
-import { isDbAvailable, _getAdapter } from "./gsd-db.js";
+import {
+  deleteArtifactByPath,
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  isMemoriesFtsAvailable,
+  repairTaskCompletionFromSummary,
+  _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";
+import { parseSummary } from "./files.js";
+
+const USER_AUTHORED_ARTIFACT_TYPES = new Set(["CONTEXT", "RESEARCH"]);
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function relativeFile(basePath: string, filePath: string): string {
+  return relative(basePath, filePath).split("\\").join("/");
+}
+
+function normalizedArtifactType(artifactType: string): string {
+  return artifactType.trim().toUpperCase();
+}
+
+function isUserAuthoredArtifactType(artifactType: string): boolean {
+  return USER_AUTHORED_ARTIFACT_TYPES.has(normalizedArtifactType(artifactType));
+}
+
+function userContentRecoveryCommand(artifactType: string): string {
+  return normalizedArtifactType(artifactType) === "CONTEXT" ? "/gsd discuss" : "/gsd auto";
+}
+
+function userContentMissingMessage(path: string, artifactType: string): string {
+  const type = normalizedArtifactType(artifactType) || "UNKNOWN";
+  return `Artifact \`${path}\` is a user-authored ${type} file recorded in the database but missing from disk. Re-run \`${userContentRecoveryCommand(type)}\` in this milestone to regenerate it.`;
+}
+
+function artifactPathRelativeToGsd(artifactPath: string): string {
+  const parts = artifactPath.split(/[\\/]+/);
+  const gsdIndex = parts.lastIndexOf(".gsd");
+  if (gsdIndex < 0 || gsdIndex === parts.length - 1) return artifactPath;
+  return parts.slice(gsdIndex + 1).join("/");
+}
+
+function isPathInside(basePath: string, candidatePath: string): boolean {
+  const rel = relative(basePath, candidatePath);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+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 {
+  return resolveArtifactDiskPath(basePath, artifactPath) !== null;
+}
+
+function resolveArtifactDiskPath(basePath: string, artifactPath: string): string | null {
+  const relativeArtifactPath = artifactPathRelativeToGsd(artifactPath);
+  if (isAbsolute(relativeArtifactPath)) {
+    return existsSync(relativeArtifactPath) ? relativeArtifactPath : null;
+  }
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    const candidate = join(root, relativeArtifactPath);
+    if (isPathInside(root, candidate) && existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function taskExistsInPlan(basePath: string, milestoneId: string, sliceId: string, taskId: string): boolean {
+  const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (!planPath || !existsSync(planPath)) return false;
+  try {
+    return parsePlan(readFileSync(planPath, "utf-8")).tasks.some((task) => task.id === taskId);
+  } catch {
+    return false;
+  }
+}
+
+function isPassingVerificationResult(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return false;
+  if (/\b(fail(?:ed|ing)?|error|blocked|mixed|untested)\b/.test(normalized)) return false;
+  if (
+    /\b(?:not|never|no|didn't|did\s+not|cannot|can't|won't|couldn't)\s+(?:\w+\s+){0,3}?(?:pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(
+      normalized,
+    )
+  ) {
+    return false;
+  }
+  return /\b(pass(?:ed|ing)?|success(?:ful)?|succeeded)\b/.test(normalized) || normalized === "all-pass";
+}
+
+function readTaskCompletionEvidenceFromSummary(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): {
+  completedAt: string;
+  verificationResult: string;
+  title: string;
+  oneLiner: string;
+  narrative: string;
+  duration: string;
+  blockerDiscovered: boolean;
+  deviations: string;
+  knownIssues: string;
+  keyFiles: string[];
+  keyDecisions: string[];
+  fullSummaryMd: string;
+} | null {
+  if (!row.slice_id || !row.task_id) return null;
+  if (!row.task_status && Number(row.task_count) > 0 && !taskExistsInPlan(basePath, row.milestone_id, row.slice_id, row.task_id)) {
+    return null;
+  }
+  const diskPath = resolveArtifactDiskPath(basePath, row.path);
+  if (!diskPath) return null;
+  try {
+    const fullSummaryMd = readFileSync(diskPath, "utf-8");
+    const summary = parseSummary(fullSummaryMd);
+    const fm = summary.frontmatter;
+    if (fm.id !== row.task_id || fm.parent !== row.slice_id || fm.milestone !== row.milestone_id) return null;
+    if (fm.blocker_discovered) return null;
+    if (!isPassingVerificationResult(fm.verification_result)) return null;
+    const completedAt = fm.completed_at.trim();
+    if (!completedAt || !Number.isFinite(Date.parse(completedAt))) return null;
+    return {
+      completedAt,
+      verificationResult: fm.verification_result.trim(),
+      title: summary.title.replace(new RegExp(`^${escapeRegExp(row.task_id)}:\\s*`), "").trim(),
+      oneLiner: summary.oneLiner,
+      narrative: summary.whatHappened,
+      duration: fm.duration,
+      blockerDiscovered: fm.blocker_discovered,
+      deviations: summary.deviations,
+      knownIssues: summary.knownLimitations,
+      keyFiles: fm.key_files.filter((file) => file !== "(none)"),
+      keyDecisions: fm.key_decisions.filter((decision) => decision !== "(none)"),
+      fullSummaryMd,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function repairTaskArtifactDbStatusDivergence(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  const evidence = readTaskCompletionEvidenceFromSummary(basePath, row);
+  if (!evidence || !row.slice_id || !row.task_id) return false;
+  repairTaskCompletionFromSummary({
+    milestoneId: row.milestone_id,
+    sliceId: row.slice_id,
+    taskId: row.task_id,
+    ...evidence,
+  });
+  return true;
+}
+
+function artifactDbStatusDivergenceFixable(
+  basePath: string,
+  row: {
+    path: string;
+    milestone_id: string;
+    slice_id: string | null;
+    task_id: string | null;
+    task_status: string | null;
+    task_count: number;
+  },
+): boolean {
+  return readTaskCompletionEvidenceFromSummary(basePath, row) !== null;
+}
+
+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";
+}
+
+type ArtifactRow = {
+  path: string;
+  artifact_type: string;
+  milestone_id: string | null;
+  slice_id: string | null;
+  task_id: string | null;
+};
+
+function sameArtifactIdentity(left: ArtifactRow, right: ArtifactRow): boolean {
+  return left.artifact_type === right.artifact_type &&
+    left.milestone_id === right.milestone_id &&
+    left.slice_id === right.slice_id &&
+    left.task_id === right.task_id;
+}
+
+function isMilestonesArtifactPath(artifactPath: string): boolean {
+  return artifactPathRelativeToGsd(artifactPath).startsWith("milestones/");
+}
+
+function expectedMilestonesArtifactPath(row: ArtifactRow): string | null {
+  if (!row.milestone_id) return null;
+  const artifactType = normalizedArtifactType(row.artifact_type);
+  if (!artifactType) return null;
+  if (row.slice_id && row.task_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/tasks/${row.task_id}-${artifactType}.md`;
+  }
+  if (row.slice_id) {
+    return `milestones/${row.milestone_id}/slices/${row.slice_id}/${row.slice_id}-${artifactType}.md`;
+  }
+  return `milestones/${row.milestone_id}/${row.milestone_id}-${artifactType}.md`;
+}
+
+function hasPresentMilestonesReplacement(basePath: string, row: ArtifactRow, artifactRows: ArtifactRow[]): boolean {
+  const expectedPath = expectedMilestonesArtifactPath(row);
+  if (expectedPath && artifactExistsOnDisk(basePath, expectedPath)) return true;
+
+  return artifactRows.some(
+    (other) =>
+      other.path !== row.path &&
+      isMilestonesArtifactPath(other.path) &&
+      sameArtifactIdentity(row, other) &&
+      artifactExistsOnDisk(basePath, other.path),
+  );
+}
 
 export async function checkEngineHealth(
   basePath: string,
   issues: DoctorIssue[],
   fixesApplied: string[],
+  options?: { repair?: boolean },
 ): Promise<void> {
   const dbPath = resolveGsdPathContract(basePath).projectDb;
 
@@ -34,6 +378,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 +566,66 @@ 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.
+      const missingUserContentArtifacts: Array<{ path: string; artifactType: string }> = [];
+      try {
+        const artifactRows = adapter
+          .prepare(
+            `SELECT path, artifact_type, milestone_id, slice_id, task_id
+             FROM artifacts
+             WHERE path != ''
+             ORDER BY path`,
+          )
+          .all() as ArtifactRow[];
+
+        for (const row of artifactRows) {
+          if (artifactExistsOnDisk(basePath, row.path)) continue;
+          const unitId = artifactUnitId(row);
+          const issuePath = artifactPathRelativeToGsd(row.path);
+          if (options?.repair && issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows)) {
+            // Route the write through the Single Writer owner (gsd-db.ts) instead
+            // of issuing raw DELETE SQL here — doctor is a read-only consumer and
+            // the single-writer invariant forbids write SQL outside the allowlist.
+            deleteArtifactByPath(row.path);
+            fixesApplied.push(`pruned stale flat-phase artifact row ${row.path}`);
+            continue;
+          }
+          if (isUserAuthoredArtifactType(row.artifact_type)) {
+            const artifactType = normalizedArtifactType(row.artifact_type);
+            missingUserContentArtifacts.push({ path: issuePath, artifactType });
+            issues.push({
+              severity: "warning",
+              code: "artifact_user_content_missing",
+              scope: artifactScope(row),
+              unitId,
+              message: userContentMissingMessage(issuePath, artifactType),
+              file: issuePath,
+              fixable: false,
+            });
+            continue;
+          }
+          issues.push({
+            severity: "error",
+            code: "artifact_file_missing",
+            scope: artifactScope(row),
+            unitId,
+            message: `Artifact ${issuePath} is recorded in the database as ${row.artifact_type || "UNKNOWN"} but no matching file exists on disk`,
+            file: issuePath,
+            fixable: issuePath.startsWith("phases/") && hasPresentMilestonesReplacement(basePath, row, artifactRows),
+          });
+        }
+      } catch {
+        // Non-fatal — artifact file existence check failed
+      }
+      if (options?.repair) {
+        for (const artifact of missingUserContentArtifacts) {
+          fixesApplied.push(
+            `skipped user-authored ${artifact.artifactType} artifact ${artifact.path} (content cannot be regenerated from the database)`,
+          );
+        }
+      }
+
+      // g. Completion artifacts disagree with open DB hierarchy rows.
       try {
         const rows = adapter
           .prepare(
@@ -225,6 +654,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);
@@ -239,13 +669,29 @@ export async function checkEngineHealth(
               : row.milestone_id;
           if (seen.has(unitId)) continue;
           seen.add(unitId);
+          const fixable = artifactDbStatusDivergenceFixable(basePath, row);
+          let repairFailed = false;
+          if (options?.repair && fixable) {
+            try {
+              if (repairTaskArtifactDbStatusDivergence(basePath, row)) {
+                fixesApplied.push(`repaired task completion from SUMMARY artifact for ${unitId}`);
+                continue;
+              }
+            } catch {
+              repairFailed = true;
+            }
+          }
           issues.push({
             severity: "error",
             code: "artifact_db_status_divergence",
             scope: row.task_id ? "task" : row.slice_id ? "slice" : "milestone",
             unitId,
-            message: `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
-            fixable: false,
+            message: repairFailed
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor found valid SUMMARY completion evidence but could not repair the database state.`
+              : fixable
+              ? `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Doctor can repair this from the SUMMARY completion evidence.`
+              : `Completion artifact ${row.path} exists while DB state for ${unitId} is still open or missing. Runtime will not import it silently; run explicit recovery/repair after review.`,
+            fixable,
           });
         }
       } catch {
@@ -256,9 +702,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 +734,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 +745,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 +756,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.