@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

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

@@ -13,12 +13,13 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
+import { isCursorAgentReadyUncached } from "../cursor-cli/readiness.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, supportsBrowserOAuth, type ProviderCategory } from "./key-manager.js";
-import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -49,6 +50,7 @@ const CLI_AUTH_PROVIDERS = new Set([
   "claude-code",
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 /**
@@ -57,9 +59,9 @@ const CLI_AUTH_PROVIDERS = new Set([
  * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
  */
 const PROVIDER_ROUTES: Record<string, string[]> = {
-  anthropic: ["github-copilot", "claude-code"],
-  openai: ["github-copilot", "openai-codex"],
-  google: ["google-antigravity", "google-gemini-cli"],
+  anthropic: ["github-copilot", "claude-code", "cursor-agent"],
+  openai: ["github-copilot", "openai-codex", "cursor-agent"],
+  google: ["google-antigravity", "google-gemini-cli", "cursor-agent"],
 };
 
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
@@ -86,6 +88,7 @@ function modelToProviderId(model: string): string | null {
       anthropic: "anthropic",
       openai: "openai",
       "github-copilot": "github-copilot",
+      "cursor-agent": "cursor-agent",
     };
     if (prefixMap[prefix]) return prefixMap[prefix];
     return rawPrefix;
@@ -95,6 +98,7 @@ function modelToProviderId(model: string): string | null {
   if (lower.startsWith("claude"))        return "anthropic";
   if (lower.startsWith("gpt-") || lower.startsWith("o1") || lower.startsWith("o3")) return "openai";
   if (lower.startsWith("gemini"))        return "google";
+  if (lower.startsWith("composer"))      return "cursor-agent";
   if (lower.startsWith("llama") || lower.startsWith("mixtral")) return "groq";
   if (lower.startsWith("grok"))          return "xai";
   if (lower.startsWith("mistral") || lower.startsWith("codestral")) return "mistral";
@@ -160,11 +164,13 @@ const CLI_BINARY_MAP: Record<string, string[]> = {
   "claude-code": ["claude", "claude-code"],
   "google-gemini-cli": ["gemini"],
   "google-antigravity": ["agy"],
+  "cursor-agent": ["cursor-agent"],
 };
 
 const CLI_AUTH_PATH_CHECK_PROVIDERS = new Set([
   "google-gemini-cli",
   "google-antigravity",
+  "cursor-agent",
 ]);
 
 let asyncCliBinaryPathCache: Map<string, boolean> | null = null;
@@ -212,6 +218,18 @@ function isCliBinaryInPath(providerId: string): boolean {
   return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 
+function isExternalCliProviderReady(providerId: string): boolean {
+  if (providerId === "cursor-agent") return isCursorAgentReadyUncached();
+  return isCliBinaryInPath(providerId);
+}
+
+function cursorAgentFailureDetail(): string {
+  if (!isCliBinaryInPath("cursor-agent")) {
+    return "Install Cursor Agent and ensure `cursor-agent` is on PATH";
+  }
+  return "Run `cursor-agent login` or set CURSOR_API_KEY";
+}
+
 async function isCliBinaryInPathAsync(providerId: string): Promise<boolean> {
   const executableNames = cliExecutableNames(providerId);
   if (executableNames.length === 0) return false;
@@ -345,6 +363,12 @@ function resolveKeyFromAuthOrEnv(providerId: string): KeyLookup | null {
 }
 
 function resolveKey(providerId: string): KeyLookup {
+  if (providerId === "cursor-agent") {
+    return isExternalCliProviderReady(providerId)
+      ? { found: true, source: "env", backedOff: false }
+      : { found: false, source: "none", backedOff: false };
+  }
+
   const direct = resolveKeyFromAuthOrEnv(providerId);
   if (direct) return direct;
 
@@ -354,7 +378,7 @@ function resolveKey(providerId: string): KeyLookup {
 
   // Cross-provider routes can use a local CLI when it is installed. Explicit
   // external CLI provider selections are handled in checkLlmProviders() below.
-  if (CLI_AUTH_PROVIDERS.has(providerId) && isCliBinaryInPath(providerId)) {
+  if (CLI_AUTH_PROVIDERS.has(providerId) && isExternalCliProviderReady(providerId)) {
     return { found: true, source: "env", backedOff: false };
   }
 
@@ -373,17 +397,22 @@ function checkLlmProviders(): ProviderCheckResult[] {
     if (CLI_AUTH_PROVIDERS.has(providerId)) {
       const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
       const label = info?.label ?? providerId;
-      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isCliBinaryInPath(providerId)) {
+      if (CLI_AUTH_PATH_CHECK_PROVIDERS.has(providerId) && !isExternalCliProviderReady(providerId)) {
         const binaries = CLI_BINARY_MAP[providerId]?.map(binary => `\`${binary}\``).join(" or ");
+        const detail = providerId === "cursor-agent"
+          ? cursorAgentFailureDetail()
+          : binaries
+          ? `Install ${label} and ensure ${binaries} is on PATH`
+          : `Install ${label} and ensure its CLI is on PATH`;
         results.push({
           name: providerId,
           label,
           category: "llm",
           status: "error",
-          message: `${label} — CLI not found`,
-          detail: binaries
-            ? `Install ${label} and ensure ${binaries} is on PATH`
-            : `Install ${label} and ensure its CLI is on PATH`,
+          message: providerId === "cursor-agent" && isCliBinaryInPath(providerId)
+            ? `${label} — CLI not authenticated`
+            : `${label} — CLI not found`,
+          detail,
           required: true,
         });
         continue;

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

@@ -408,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)));
       }

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

@@ -84,14 +84,21 @@ export type DoctorIssueCode =
   | "db_orphaned_task"
   | "db_orphaned_slice"
   | "db_done_task_no_summary"
+  | "artifact_file_missing"
+  | "artifact_user_content_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"
-  | "orphan_milestone_db";
+  | "orphan_milestone_db"
+  // Parent-workspace declared repository checks (#818)
+  | "workspace_repo_path_missing"
+  | "workspace_repo_not_a_repo";
 
 /**
  * Issue codes that represent global or completion-critical state.

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

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
@@ -16,6 +17,8 @@ import { isClosedStatus } from "./status-guards.js";
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
 import type { RoadmapSliceEntry } from "./types.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -308,6 +311,94 @@ export async function readDoctorHistory(basePath: string, lastN = 50): Promise<D
   } catch { return []; }
 }
 
+/**
+ * Resolve the git working-tree root for a path, or null if it is not a repo.
+ * Used by the workspace-repository probe to check that a declared child path is
+ * itself a git repository (not merely nested inside the parent's repo).
+ */
+function resolveGitToplevel(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    }).trim();
+    return out ? resolve(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** realpath that falls back to the resolved path if the link cannot be read. */
+function realpathSafe(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Parent-workspace probe (#818): validate that every declared child repository
+ * exists on disk and is a git repository at its own root. The registry only
+ * checks paths stay inside the project root; it never checks existence or
+ * git-ness, so a typo'd path (e.g. `frontned`) would otherwise build cleanly
+ * and silently produce "no problems found." No-op for single-repo projects.
+ */
+function checkWorkspaceRepositoryHealth(
+  basePath: string,
+  prefs: GSDPreferences | undefined,
+  issues: DoctorIssue[],
+): void {
+  if (prefs?.workspace?.mode !== "parent") return;
+  let registry;
+  try {
+    registry = createRepositoryRegistryFromPreferences(basePath, prefs);
+  } catch (err) {
+    issues.push({
+      severity: "error",
+      code: "invalid_preferences",
+      scope: "project",
+      unitId: "workspace",
+      message: `workspace registry failed to build: ${err instanceof Error ? err.message : String(err)}`,
+      fixable: false,
+    });
+    return;
+  }
+  for (const repo of registry.repositories) {
+    if (repo.id === "project") continue;
+    if (!existsSync(repo.root)) {
+      issues.push({
+        severity: "error",
+        code: "workspace_repo_path_missing",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path does not exist on disk: ${repo.root}`,
+        fixable: false,
+      });
+      continue;
+    }
+    // Must be a repo at its OWN root — a plain dir nested in the parent repo
+    // would otherwise pass a bare `nativeIsRepo` check via the enclosing
+    // parent's .git. Compare on realpath so symlinked temp roots (macOS
+    // /var vs /private/var) don't cause a false mismatch.
+    const toplevel = resolveGitToplevel(repo.root);
+    const declaredReal = realpathSafe(repo.root);
+    const toplevelReal = toplevel ? realpathSafe(toplevel) : null;
+    if (toplevelReal !== declaredReal) {
+      issues.push({
+        severity: "warning",
+        code: "workspace_repo_not_a_repo",
+        scope: "project",
+        unitId: `workspace.repositories.${repo.id}`,
+        message: `declared repository "${repo.id}" path is not a git repository at its own root: ${repo.root}`,
+        fixable: false,
+      });
+    }
+  }
+}
+
 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[] = [];
@@ -366,6 +457,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode, dryRun);
+  checkWorkspaceRepositoryHealth(basePath, prefs?.preferences, issues);
   const gitMs = Date.now() - t0git;
 
   // Runtime health checks — timed
@@ -386,7 +478,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const envMs = Date.now() - t0env;
 
   // Engine health checks — DB constraints and projection drift
-  await checkEngineHealth(basePath, issues, fixesApplied);
+  await checkEngineHealth(basePath, issues, fixesApplied, { repair: fix && !dryRun });
 
   const milestonesPath = milestonesDir(basePath);
   const legacyMilestonesPath2 = legacyMilestonesDir(basePath);

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -12,7 +12,8 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
+import { getShellConfig, killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
+import { redactSecrets } from "./redact-secrets.js";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -138,7 +139,12 @@ function clampTimeout(request: ExecSandboxRequest, opts: ExecSandboxOptions): nu
 function resolveCommand(runtime: ExecSandboxRequest["runtime"]): { cmd: string; args: string[] } {
   switch (runtime) {
     case "bash":
-      return { cmd: "bash", args: ["-c"] };
+      try {
+        const { shell, args } = getShellConfig();
+        return { cmd: shell, args };
+      } catch {
+        return { cmd: "bash", args: ["-c"] };
+      }
     case "node":
       return { cmd: process.execPath, args: ["-e"] };
     case "python":
@@ -310,8 +316,11 @@ export function runExecSandbox(
       const stderrBuf = Buffer.concat(stderrChunks);
       const stdoutSuffix = stdoutTruncated ? "\n[truncated: stdout cap reached]\n" : "";
       const stderrSuffix = stderrTruncated ? "\n[truncated: stderr cap reached]\n" : "";
-      writeFileSync(stdoutPath, Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]));
-      writeFileSync(stderrPath, Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]));
+      // Redact secret-shaped substrings before persisting to .gsd/exec/ (skipped by
+      // the secret scanner). The returned digest is derived from the raw buffer
+      // below and is redacted downstream when the session is written to activity/.
+      writeFileSync(stdoutPath, redactSecrets(Buffer.concat([stdoutBuf, Buffer.from(stdoutSuffix, "utf-8")]).toString("utf-8")));
+      writeFileSync(stderrPath, redactSecrets(Buffer.concat([stderrBuf, Buffer.from(stderrSuffix, "utf-8")]).toString("utf-8")));
 
       const digestBody = tail(stdoutBuf, opts.digest_chars);
       const digest =

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -11,18 +11,84 @@ import { migrateFromMarkdown } from "./md-importer.js";
 import { countDbHierarchy } from "./migration-auto-check.js";
 import { logWarning } from "./workflow-logger.js";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
-import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+import {
+  canonicalPhaseDirName,
+  dirIsContentBearingLegacyMilestone,
+  milestonesDir,
+  resolveMilestonePath,
+} from "./paths.js";
 
 const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+const RETRYABLE_FS_ERROR_CODES = new Set(["EPERM", "EBUSY", "ENOTEMPTY"]);
+const RM_RETRY_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 } as const;
+
+type FlatPhaseMigrationFsOps = {
+  cpSync: typeof cpSync;
+  renameSync: typeof renameSync;
+  rmSync: typeof rmSync;
+};
+
+let fsOps: FlatPhaseMigrationFsOps = { cpSync, renameSync, rmSync };
+
+export function _setFlatPhaseMigrationFsOpsForTest(
+  overrides: Partial<FlatPhaseMigrationFsOps>,
+): () => void {
+  const previous = fsOps;
+  fsOps = { ...fsOps, ...overrides };
+  return () => {
+    fsOps = previous;
+  };
+}
 
 function legacyMigratingPath(basePath: string): string {
   return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
 }
 
+function removePathWithRetries(path: string): void {
+  fsOps.rmSync(path, { recursive: true, force: true, maxRetries: RM_RETRY_OPTIONS.maxRetries, retryDelay: RM_RETRY_OPTIONS.retryDelay });
+}
+
+function isRetryableFsError(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code;
+  return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+
+function movePathWithCopyDeleteFallback(src: string, dst: string): void {
+  try {
+    fsOps.renameSync(src, dst);
+    return;
+  } catch (err) {
+    if (!isRetryableFsError(err)) throw err;
+  }
+
+  try {
+    fsOps.cpSync(src, dst, { recursive: true, force: true });
+    removePathWithRetries(src);
+  } catch (fallbackErr) {
+    if (existsSync(src) && existsSync(dst)) {
+      try {
+        removePathWithRetries(dst);
+      } catch {
+        // Leave the original error intact; the next run can pre-clean dst.
+      }
+    }
+    throw fallbackErr;
+  }
+}
+
+function expectedPhaseDirs(basePath: string): string[] {
+  return getAllMilestones().map((milestone) =>
+    resolveMilestonePath(basePath, milestone.id) ??
+      join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)),
+  );
+}
+
 function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
   if (!existsSync(dirPath)) return false;
   try {
-    return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+    return readdirSync(dirPath).some(
+      (e) => statSync(join(dirPath, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(dirPath, e)),
+    );
   } catch {
     return false;
   }
@@ -34,19 +100,26 @@ function rollbackPartialMigration(
   migratingPath?: string,
 ): void {
   // Remove the partially-written phases/ dir.
-  rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+  try {
+    removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
+  } catch (removeErr) {
+    logWarning(
+      "migration",
+      `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${(removeErr as Error).message}`,
+    );
+  }
   // Restore milestones/ — prefer renaming the preserved migrating copy back.
   const milestonesPath = join(basePath, ".gsd", "milestones");
   try {
     if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
-      renameSync(migratingPath, milestonesPath);
+      movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
       return;
     }
     if (existsSync(backupDir)) {
       cpSync(backupDir, milestonesPath, { recursive: true });
     }
     if (migratingPath && existsSync(migratingPath)) {
-      rmSync(migratingPath, { recursive: true, force: true });
+      removePathWithRetries(migratingPath);
     }
   } catch (restoreErr) {
     logWarning(
@@ -70,6 +143,50 @@ export function needsFlatPhaseMigration(basePath: string): boolean {
   return hasLegacyMilestoneSubdirs(legacyMigratingPath(basePath));
 }
 
+/** Retention window before flat-phase migration backups are auto-pruned. */
+export const FLAT_PHASE_BACKUP_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Remove stale flat-phase migration backups after the retention window.
+ * Only runs when migration is complete (.gsd/phases/ exists, legacy layout gone).
+ * Returns the number of migrate-* directories removed.
+ */
+export function pruneStaleFlatPhaseBackups(basePath: string): number {
+  if (needsFlatPhaseMigration(basePath)) return 0;
+
+  const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+  if (!existsSync(phasesPath)) return 0;
+
+  const backupRoot = join(basePath, ".gsd-backups");
+  if (!existsSync(backupRoot)) return 0;
+
+  const now = Date.now();
+  let removed = 0;
+  for (const entry of readdirSync(backupRoot)) {
+    if (!entry.startsWith("migrate-")) continue;
+    const dirPath = join(backupRoot, entry);
+    try {
+      const st = statSync(dirPath);
+      if (!st.isDirectory()) continue;
+      if (now - st.mtimeMs < FLAT_PHASE_BACKUP_RETENTION_MS) continue;
+      rmSync(dirPath, { recursive: true, force: true });
+      removed++;
+    } catch {
+      // Non-fatal: leave backup for manual recovery.
+    }
+  }
+
+  try {
+    if (readdirSync(backupRoot).length === 0) {
+      rmSync(backupRoot, { recursive: true, force: true });
+    }
+  } catch {
+    // Non-fatal.
+  }
+
+  return removed;
+}
+
 /**
  * Migrate from legacy nested .gsd/milestones/ to flat-phase .gsd/phases/.
  *
@@ -118,18 +235,29 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       throw err;
     }
 
+    if (existsSync(migratingPath)) {
+      removePathWithRetries(migratingPath);
+    }
+
     // 3. Rename legacy tree aside before rendering so path resolvers target
     // phases/ instead of writing back into the nested milestones/ layout.
     // Keep the full tree on disk until render+verify succeed (unlike rmSync).
     try {
-      renameSync(milestonesPath, migratingPath);
+      movePathWithCopyDeleteFallback(milestonesPath, migratingPath);
     } catch (err) {
       logWarning("migration", `failed to rename legacy milestones/ before render: ${(err as Error).message}`);
       throw err;
     }
-  } else {
-    // Interrupted run: clear any partial phases/ projection before retrying.
-    rmSync(phasesPath, { recursive: true, force: true });
+  }
+
+  // Clear any stale or partially-rendered flat projection before this run
+  // writes. Verification below checks the current DB render, not leftovers.
+  try {
+    removePathWithRetries(phasesPath);
+  } catch (err) {
+    logWarning("migration", `failed to clear stale phases/ before render: ${(err as Error).message}`);
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw err;
   }
 
   // 4. Render flat-phase from DB
@@ -167,22 +295,14 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
   }
 
   const db = countDbHierarchy();
-  let renderedDirCount = 0;
-  try {
-    // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
-    // whose dirs start with "100-slug" are counted correctly.
-    renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
-  } catch {
-    // phases/ doesn't exist or is unreadable — same as zero dirs
-  }
-  if (db.milestones > 0 && renderedDirCount !== db.milestones) {
+  const missingPhaseDirs = expectedPhaseDirs(basePath).filter((phaseDir) => !existsSync(phaseDir));
+  if (db.milestones > 0 && missingPhaseDirs.length > 0) {
     logWarning(
       "migration",
-      `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`,
+      `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`,
     );
     rollbackPartialMigration(basePath, backupDir, migratingPath);
-    throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+    throw new Error("flat-phase migration verification failed: missing rendered phase directories");
   }
   if (db.slices > 0 && renderResult.rendered === 0) {
     logWarning(
@@ -195,7 +315,7 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
 
   // 6. Verified — remove the renamed legacy tree (backup already on disk).
   try {
-    rmSync(migratingPath, { recursive: true, force: true });
+    removePathWithRetries(migratingPath);
   } catch (err) {
     logWarning(
       "migration",