@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -5,17 +5,17 @@ import { dirname, join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { loadFile } from "./files.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { deriveState, isMilestoneComplete } from "./state.js";
-import { createWorktree, listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
+import { isCompletedMilestoneTerminal } from "./milestone-closeout.js";
+import { deriveState } from "./state.js";
+import { isClosedStatus } from "./status-guards.js";
+import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
 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";
 
 /**
@@ -146,28 +146,13 @@ function getSnapshotDiffCheckFailure(basePath: string): string | null {
   return failures.length > 0 ? failures.join("\n") : null;
 }
 
-async function isCompletedMilestoneTerminal(basePath: string, milestoneId: string): Promise<boolean> {
-  const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-  if (!summaryPath) return false;
-
-  if (isDbAvailable()) {
-    const milestone = getMilestone(milestoneId);
-    return !!milestone && milestone.status === "complete";
-  }
-
-  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-  const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-  if (!roadmapContent) return false;
-  const roadmap = parseLegacyRoadmap(roadmapContent);
-  return isMilestoneComplete(roadmap);
-}
-
 export async function checkGitHealth(
   basePath: string,
   issues: DoctorIssue[],
   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)) {
@@ -175,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",
@@ -188,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.
@@ -206,7 +212,7 @@ export async function checkGitHealth(
       const milestoneId = wt.branch.replace(/^milestone\//, "");
       const milestoneEntry = state.registry.find(m => m.id === milestoneId);
       const isComplete = milestoneEntry
-        ? await isCompletedMilestoneTerminal(basePath, milestoneId)
+        ? isClosedStatus(milestoneEntry.status)
         : false;
 
       if (!isComplete && !hasProjectContentOnDisk(wt.path) && hasProjectContentOnDisk(basePath)) {
@@ -304,6 +310,8 @@ export async function checkGitHealth(
           let branchMilestoneComplete = false;
           const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
           if (!roadmapContent) continue;
+          const milestoneEntry = state.registry.find(m => m.id === milestoneId);
+          if (!milestoneEntry || !isClosedStatus(milestoneEntry.status)) continue;
           branchMilestoneComplete = await isCompletedMilestoneTerminal(basePath, milestoneId);
           if (branchMilestoneComplete) {
             issues.push({
@@ -496,8 +504,8 @@ export async function checkGitHealth(
   // that is no longer registered with git. These orphaned dirs cause
   // "already exists" errors when re-creating the same worktree name.
   try {
-    const wtDir = worktreesDir(basePath);
-    if (existsSync(wtDir)) {
+    for (const wtDir of allWorktreesDirs(basePath)) {
+      if (!existsSync(wtDir)) continue;
       // Resolve symlinks and normalize separators so that symlinked .gsd
       // paths (e.g. ~/.gsd/projects/<hash>/worktrees/…) match the paths
       // returned by `git worktree list`.

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";
@@ -58,7 +59,7 @@ const CLI_AUTH_PROVIDERS = new Set([
 const PROVIDER_ROUTES: Record<string, string[]> = {
   anthropic: ["github-copilot", "claude-code"],
   openai: ["github-copilot", "openai-codex"],
-  google: ["google-gemini-cli"],
+  google: ["google-antigravity", "google-gemini-cli"],
 };
 
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
@@ -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;
@@ -62,19 +49,19 @@ export async function checkRuntimeHealth(
     if (lock) {
       const alive = isLockProcessAlive(lock);
       if (!alive) {
-        issues.push({
-          severity: "error",
-          code: "stale_crash_lock",
-          scope: "project",
-          unitId: "project",
-          message: `Stale auto-mode worker (PID ${lock.pid}, started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
-          file: "<workers table>",
-          fixable: true,
-        });
-
         if (shouldFix("stale_crash_lock")) {
           clearStaleWorkerLock(basePath);
           fixesApplied.push("cleared stale auto-mode worker state");
+        } else {
+          issues.push({
+            severity: "error",
+            code: "stale_crash_lock",
+            scope: "project",
+            unitId: "project",
+            message: `Stale auto-mode worker (PID ${lock.pid}, started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
+            file: "<workers table>",
+            fixable: true,
+          });
         }
       }
     }
@@ -414,26 +401,31 @@ export async function checkRuntimeHealth(
         ".gsd/event-log.jsonl",
       ];
 
-      // If blanket .gsd/ or .gsd is present, all patterns are covered
+      // If blanket .gsd/ or .gsd is present, all .gsd/* patterns are covered —
+      // but NOT the .gsd-worktrees/ sibling, which always needs its own entry.
       const hasBlanketIgnore = existingLines.has(".gsd/") || existingLines.has(".gsd");
-
+      const missing: string[] = [];
+      if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
+        missing.push(".gsd-worktrees/");
+      }
       if (!hasBlanketIgnore) {
-        const missing = criticalPatterns.filter(p => !existingLines.has(p));
-        if (missing.length > 0) {
-          issues.push({
-            severity: "warning",
-            code: "gitignore_missing_patterns",
-            scope: "project",
-            unitId: "project",
-            message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-            file: ".gitignore",
-            fixable: true,
-          });
+        missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
+      }
 
-          if (shouldFix("gitignore_missing_patterns")) {
-            ensureGitignore(basePath, { manageGitignore });
-            fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-          }
+      if (missing.length > 0) {
+        issues.push({
+          severity: "warning",
+          code: "gitignore_missing_patterns",
+          scope: "project",
+          unitId: "project",
+          message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+          file: ".gitignore",
+          fixable: true,
+        });
+
+        if (shouldFix("gitignore_missing_patterns")) {
+          ensureGitignore(basePath, { manageGitignore });
+          fixesApplied.push("added missing GSD runtime patterns to .gitignore");
         }
       }
     }
@@ -462,7 +454,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"

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

@@ -3,11 +3,14 @@ import { join } from "node:path";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.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";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
@@ -192,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");
@@ -314,10 +318,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // CLI doctor can run before any tool handler has opened the DB. Runtime
   // health checks need the existing project DB to surface DB-backed crash
   // locks, paused sessions, and coordination rows.
-  const dbPath = resolveGsdPathContract(basePath).projectDb;
-  if (existsSync(dbPath)) {
-    try { openDatabase(dbPath); } catch { /* surfaced later as db_unavailable */ }
-  }
+  openExistingWorkflowDatabase(basePath);
 
   // Issue codes that represent completion state transitions — creating summary
   // stubs, marking slices/milestones done in the roadmap. These belong to the
@@ -333,6 +334,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   };
 
   const prefs = loadEffectiveGSDPreferences(basePath);
+  for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+    issues.push({
+      severity: diagnostic.severity,
+      code: "invalid_preferences",
+      scope: "project",
+      unitId: "project",
+      message: `GSD preferences ${diagnostic.kind}: ${formatPreferenceDiagnosticDetail(diagnostic)}`,
+      file: diagnostic.path,
+      fixable: false,
+    });
+  }
   if (prefs) {
     const prefIssues = validatePreferenceShape(prefs.preferences);
     for (const issue of prefIssues) {
@@ -353,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
@@ -377,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;
@@ -422,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;
@@ -461,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 };
@@ -602,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",
@@ -771,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,
       });

package/src/resources/extensions/gsd/engine-hook-contract.ts

@@ -0,0 +1,79 @@
+// Project/App: gsd-pi
+// File Purpose: Typed contract for which tool lifecycle hooks fire under which
+// engine, plus the single seam for tool-name normalization.
+//
+// ── Why this contract exists ────────────────────────────────────────────────
+// External engines (claude-code-cli) pre-execute tools inside the vendor CLI
+// and hand the agent loop a `toolCall.externalResult`. The loop short-circuits
+// before `beforeToolCall`/`afterToolCall` ever run for those calls
+// (packages/pi-agent-core/src/agent-loop.ts, prepareToolCall: the
+// externalResult branch returns an "immediate" outcome before the
+// config.beforeToolCall invocation, and "immediate" outcomes skip
+// finalizeExecutedToolCall where config.afterToolCall lives).
+// `beforeToolCall`/`afterToolCall` are exactly what the extension runner maps
+// to the `tool_call`/`tool_result` extension events
+// (packages/gsd-agent-core/src/session/agent-session-extensions.ts,
+// installAgentToolHooks).
+//
+// `tool_execution_start` is emitted unconditionally before prepareToolCall
+// and `tool_execution_end` after every finalized outcome — immediate or
+// executed — so those two are the ONLY tool lifecycle hooks that fire for
+// every tool call on every engine.
+//
+// Consequence: any enforcement attached only to `tool_call` (blocking) or
+// `tool_result` (rewriting) is silently dead under external engines. Safety
+// enforcement must ride `tool_execution_start`/`tool_execution_end`, or
+// mirror across both with toolCallId dedup. See the per-registration contract
+// comments in bootstrap/register-hooks.ts for how each registered hook
+// honors (or knowingly violates) this contract.
+
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+
+/**
+ * Tool lifecycle hooks that fire for EVERY tool call on EVERY engine,
+ * including external engines (claude-code-cli) that pre-execute tools.
+ * Attach safety-critical enforcement and evidence collection here.
+ */
+export const UNIVERSAL_TOOL_HOOKS = ["tool_execution_start", "tool_execution_end"] as const;
+
+/**
+ * Tool lifecycle hooks that fire ONLY for natively executed tools. External
+ * engines pre-execute tools (externalResult), short-circuiting the agent
+ * loop's beforeToolCall/afterToolCall — so handlers on these events never run
+ * for those calls. Blocking guards attached only here are dead under external
+ * engines; they need a tool_execution_start mirror to be universal.
+ */
+export const NATIVE_ONLY_TOOL_HOOKS = ["tool_call", "tool_result"] as const;
+
+export type UniversalToolHook = (typeof UNIVERSAL_TOOL_HOOKS)[number];
+export type NativeOnlyToolHook = (typeof NATIVE_ONLY_TOOL_HOOKS)[number];
+
+// Non-tool lifecycle events (session_start, agent_end, message_update, ...)
+// are intentionally NOT classified here: they are emitted by the session
+// host / extension runner independent of tool execution, so the external
+// engine short-circuit above does not apply to them. Only classify events
+// whose engine behavior has been verified against the agent loop.
+
+/**
+ * Canonical tool name: strips the `mcp__<server>__` prefix when present,
+ * nothing else. Use for identity checks against host/native tool names and
+ * for any guard that must NOT conflate workflow aliases with their canonical
+ * tools (e.g. write gates, evidence keys).
+ *
+ * Malformed MCP names (empty server or empty tool segment, e.g.
+ * `mcp____tool` or `mcp__server__`) are returned unchanged.
+ */
+export function canonicalToolName(toolName: string): string {
+  return stripMcpToolPrefix(toolName);
+}
+
+/**
+ * Workflow-aware canonical tool name: strips the MCP prefix AND resolves
+ * workflow tool aliases to their canonical contract names. Use whenever the
+ * name is compared against the workflow tool surface (scoping, presentation,
+ * dispatch) — plain {@link canonicalToolName} would miss alias spellings.
+ */
+export function canonicalWorkflowToolName(toolName: string): string {
+  return canonicalWorkflowSurfaceToolName(toolName);
+}