gsd-pi 2.37.1 → 2.38.0-dev.96dc7fb

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

@@ -657,6 +657,81 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — external state check failed
   }
+
+  // ── Metrics ledger integrity ───────────────────────────────────────────
+  try {
+    const metricsPath = join(root, "metrics.json");
+    if (existsSync(metricsPath)) {
+      try {
+        const raw = readFileSync(metricsPath, "utf-8");
+        const ledger = JSON.parse(raw);
+        if (ledger.version !== 1 || !Array.isArray(ledger.units)) {
+          issues.push({
+            severity: "warning",
+            code: "metrics_ledger_corrupt",
+            scope: "project",
+            unitId: "project",
+            message: "metrics.json has an unexpected structure (version !== 1 or units is not an array) — metrics data may be unreliable",
+            file: ".gsd/metrics.json",
+            fixable: false,
+          });
+        }
+      } catch {
+        issues.push({
+          severity: "warning",
+          code: "metrics_ledger_corrupt",
+          scope: "project",
+          unitId: "project",
+          message: "metrics.json is not valid JSON — metrics data may be corrupt",
+          file: ".gsd/metrics.json",
+          fixable: false,
+        });
+      }
+    }
+  } catch {
+    // Non-fatal — metrics check failed
+  }
+
+  // ── Large planning file detection ──────────────────────────────────────
+  // Files over 100KB can cause LLM context pressure. Report the worst offenders.
+  try {
+    const MAX_FILE_BYTES = 100 * 1024; // 100KB
+    const milestonesPath = milestonesDir(basePath);
+    if (existsSync(milestonesPath)) {
+      const largeFiles: Array<{ path: string; sizeKB: number }> = [];
+      function scanForLargeFiles(dir: string, depth = 0): void {
+        if (depth > 6) return;
+        try {
+          for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            try {
+              const s = statSync(full);
+              if (s.isDirectory()) { scanForLargeFiles(full, depth + 1); continue; }
+              if (entry.endsWith(".md") && s.size > MAX_FILE_BYTES) {
+                largeFiles.push({ path: full.replace(basePath + "/", ""), sizeKB: Math.round(s.size / 1024) });
+              }
+            } catch { /* skip entry */ }
+          }
+        } catch { /* skip dir */ }
+      }
+      scanForLargeFiles(milestonesPath);
+      if (largeFiles.length > 0) {
+        largeFiles.sort((a, b) => b.sizeKB - a.sizeKB);
+        const worst = largeFiles[0]!;
+        issues.push({
+          severity: "warning",
+          code: "large_planning_file",
+          scope: "project",
+          unitId: "project",
+          message: `${largeFiles.length} planning file(s) exceed 100KB — largest: ${worst.path} (${worst.sizeKB}KB). Large files cause LLM context pressure.`,
+          file: worst.path,
+          fixable: false,
+        });
+      }
+    }
+  } catch {
+    // Non-fatal — large file scan failed
+  }
 }
 
 /**

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

@@ -407,6 +407,63 @@ function checkGitRemote(basePath: string): EnvironmentCheckResult | null {
   return { name: "git_remote", status: "ok", message: "Git remote reachable" };
 }
 
+/**
+ * Check if the project build passes (opt-in slow check, use --build flag).
+ * Runs npm run build and reports failure as env_build.
+ */
+function checkBuildHealth(basePath: string): EnvironmentCheckResult | null {
+  const pkgPath = join(basePath, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const buildScript = pkg.scripts?.build;
+    if (!buildScript) return null;
+
+    const result = tryExec("npm run build 2>&1", basePath);
+    if (result === null) {
+      return {
+        name: "build",
+        status: "error",
+        message: "Build failed — npm run build exited non-zero",
+        detail: "Fix build errors before dispatching work",
+      };
+    }
+    return { name: "build", status: "ok", message: "Build passes" };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if tests pass (opt-in slow check, use --test flag).
+ * Runs npm test and reports failures as env_test.
+ */
+function checkTestHealth(basePath: string): EnvironmentCheckResult | null {
+  const pkgPath = join(basePath, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const testScript = pkg.scripts?.test;
+    // Skip if no test script or the default placeholder
+    if (!testScript || testScript.includes("no test specified")) return null;
+
+    const result = tryExec("npm test 2>&1", basePath);
+    if (result === null) {
+      return {
+        name: "test",
+        status: "warning",
+        message: "Tests failing — npm test exited non-zero",
+        detail: "Fix failing tests before shipping",
+      };
+    }
+    return { name: "test", status: "ok", message: "Tests pass" };
+  } catch {
+    return null;
+  }
+}
+
 // ── Public API ─────────────────────────────────────────────────────────────
 
 /**
@@ -454,6 +511,26 @@ export function runFullEnvironmentChecks(basePath: string): EnvironmentCheckResu
   return results;
 }
 
+/**
+ * Run slow opt-in checks (build and/or test).
+ * These are never run on the pre-dispatch gate — only on explicit /gsd doctor --build/--test.
+ */
+export function runSlowEnvironmentChecks(
+  basePath: string,
+  options?: { includeBuild?: boolean; includeTests?: boolean },
+): EnvironmentCheckResult[] {
+  const results: EnvironmentCheckResult[] = [];
+  if (options?.includeBuild) {
+    const buildCheck = checkBuildHealth(basePath);
+    if (buildCheck) results.push(buildCheck);
+  }
+  if (options?.includeTests) {
+    const testCheck = checkTestHealth(basePath);
+    if (testCheck) results.push(testCheck);
+  }
+  return results;
+}
+
 /**
  * Convert environment check results to DoctorIssue format for the doctor pipeline.
  */
@@ -477,12 +554,16 @@ export function environmentResultsToDoctorIssues(results: EnvironmentCheckResult
 export async function checkEnvironmentHealth(
   basePath: string,
   issues: DoctorIssue[],
-  options?: { includeRemote?: boolean },
+  options?: { includeRemote?: boolean; includeBuild?: boolean; includeTests?: boolean },
 ): Promise<void> {
   const results = options?.includeRemote
     ? runFullEnvironmentChecks(basePath)
     : runEnvironmentChecks(basePath);
 
+  if (options?.includeBuild || options?.includeTests) {
+    results.push(...runSlowEnvironmentChecks(basePath, options));
+  }
+
   issues.push(...environmentResultsToDoctorIssues(results));
 }
 

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

@@ -76,3 +76,23 @@ export function formatDoctorIssuesForPrompt(issues: DoctorIssue[]): string {
     return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
   }).join("\n");
 }
+
+/**
+ * Serialize a doctor report to JSON — suitable for CI/tooling integration.
+ * Usage: /gsd doctor --json
+ */
+export function formatDoctorReportJson(report: DoctorReport): string {
+  return JSON.stringify(
+    {
+      ok: report.ok,
+      basePath: report.basePath,
+      generatedAt: new Date().toISOString(),
+      summary: summarizeDoctorIssues(report.issues),
+      issues: report.issues,
+      fixesApplied: report.fixesApplied,
+      ...(report.timing ? { timing: report.timing } : {}),
+    },
+    null,
+    2,
+  );
+}

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

@@ -14,6 +14,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
+import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
 
@@ -56,6 +57,7 @@ function modelToProviderId(model: string): string | null {
       google: "google",
       anthropic: "anthropic",
       openai: "openai",
+      "github-copilot": "github-copilot",
     };
     if (prefixMap[prefix]) return prefixMap[prefix];
   }
@@ -139,7 +141,15 @@ function resolveKey(providerId: string): KeyLookup {
     }
   }
 
-  // Check environment variable
+  // Check environment variable using the authoritative env var resolution
+  // (handles multi-var lookups like ANTHROPIC_OAUTH_TOKEN || ANTHROPIC_API_KEY,
+  //  COPILOT_GITHUB_TOKEN || GH_TOKEN || GITHUB_TOKEN, Vertex ADC, Bedrock, etc.)
+  if (getEnvApiKey(providerId)) {
+    return { found: true, source: "env", backedOff: false };
+  }
+
+  // Fall back to PROVIDER_REGISTRY env var for providers not covered by getEnvApiKey
+  // (e.g., search providers like Brave, Tavily; tool providers like Jina, Context7)
   if (info?.envVar && process.env[info.envVar]) {
     return { found: true, source: "env", backedOff: false };
   }
@@ -149,6 +159,16 @@ function resolveKey(providerId: string): KeyLookup {
 
 // ── Individual check groups ────────────────────────────────────────────────────
 
+/**
+ * Providers that can serve models normally associated with another provider.
+ * Key = the provider whose models can be served, Value = alternative providers to check.
+ * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
+ */
+const PROVIDER_ROUTES: Record<string, string[]> = {
+  anthropic: ["github-copilot"],
+  openai: ["github-copilot"],
+};
+
 function checkLlmProviders(): ProviderCheckResult[] {
   const required = collectConfiguredModelProviders();
   const results: ProviderCheckResult[] = [];
@@ -159,6 +179,23 @@ function checkLlmProviders(): ProviderCheckResult[] {
     const lookup = resolveKey(providerId);
 
     if (!lookup.found) {
+      // Check if a cross-provider can serve this provider's models
+      const routes = PROVIDER_ROUTES[providerId];
+      const routeProvider = routes?.find(routeId => resolveKey(routeId).found);
+      if (routeProvider) {
+        const routeInfo = PROVIDER_REGISTRY.find(p => p.id === routeProvider);
+        const routeLabel = routeInfo?.label ?? routeProvider;
+        results.push({
+          name: providerId,
+          label,
+          category: "llm",
+          status: "ok",
+          message: `${label} — available via ${routeLabel}`,
+          required: true,
+        });
+        continue;
+      }
+
       const envVar = info?.envVar ?? `${providerId.toUpperCase()}_API_KEY`;
       results.push({
         name: providerId,

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

@@ -53,7 +53,20 @@ export type DoctorIssueCode =
   | "stranded_lock_directory"
   // Git / worktree integrity checks
   | "integration_branch_missing"
-  | "worktree_directory_orphaned";
+  | "worktree_directory_orphaned"
+  // GSD state structural checks
+  | "circular_slice_dependency"
+  | "orphaned_slice_directory"
+  | "duplicate_task_id"
+  | "task_file_not_in_plan"
+  | "stale_replan_file"
+  | "future_timestamp"
+  // Runtime data integrity
+  | "metrics_ledger_corrupt"
+  | "large_planning_file"
+  // Slow environment checks (opt-in via --build / --test flags)
+  | "env_build"
+  | "env_test";
 
 /**
  * Issue codes that represent expected completion-transition states.
@@ -83,6 +96,8 @@ export interface DoctorReport {
   basePath: string;
   issues: DoctorIssue[];
   fixesApplied: string[];
+  /** Per-domain check durations in milliseconds. Present on explicit /gsd doctor runs. */
+  timing?: { git: number; runtime: number; environment: number; gsdState: number };
 }
 
 export interface DoctorSummary {

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

@@ -1,14 +1,15 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile } from "./paths.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
 
-import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
+import type { RoadmapSliceEntry } from "./types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -17,7 +18,7 @@ import { runProviderChecks } from "./doctor-providers.js";
 // All public types and functions from extracted modules are re-exported here
 // so that existing imports from "./doctor.js" continue to work unchanged.
 export type { DoctorSeverity, DoctorIssueCode, DoctorIssue, DoctorReport, DoctorSummary } from "./doctor-types.js";
-export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt } from "./doctor-format.js";
+export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt, formatDoctorReportJson } from "./doctor-format.js";
 export { runEnvironmentChecks, runFullEnvironmentChecks, formatEnvironmentReport, type EnvironmentCheckResult } from "./doctor-environment.js";
 export { computeProgressScore, computeProgressScoreWithContext, formatProgressLine, formatProgressReport, type ProgressScore, type ProgressLevel } from "./progress-score.js";
 
@@ -350,10 +351,60 @@ export async function selectDoctorScope(basePath: string, requestedScope?: strin
   return state.registry[0]?.id;
 }
 
-export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch" }): Promise<import("./doctor-types.js").DoctorReport> {
+// ── Helper: circular dependency detection ──────────────────────────────────
+function detectCircularDependencies(slices: RoadmapSliceEntry[]): string[][] {
+  const known = new Set(slices.map(s => s.id));
+  const adj = new Map<string, string[]>();
+  for (const s of slices) adj.set(s.id, s.depends.filter(d => known.has(d)));
+  const state = new Map<string, "unvisited" | "visiting" | "done">();
+  for (const s of slices) state.set(s.id, "unvisited");
+  const cycles: string[][] = [];
+  function dfs(id: string, path: string[]): void {
+    const st = state.get(id);
+    if (st === "done") return;
+    if (st === "visiting") { cycles.push([...path.slice(path.indexOf(id)), id]); return; }
+    state.set(id, "visiting");
+    for (const dep of adj.get(id) ?? []) dfs(dep, [...path, id]);
+    state.set(id, "done");
+  }
+  for (const s of slices) if (state.get(s.id) === "unvisited") dfs(s.id, []);
+  return cycles;
+}
+
+// ── Helper: doctor run history ──────────────────────────────────────────────
+interface DoctorHistoryEntry { ts: string; ok: boolean; errors: number; warnings: number; fixes: number; codes: string[] }
+
+async function appendDoctorHistory(basePath: string, report: DoctorReport): Promise<void> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      ok: report.ok,
+      errors: report.issues.filter(i => i.severity === "error").length,
+      warnings: report.issues.filter(i => i.severity === "warning").length,
+      fixes: report.fixesApplied.length,
+      codes: [...new Set(report.issues.map(i => i.code))],
+    } satisfies DoctorHistoryEntry);
+    const existing = existsSync(historyPath) ? readFileSync(historyPath, "utf-8") : "";
+    await saveFile(historyPath, existing + entry + "\n");
+  } catch { /* non-fatal */ }
+}
+
+/** Read the last N doctor history entries. Returns most-recent-first. */
+export async function readDoctorHistory(basePath: string, lastN = 50): Promise<DoctorHistoryEntry[]> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    if (!existsSync(historyPath)) return [];
+    const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+    return lines.slice(-lastN).reverse().map(l => JSON.parse(l) as DoctorHistoryEntry);
+  } catch { return []; }
+}
+
+export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; dryRun?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch"; includeBuild?: boolean; includeTests?: boolean }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
   const fix = options?.fix === true;
+  const dryRun = options?.dryRun === true;
   const fixLevel = options?.fixLevel ?? "all";
 
   // Issue codes that represent completion state transitions — creating summary
@@ -364,11 +415,18 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
 
   /** Whether a given issue code should be auto-fixed at the current fixLevel. */
   const shouldFix = (code: DoctorIssueCode): boolean => {
-    if (!fix) return false;
+    if (!fix || dryRun) return false;
     if (fixLevel === "task" && COMPLETION_TRANSITION_CODES.has(code)) return false;
     return true;
   };
 
+  /** Log a dry-run "would fix" entry when fix=true but dryRun=true. */
+  const dryRunCanFix = (code: DoctorIssueCode, message: string): void => {
+    if (dryRun && fix && !(fixLevel === "task" && COMPLETION_TRANSITION_CODES.has(code))) {
+      fixesApplied.push(`[dry-run] would fix: ${message}`);
+    }
+  };
+
   const prefs = loadEffectiveGSDPreferences();
   if (prefs) {
     const prefIssues = validatePreferenceShape(prefs.preferences);
@@ -385,21 +443,33 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
+  // Git health checks — timed
+  const t0git = Date.now();
   const isolationMode: "none" | "worktree" | "branch" = options?.isolationMode ??
     (prefs?.preferences?.git?.isolation === "none" ? "none" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree");
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
+  const gitMs = Date.now() - t0git;
 
-  // Runtime health checks (crash locks, completed-units, hook state, activity logs, STATE.md, gitignore)
+  // Runtime health checks — timed
+  const t0runtime = Date.now();
   await checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix);
+  const runtimeMs = Date.now() - t0runtime;
 
-  // Environment health checks (#1221: missing tools, port conflicts, stale deps, disk space)
-  await checkEnvironmentHealth(basePath, issues, { includeRemote: !options?.scope });
+  // Environment health checks — timed
+  const t0env = Date.now();
+  await checkEnvironmentHealth(basePath, issues, {
+    includeRemote: !options?.scope,
+    includeBuild: options?.includeBuild,
+    includeTests: options?.includeTests,
+  });
+  const envMs = Date.now() - t0env;
 
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
-    return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };
+    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;
   }
 
   const requirementsPath = resolveGsdRootFile(basePath, "REQUIREMENTS");
@@ -465,6 +535,43 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     if (!roadmapContent) continue;
     const roadmap = parseRoadmap(roadmapContent);
 
+    // ── Circular dependency detection ──────────────────────────────────────
+    for (const cycle of detectCircularDependencies(roadmap.slices)) {
+      issues.push({
+        severity: "error",
+        code: "circular_slice_dependency",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Circular dependency detected: ${cycle.join(" → ")}`,
+        file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+        fixable: false,
+      });
+    }
+
+    // ── Orphaned slice directories ─────────────────────────────────────────
+    try {
+      const slicesDir = join(milestonePath, "slices");
+      if (existsSync(slicesDir)) {
+        const knownSliceIds = new Set(roadmap.slices.map(s => s.id));
+        for (const entry of readdirSync(slicesDir)) {
+          try {
+            if (!lstatSync(join(slicesDir, entry)).isDirectory()) continue;
+          } catch { continue; }
+          if (!knownSliceIds.has(entry)) {
+            issues.push({
+              severity: "warning",
+              code: "orphaned_slice_directory",
+              scope: "milestone",
+              unitId: milestoneId,
+              message: `Directory "${entry}" exists in ${milestoneId}/slices/ but is not referenced in the roadmap`,
+              file: `${relMilestonePath(basePath, milestoneId)}/slices/${entry}`,
+              fixable: false,
+            });
+          }
+        }
+      }
+    } catch { /* non-fatal */ }
+
     for (const slice of roadmap.slices) {
       const unitId = `${milestoneId}/${slice.id}`;
       if (options?.scope && !matchesScope(unitId, options.scope) && options.scope !== milestoneId) continue;
@@ -539,6 +646,33 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         continue;
       }
 
+      // ── Duplicate task IDs ───────────────────────────────────────────────
+      const taskIdCounts = new Map<string, number>();
+      for (const task of plan.tasks) taskIdCounts.set(task.id, (taskIdCounts.get(task.id) ?? 0) + 1);
+      for (const [taskId, count] of taskIdCounts) {
+        if (count > 1) {
+          issues.push({ severity: "error", code: "duplicate_task_id", scope: "slice", unitId,
+            message: `Task ID "${taskId}" appears ${count} times in ${slice.id}-PLAN.md — duplicate IDs cause dispatch failures`,
+            file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"), fixable: false });
+        }
+      }
+
+      // ── Task files on disk not in plan ────────────────────────────────────
+      try {
+        if (tasksDir) {
+          const planTaskIds = new Set(plan.tasks.map(t => t.id));
+          for (const f of readdirSync(tasksDir)) {
+            if (!f.endsWith("-SUMMARY.md")) continue;
+            const diskTaskId = f.replace(/-SUMMARY\.md$/, "");
+            if (!planTaskIds.has(diskTaskId)) {
+              issues.push({ severity: "info", code: "task_file_not_in_plan", scope: "slice", unitId,
+                message: `Task summary "${f}" exists on disk but "${diskTaskId}" is not in ${slice.id}-PLAN.md`,
+                file: relTaskFile(basePath, milestoneId, slice.id, diskTaskId, "SUMMARY"), fixable: false });
+            }
+          }
+        }
+      } catch { /* non-fatal */ }
+
       let allTasksDone = plan.tasks.length > 0;
       for (const task of plan.tasks) {
         const taskUnitId = `${unitId}/${task.id}`;
@@ -555,6 +689,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
             file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"),
             fixable: true,
           });
+          dryRunCanFix("task_done_missing_summary", `create stub summary for ${taskUnitId}`);
           if (shouldFix("task_done_missing_summary")) {
             const stubPath = join(
               basePath, ".gsd", "milestones", milestoneId, "slices", slice.id, "tasks",
@@ -618,6 +753,22 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           }
         }
 
+        // ── Future timestamp check ─────────────────────────────────────
+        if (task.done && hasSummary && summaryPath) {
+          try {
+            const rawSummary = await loadFile(summaryPath);
+            const m = rawSummary?.match(/^completed_at:\s*(.+)$/m);
+            if (m) {
+              const ts = new Date(m[1].trim());
+              if (!isNaN(ts.getTime()) && ts.getTime() > Date.now() + 24 * 60 * 60 * 1000) {
+                issues.push({ severity: "warning", code: "future_timestamp", scope: "task", unitId: taskUnitId,
+                  message: `Task ${task.id} has completed_at "${m[1].trim()}" which is more than 24h in the future`,
+                  file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"), fixable: false });
+              }
+            }
+          } catch { /* non-fatal */ }
+        }
+
         allTasksDone = allTasksDone && task.done;
       }
 
@@ -646,6 +797,13 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         }
       }
 
+      // ── Stale REPLAN: exists but all tasks done ────────────────────────
+      if (replanPath && allTasksDone) {
+        issues.push({ severity: "info", code: "stale_replan_file", scope: "slice", unitId,
+          message: `${slice.id} has a REPLAN.md but all tasks are done — REPLAN.md may be stale`,
+          file: relSliceFile(basePath, milestoneId, slice.id, "REPLAN"), fixable: false });
+      }
+
       const sliceSummaryPath = resolveSliceFile(basePath, milestoneId, slice.id, "SUMMARY");
       const sliceUatPath = join(slicePath, `${slice.id}-UAT.md`);
       const hasSliceSummary = !!(sliceSummaryPath && await loadFile(sliceSummaryPath));
@@ -661,6 +819,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relSliceFile(basePath, milestoneId, slice.id, "SUMMARY"),
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_missing_slice_summary", `create placeholder summary for ${unitId}`);
         if (shouldFix("all_tasks_done_missing_slice_summary")) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
@@ -674,6 +833,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: `${relSlicePath(basePath, milestoneId, slice.id)}/${slice.id}-UAT.md`,
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_missing_slice_uat", `create placeholder UAT for ${unitId}`);
         if (shouldFix("all_tasks_done_missing_slice_uat")) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
@@ -687,6 +847,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_roadmap_not_checked", `mark ${slice.id} done in roadmap`);
         if (shouldFix("all_tasks_done_roadmap_not_checked") && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
           await markSliceDoneInRoadmap(basePath, milestoneId, slice.id, fixesApplied);
         }
@@ -744,14 +905,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  if (fix && fixesApplied.length > 0) {
+  if (fix && !dryRun && fixesApplied.length > 0) {
     await updateStateFile(basePath, fixesApplied);
   }
 
-  return {
+  const report: DoctorReport = {
     ok: issues.every(issue => issue.severity !== "error"),
     basePath,
     issues,
     fixesApplied,
+    timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: Math.max(0, Date.now() - t0env - envMs) },
   };
+  await appendDoctorHistory(basePath, report);
+  return report;
 }