@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/migrate/planning-writer.ts

@@ -0,0 +1,259 @@
+// Project/App: gsd-pi
+// File Purpose: DB → .planning/ projection. Parallel to writer.ts (which
+// emits .gsd/). Produces the .planning/ markdown shape that gsd-core reads.
+//
+// Layout policy (spec §4.4): emits the layout recorded in the compat marker.
+// v1 supports flat-phases; multi-milestone and legacy-milestone-dir are stubbed
+// with a clear error until fixtures exist to validate them.
+
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.js";
+import { saveFile } from "../files.js";
+import type { PlanningLayout } from "../compat/compat-marker.js";
+import {
+  applyPlanningProjectionWrites,
+  type PlanningProjectionWrite,
+} from "../compat/planning-compat.js";
+
+export interface PlanningWrittenFiles {
+  paths: string[];
+  layout: PlanningLayout;
+}
+
+function planningRoot(basePath: string): string {
+  return join(basePath, ".planning");
+}
+
+function slugify(title: string, fallback: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return slug || fallback;
+}
+
+function pad(n: number, width = 2): string {
+  return String(n).padStart(width, "0");
+}
+
+/**
+ * Format a roadmap for the flat-phases layout. Mirrors the checkbox line
+ * format that parsers.ts parsePhaseEntry recognizes: `- [x] NN — Title`.
+ */
+function formatPlanningRoadmapFlat(
+  entries: Array<{ number: number; title: string; done: boolean }>,
+): string {
+  const lines = ["# Roadmap", "", "## Phases", ""];
+  for (const e of entries) {
+    const box = e.done ? "[x]" : "[ ]";
+    lines.push(`- ${box} ${pad(e.number)} — ${e.title}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Format STATE.md in gsd-core's phase-progress schema. gsd-pi is authoritative
+ * for status; this is a one-way DB→projection (edits to STATE.md are not
+ * re-imported — see spec §7).
+ */
+function formatPlanningState(
+  activeMilestone: string,
+  totalPhases: number,
+  completedPhases: number,
+): string {
+  const pct = totalPhases === 0 ? 0 : Math.round((completedPhases / totalPhases) * 100);
+  const ts = new Date().toISOString();
+  return [
+    "---",
+    "gsd_state_version: 1.0",
+    `milestone: ${activeMilestone}`,
+    'milestone_name: "milestone"',
+    "status: active",
+    `stopped_at: Phase 01 — in progress`,
+    `last_updated: "${ts}"`,
+    `last_activity: ${ts.slice(0, 10)}`,
+    "progress:",
+    `  total_phases: ${totalPhases}`,
+    `  completed_phases: ${completedPhases}`,
+    `  total_plans: ${totalPhases}`,
+    `  completed_plans: ${completedPhases}`,
+    `  percent: ${pct}`,
+    "---",
+    "",
+    "# Project State",
+    "",
+    "Current Phase: **01**",
+    "Status: **active**",
+    "",
+  ].join("\n");
+}
+
+function formatPlanningProject(title: string): string {
+  return `# ${title}\n`;
+}
+
+/**
+ * Format a phase plan file with the XML-tagged structure parsers.ts
+ * parseOldPlan recognizes: <objective>, <tasks>, <verification>.
+ */
+function formatPlanningPlan(
+  phaseNum: number,
+  planNum: number,
+  title: string,
+  tasks: Array<{ id: string; title: string; estimate?: string }>,
+): string {
+  const lines: string[] = [];
+  lines.push(`# ${pad(phaseNum)}-${pad(planNum)}: ${title}`, "");
+  lines.push("<objective>");
+  lines.push(`${title}.`);
+  lines.push("</objective>");
+  lines.push("");
+  lines.push("<tasks>");
+  for (const t of tasks) {
+    const est = t.estimate ? ` _(${t.estimate})_` : "";
+    lines.push(`- [ ] **${t.id}**: ${t.title}${est}`);
+  }
+  lines.push("</tasks>");
+  lines.push("");
+  lines.push("<verification>");
+  lines.push("All tasks complete and tests pass.");
+  lines.push("</verification>");
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Project DB state to .planning/ in the recorded layout.
+ * Reads DB directly (canonical source). Writes via saveFile (atomic).
+ *
+ * v1: flat-phases only. Each milestone's slices become sequentially-numbered
+ * phase dirs; each task within a slice becomes a plan file (NN-MM-PLAN.md).
+ */
+export async function writePlanningDirectory(
+  basePath: string,
+  layout: PlanningLayout,
+): Promise<PlanningWrittenFiles> {
+  if (layout !== "flat-phases") {
+    // v1: flat-phases only. multi-milestone and legacy-milestone-dir need
+    // fixtures to validate the reverse-mapping (transformer.ts is non-injective
+    // — three layouts collapse to one .gsd/ shape); stub until then.
+    throw new Error(
+      `writePlanningDirectory: layout "${layout}" not yet supported (v1 supports flat-phases only)`,
+    );
+  }
+
+  const root = planningRoot(basePath);
+  mkdirSync(root, { recursive: true });
+  const paths: string[] = [];
+  const projectionWrites: PlanningProjectionWrite[] = [];
+  const toPlanningRel = (absPath: string): string =>
+    relative(root, absPath).replace(/\\/g, "/");
+
+  const milestones = getAllMilestones();
+  if (milestones.length === 0) {
+    return { paths, layout };
+  }
+
+  // Flat-phases: each slice becomes one phase. Tasks within become plan files.
+  let phaseNum = 0;
+  const roadmapEntries: Array<{ number: number; title: string; done: boolean }> = [];
+
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    for (const slice of slices) {
+      phaseNum++;
+      const phaseSlug = slugify(slice.title || slice.id, slice.id.toLowerCase());
+      const phaseDirName = `${pad(phaseNum)}-${phaseSlug}`;
+      const phaseDir = join(root, "phases", phaseDirName);
+      mkdirSync(phaseDir, { recursive: true });
+
+      const tasks = getSliceTasks(milestone.id, slice.id);
+      const isDone =
+        tasks.length > 0 && tasks.every((t) => t.status === "complete");
+      roadmapEntries.push({
+        number: phaseNum,
+        title: slice.title || slice.id,
+        done: isDone,
+      });
+
+      if (tasks.length === 0) {
+        // Empty phase — write a single placeholder plan so the dir isn't empty.
+        const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
+        await saveFile(
+          planPath,
+          formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []),
+        );
+        paths.push(planPath);
+        projectionWrites.push({
+          relPath: toPlanningRel(planPath),
+          entities: [`${milestone.id}/${slice.id}`],
+        });
+      } else {
+        for (let ti = 0; ti < tasks.length; ti++) {
+          const task = tasks[ti]!;
+          const planNum = ti + 1;
+          const planPath = join(phaseDir, `${pad(phaseNum)}-${pad(planNum)}-PLAN.md`);
+          await saveFile(
+            planPath,
+            formatPlanningPlan(phaseNum, planNum, task.title || task.id, [
+              {
+                id: task.id,
+                title: task.title || task.id,
+                estimate: task.estimate || undefined,
+              },
+            ]),
+          );
+          paths.push(planPath);
+          projectionWrites.push({
+            relPath: toPlanningRel(planPath),
+            entities: [`${milestone.id}/${slice.id}/${task.id}`],
+          });
+        }
+      }
+    }
+  }
+
+  // If no slices produced any phases, write a single empty phase so ROADMAP.md
+  // isn't blank and the layout is still discoverable.
+  if (roadmapEntries.length === 0) {
+    const phaseDirName = `${pad(1)}-milestone`;
+    const phaseDir = join(root, "phases", phaseDirName);
+    mkdirSync(phaseDir, { recursive: true });
+    const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
+    await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0]!.title || milestones[0]!.id, []));
+    paths.push(planPath);
+    projectionWrites.push({
+      relPath: toPlanningRel(planPath),
+      entities: [milestones[0]!.id],
+    });
+    roadmapEntries.push({ number: 1, title: milestones[0]!.title || milestones[0]!.id, done: false });
+  }
+
+  // Root files
+  const milestoneEntities = milestones.map((m) => m.id);
+  const roadmapPath = join(root, "ROADMAP.md");
+  await saveFile(roadmapPath, formatPlanningRoadmapFlat(roadmapEntries));
+  paths.push(roadmapPath);
+  projectionWrites.push({ relPath: toPlanningRel(roadmapPath), entities: milestoneEntities });
+
+  const completedPhases = roadmapEntries.filter((e) => e.done).length;
+  const statePath = join(root, "STATE.md");
+  await saveFile(
+    statePath,
+    formatPlanningState(milestones[0]!.id, roadmapEntries.length, completedPhases),
+  );
+  paths.push(statePath);
+  projectionWrites.push({ relPath: toPlanningRel(statePath), entities: [milestones[0]!.id] });
+
+  const projectPath = join(root, "PROJECT.md");
+  await saveFile(projectPath, formatPlanningProject(milestones[0]!.title || milestones[0]!.id));
+  paths.push(projectPath);
+  projectionWrites.push({ relPath: toPlanningRel(projectPath), entities: [milestones[0]!.id] });
+
+  applyPlanningProjectionWrites(basePath, projectionWrites);
+  return { paths, layout };
+}

package/src/resources/extensions/gsd/migrate-external.ts

@@ -7,12 +7,13 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, statSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
 import { hasGitTrackedGsdFiles } from "./gitignore.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { gsdRoot, milestonesDir, resolveGsdRootFile } from "./paths.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -159,6 +160,10 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
     }
 
+    // Remove .gsd.migrating once the junction is verified. The git-index cleanup
+    // below is best-effort and does not need the staging copy to survive.
+    rmSync(migratingPath, { recursive: true, force: true });
+
     // Clean the git index — any .gsd/* files tracked before migration now
     // sit behind the symlink and git can't follow it, causing them to show
     // as deleted. Remove them from the index so the working tree stays clean.
@@ -174,9 +179,6 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       // Non-fatal — git may be unavailable or nothing was tracked
     }
 
-    // Remove .gsd.migrating only after symlink is verified and index is clean
-    rmSync(migratingPath, { recursive: true, force: true });
-
     return { migrated: true };
   } catch (err) {
     // Rollback: rename .gsd.migrating back to .gsd
@@ -195,16 +197,57 @@ export function migrateToExternalState(basePath: string): MigrationResult {
   }
 }
 
+export 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 normalizeResolvedPath(p: string): string {
+  const normalized = p.replaceAll("\\", "/").replace(/\/+$/, "");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isLocalGsdExternalStateJunction(basePath: string, localGsd: string): boolean {
+  try {
+    const stat = lstatSync(localGsd);
+    if (!stat.isSymbolicLink()) return false;
+    const resolved = normalizeResolvedPath(realpathSync(localGsd));
+    const resolvedExternal = normalizeResolvedPath(realpathSync(externalGsdRoot(basePath)));
+    return resolved === resolvedExternal;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Recover from a failed migration (`.gsd.migrating` exists).
- * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist.
+ * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist, or removes an
+ * orphaned staging directory when `.gsd` is already a verified external state
+ * junction with intact current state.
  */
 export function recoverFailedMigration(basePath: string): boolean {
   const localGsd = join(basePath, ".gsd");
   const migratingPath = join(basePath, ".gsd.migrating");
 
   if (!existsSync(migratingPath)) return false;
-  if (existsSync(localGsd)) return false; // both exist -- ambiguous, don't touch
+  if (existsSync(localGsd)) {
+    if (!isLocalGsdExternalStateJunction(basePath, localGsd)) return false;
+    if (!isCurrentGsdStateIntactForMigratingCleanup(basePath)) return false;
+    try {
+      rmSync(migratingPath, { recursive: true, force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 
   try {
     renameSync(migratingPath, localGsd);

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
@@ -9,8 +9,8 @@ import {
 } from "./gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import {
-  milestonesDir,
   resolveMilestoneFile,
   resolveSliceFile,
 } from "./paths.js";
@@ -102,18 +102,9 @@ export function recoverWouldDeleteDbRows(basePath: string): boolean {
 }
 
 export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
-  const root = milestonesDir(basePath);
-  if (!existsSync(root)) return emptyScan();
-
   const scan = emptyScan();
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !/^M\d+/.test(entry.name)) continue;
-    // Use the CANONICAL milestone id (e.g. "M001" or "M001-a1b2c3"), matching
-    // scanDbHierarchy's milestone.id — not the raw directory name, which may
-    // carry a legacy descriptor (e.g. "M001-some-descriptor"). The canonical id
-    // both keys the identity sets AND resolves files correctly: resolveFile's
-    // prefix/legacy-pattern matching handles the descriptor dir either way.
-    const milestoneId = entry.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/)?.[1] ?? entry.name;
+  // findMilestoneIds handles both flat-phase (NN-slug) and legacy (M###) dirs.
+  for (const milestoneId of findMilestoneIds(basePath)) {
     scan.counts.milestones++;
     scan.milestones.add(milestoneId);
 

package/src/resources/extensions/gsd/milestone-actions.ts

@@ -17,6 +17,7 @@ import {
   resolveMilestonePath,
   resolveMilestoneFile,
   buildMilestoneFileName,
+  relMilestoneFile,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
@@ -61,7 +62,8 @@ export function parkMilestone(basePath: string, milestoneId: string, reason: str
     if (summaryFile) return false;
   }
 
-  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+  const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
   if (existsSync(parkedPath)) return false; // already parked
 
   const content = [
@@ -100,7 +102,8 @@ export function unparkMilestone(basePath: string, milestoneId: string): boolean
   const mDir = resolveMilestonePath(basePath, milestoneId);
   if (!mDir || !existsSync(mDir)) return false;
 
-  const parkedPath = join(mDir, buildMilestoneFileName(milestoneId, "PARKED"));
+  // Use relMilestoneFile for layout-aware path (legacy: M001-PARKED.md, flat-phase: 01-PARKED.md)
+  const parkedPath = join(basePath, relMilestoneFile(basePath, milestoneId, "PARKED"));
   const hadParkedFile = existsSync(parkedPath);
   const dbThinksParked = isDbAvailable() && getMilestone(milestoneId)?.status === "parked";
 

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -26,6 +26,7 @@ import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
 import { proveMilestoneCloseout } from "./milestone-closeout-proof.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import type { DispatchAction, DispatchContext } from "./auto-dispatch.js";
 import {
@@ -210,6 +211,16 @@ export async function evaluateCompleteMilestoneDispatch(
     }
   }
 
+  if (isDbAvailable()) {
+    // Repair only the missing-validation closeout case here; existing guards below
+    // and post-unit proof remain responsible for blocking incomplete closeouts.
+    checkCloseoutConsistencyGate(mid, {
+      allowOpenMilestone: true,
+      allowPassThroughValidation: true,
+      artifactBasePath: resolveCanonicalMilestoneRoot(basePath, mid),
+    });
+  }
+
   const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
   if (validationFile) {
     const validationContent = await loadFile(validationFile);
@@ -256,9 +267,9 @@ export async function evaluateCompleteMilestoneDispatch(
             const skippedByTrivialVariant = /trivial-scope pipeline variant/i.test(validationContent);
             const structuredMatch =
               validationContent.includes("Operational") &&
-              (validationContent.includes("MET") || validationContent.includes("N/A") || validationContent.includes("SATISFIED") || validationContent.includes("DEFERRED"));
+              (validationContent.includes("MET") || validationContent.includes("N/A") || validationContent.includes("SATISFIED") || validationContent.includes("DEFERRED") || validationContent.includes("PASS") || validationContent.includes("COVERED"));
             const proseMatch =
-              /[Oo]perational[\s\S]{0,500}?(?:✅|pass|verified|confirmed|met|complete|true|yes|addressed|covered|satisfied|partially|deferred|n\/a|not[\s-]+applicable)/i.test(validationContent);
+              /[Oo]perational[\s\S]{0,2000}?(?:✅|pass|verified|confirmed|met|complete|true|yes|addressed|covered|satisfied|partially|deferred|n\/a|not[\s-]+applicable)/i.test(validationContent);
             const hasOperationalCheck =
               skippedByMarker ||
               skippedByPreference ||

package/src/resources/extensions/gsd/milestone-ids.ts

@@ -6,9 +6,11 @@
  */
 
 import { randomInt } from "node:crypto";
+import { join } from "node:path";
 import { logWarning } from "./workflow-logger.js";
 import { readdirSync, existsSync } from "node:fs";
-import { milestonesDir } from "./paths.js";
+import { milestonesDir, gsdProjectionRoot } from "./paths.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
 import { loadQueueOrder, sortByQueueOrder } from "./queue-order.js";
 import { getErrorMessage } from "./error-utils.js";
 
@@ -139,26 +141,54 @@ export function clearReservedMilestoneIds(): void {
 
 // ─── Discovery ──────────────────────────────────────────────────────────────
 
+function scanMilestoneIdsFromDir(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      // Legacy layout: exact M001 or M001-abcdef directory name
+      if (MILESTONE_ID_RE.test(d.name)) {
+        return d.name;
+      }
+      // Legacy layout: M001-abcdef-slug descriptor directories
+      const legacyMatch = d.name.match(/^(M\d{3}(?:-[a-z0-9]{6})?)-/);
+      if (legacyMatch) {
+        return legacyMatch[1]!;
+      }
+      // Flat-phase layout: NN-slug → M00N (slug may encode M00N or M00N-abcdef)
+      const flatMatch = d.name.match(/^(\d+)-(.+)$/);
+      if (flatMatch) {
+        const phaseNum = parseInt(flatMatch[1]!, 10);
+        const fromSlug = normalizeDiscussMilestoneId(flatMatch[2]!);
+        if (MILESTONE_ID_RE.test(fromSlug)) {
+          return fromSlug;
+        }
+        return `M${String(phaseNum).padStart(3, "0")}`;
+      }
+      return null;
+    })
+    .filter((id): id is string => id !== null);
+}
+
 /** Scan the milestones directory and return IDs sorted by queue order (or numeric fallback). */
 export function findMilestoneIds(basePath: string): string[] {
-  const dir = milestonesDir(basePath);
-  try {
-    const ids = readdirSync(dir, { withFileTypes: true })
-      .filter((d) => d.isDirectory())
-      .map((d) => {
-        const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-        return match ? match[1] : null;
-      })
-      .filter((id): id is string => id !== null);
-
-    // Apply custom queue order if available, else fall back to numeric sort
-    const customOrder = loadQueueOrder(basePath);
-    return sortByQueueOrder(ids, customOrder);
-  } catch (err) {
-    // Log why milestone scanning failed — silent [] here causes infinite loops (#456)
-    if (existsSync(dir)) {
-      logWarning("engine", `findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${getErrorMessage(err)}`);
+  const root = gsdProjectionRoot(basePath);
+  const dirs = [milestonesDir(basePath)];
+  const legacyDir = join(root, "milestones");
+  if (legacyDir !== dirs[0] && existsSync(legacyDir)) dirs.push(legacyDir);
+  const phasesDir = join(root, LAYOUT_SEGMENTS.level1);
+  if (phasesDir !== dirs[0] && existsSync(phasesDir)) dirs.push(phasesDir);
+
+  const ids = new Set<string>();
+  for (const dir of dirs) {
+    try {
+      for (const id of scanMilestoneIdsFromDir(dir)) ids.add(id);
+    } catch (err) {
+      if (existsSync(dir)) {
+        logWarning("engine", `findMilestoneIds: ${dir} exists but readdirSync failed — ${getErrorMessage(err)}`);
+      }
     }
-    return [];
   }
+
+  const customOrder = loadQueueOrder(basePath);
+  return sortByQueueOrder([...ids], customOrder);
 }

package/src/resources/extensions/gsd/milestone-planning-persistence.ts

@@ -161,6 +161,14 @@ async function renderPlanArtifacts(
 ): Promise<string | { error: string }> {
   try {
     const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    // renderRoadmapFromDb only skips for unplanned milestones (zero slices +
+    // empty vision); persistMilestonePlan always populates both via writePlanRows
+    // before this render, so the skipped branch is unreachable here. Fall back to
+    // resolving the projected path so a future invariant still surfaces a clear
+    // render failure rather than an undefined dereference.
+    if ("skipped" in renderResult) {
+      return { error: `render skipped: milestone ${params.milestoneId} has no planned slices` };
+    }
     return renderResult.roadmapPath;
   } catch (renderErr) {
     logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`);

package/src/resources/extensions/gsd/milestone-validation-verdict.ts

@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
 import { loadFile } from "./files.js";
 import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
-import { gsdProjectionRoot } from "./paths.js";
+import { relMilestoneFile } from "./paths.js";
 import {
   extractVerdict,
   isValidMilestoneVerdict,
@@ -68,13 +68,11 @@ export async function resolveMilestoneValidationVerdict(
     if (projectVerdict) return projectVerdict;
   }
 
-  // Last resort: direct canonical projection path even when resolveDir helpers
-  // have not materialized the milestone directory yet.
-  const directPath = join(
-    gsdProjectionRoot(canonicalBase),
-    "milestones",
-    milestoneId,
-    `${milestoneId}-VALIDATION.md`,
-  );
+  // Last resort: layout-aware fallback path when resolveDir helpers
+  // haven't materialized the milestone directory yet. relMilestoneFile()
+  // builds the canonical NN-VALIDATION.md path for flat-phase and the
+  // legacy MID-VALIDATION.md path for projects that haven't migrated.
+  // See open-gsd/gsd-pi#876.
+  const directPath = join(canonicalBase, relMilestoneFile(canonicalBase, milestoneId, "VALIDATION"));
   return verdictFromValidationPath(directPath);
 }