@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -9,19 +9,23 @@
 // Critical invariant: rendered markdown must round-trip through
 // parseRoadmap(), parsePlan(), parseSummary() in files.ts.
 
-import { readFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
 import { dirname, join, relative } from "node:path";
 import {
   getAllMilestones,
   getMilestone,
+  getMilestoneScopedArtifacts,
+  getSliceScopedArtifacts,
   getMilestoneSlices,
   getSliceTasks,
   getTask,
   getSlice,
   insertArtifact,
+  deleteArtifactByPath,
   getGateResults,
+  isDbAvailable,
 } from "./gsd-db.js";
 import type { MilestoneRow, ArtifactRow } from "./db-milestone-artifact-rows.js";
 import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
@@ -31,6 +35,8 @@ import {
   resolveFile,
   resolveSliceFile,
   resolveSlicePath,
+  resolveTaskFile,
+  resolveTasksDir,
   gsdProjectionRoot,
   gsdRoot,
   buildMilestoneFileName,
@@ -40,8 +46,60 @@ import {
 import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.js";
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { invalidateStateCache } from "./state.js";
-import { clearPathCache } from "./paths.js";
+import { clearPathCache, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, resolveMilestonePath, relSliceFile, canonicalPhaseDirName } from "./paths.js";
+import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./compat/compat-marker.js";
 import type { RiskLevel } from "./types.js";
+import {
+  phaseDirName,
+  planFileName,
+  milestoneIdToPhaseNum,
+  sliceIdToPlanNum,
+  derivePhaseSlug,
+} from "./layout-policy.js";
+
+// ─── Compat marker invalidation ───────────────────────────────────────────
+// Every successful projection write pushes its (basePath, projectionPath,
+// entities) here; invalidateCaches() drains it and refreshes .gsd/.compat.json
+// so the next reconcile pass sees gsd-pi's own writes as expected. This is the
+// feedback-loop-prevention mechanism for cross-tool compatibility.
+const _pendingProjectionWrites: Array<{ basePath: string; projectionPath: string; entities: string[] }> = [];
+
+function recordProjectionWrite(basePath: string, projectionPath: string, entities: string[]): void {
+  _pendingProjectionWrites.push({ basePath, projectionPath, entities });
+}
+
+function flushProjectionWritesToMarker(): void {
+  if (_pendingProjectionWrites.length === 0) return;
+  // Group by basePath (defensive — multiple projects are unusual but possible).
+  const byBase = new Map<string, Map<string, string[]>>();
+  for (const w of _pendingProjectionWrites) {
+    let bucket = byBase.get(w.basePath);
+    if (!bucket) { bucket = new Map(); byBase.set(w.basePath, bucket); }
+    bucket.set(w.projectionPath, w.entities);
+  }
+  _pendingProjectionWrites.length = 0;
+
+  for (const [basePath, writes] of byBase) {
+    try {
+      const marker = readCompatMarker(basePath);
+      for (const [projectionPath, entities] of writes) {
+        const abs = join(basePath, ".gsd", projectionPath);
+        if (existsSync(abs)) {
+          marker.projections[projectionPath] = {
+            sha: computeProjectionSha(readFileSync(abs, "utf-8")),
+            entities,
+          };
+        }
+      }
+      marker.lastWriter = "gsd-pi";
+      marker.lastProjectedAt = new Date().toISOString();
+      writeCompatMarker(basePath, marker);
+    } catch (e) {
+      // Marker I/O must never break projection. Reconcile will heal on next run.
+      logWarning("renderer", `compat marker flush failed: ${(e as Error).message}`);
+    }
+  }
+}
 
 // ─── Helpers ──────────────────────────────────────────────────────────────
 
@@ -64,6 +122,7 @@ function toArtifactPath(absPath: string, basePath: string): string {
  * Invalidate all caches after a disk write.
  */
 function invalidateCaches(): void {
+  flushProjectionWritesToMarker();
   invalidateStateCache();
   clearPathCache();
   clearParseCache();
@@ -87,7 +146,9 @@ function taskSummaryForSlicePlan(description: string): string {
   const meaningful = meaningfulSection(description);
   if (!meaningful) return "";
 
-  const beforeHeading = meaningful.split(/\n#{1,6}\s+/)[0]?.trim() ?? "";
+  // Strip XML tags (flat-phase <tasks> format) so they don't leak into summaries
+  const cleaned = meaningful.replace(/<\/?tasks>/g, "").trim();
+  const beforeHeading = cleaned.split(/\n#{1,6}\s+/)[0]?.trim() ?? "";
   const firstBlock = beforeHeading.split(/\n\s*\n/)[0]?.trim() ?? "";
   return firstBlock || beforeHeading;
 }
@@ -109,12 +170,28 @@ function sanitizeInlineRoadmapText(value: string | null | undefined): string {
 }
 
 function resolveRoadmapProjectionPath(basePath: string, milestoneId: string): string {
-  const projectionMilestonesDir = join(gsdProjectionRoot(basePath), "milestones");
-  const milestoneDirName = resolveDir(projectionMilestonesDir, milestoneId) ?? milestoneId;
-  const milestoneDir = join(projectionMilestonesDir, milestoneDirName);
-  const roadmapFileName = resolveFile(milestoneDir, milestoneId, "ROADMAP") ??
-    buildMilestoneFileName(milestoneId, "ROADMAP");
-  return join(milestoneDir, roadmapFileName);
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const existing = resolveMilestonePath(basePath, milestoneId);
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacyLayout = existing
+    ? existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\")
+    : isLegacyMilestonesLayout(basePath);
+  const phaseDir = existing ?? join(
+    isLegacyLayout ? legacyBase : milestonesDir(basePath),
+    isLegacyLayout ? milestoneId : canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
+  );
+  const roadmapFileName = isLegacyLayout
+    ? `${milestoneId}-ROADMAP.md`
+    : `${String(phaseNum).padStart(2, "0")}-ROADMAP.md`;
+  return join(phaseDir, roadmapFileName);
+}
+
+function isMilestoneFlatPhaseLayout(basePath: string, milestoneId: string): boolean {
+  const existing = resolveMilestonePath(basePath, milestoneId);
+  const legacyBase = legacyMilestonesDir(basePath);
+  return existing
+    ? !(existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\"))
+    : !isLegacyMilestonesLayout(basePath);
 }
 
 /**
@@ -130,6 +207,7 @@ async function writeAndStore(
     slice_id?: string;
     task_id?: string;
   },
+  basePath?: string,
 ): Promise<void> {
   await saveFile(absPath, content);
 
@@ -147,6 +225,17 @@ async function writeAndStore(
     logWarning("renderer", `failed to update artifact in DB: ${artifactPath}`);
   }
 
+  // Record the projection write so invalidateCaches() can refresh the compat
+  // marker. basePath is optional only to avoid forcing every caller; when
+  // present, the marker gets updated. artifactPath is already .gsd/-relative.
+  if (basePath) {
+    const entities: string[] = [];
+    if (opts.milestone_id) entities.push(opts.milestone_id);
+    if (opts.milestone_id && opts.slice_id) entities.push(`${opts.milestone_id}/${opts.slice_id}`);
+    if (opts.milestone_id && opts.slice_id && opts.task_id) entities.push(`${opts.milestone_id}/${opts.slice_id}/${opts.task_id}`);
+    recordProjectionWrite(basePath, artifactPath, entities);
+  }
+
   invalidateCaches();
 }
 
@@ -171,7 +260,8 @@ function renderRoadmapMarkdown(milestone: MilestoneRow, slices: SliceRow[]): str
   lines.push("");
   for (const slice of slices) {
     const done = isClosedStatus(slice.status) ? "x" : " ";
-    const depends = `[${(slice.depends ?? []).join(",")}]`;
+    const cleanDepends = (slice.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d));
+    const depends = `[${cleanDepends.join(",")}]`;
     const safeTitle = sanitizeInlineRoadmapText(slice.title || slice.id) || slice.id;
     const safeRisk = normalizeRiskLevel(slice.risk);
     // ADR-011: sketch slices get a `[sketch]` badge so the roadmap shows at a
@@ -344,12 +434,14 @@ function renderSlicePlanMarkdown(slice: SliceRow, tasks: TaskRow[], gates: GateR
   }
   lines.push("");
 
-  lines.push("## Tasks");
-  lines.push("");
+  // Flat-phase: tasks render as a <tasks> XML block (gsd-core native format)
+  // instead of a ## Tasks markdown section. This makes the plan file compatible
+  // with gsd-core's parseOldPlan which extracts <tasks> blocks.
+  lines.push("<tasks>");
   for (const task of tasks) {
     const done = isClosedStatus(task.status) ? "x" : " ";
-    const estimate = task.estimate.trim() ? ` \`est:${task.estimate.trim()}\`` : "";
-    lines.push(`- [${done}] **${task.id}: ${task.title || task.id}**${estimate}`);
+    const estimate = task.estimate.trim() ? ` _(${task.estimate.trim()})_` : "";
+    lines.push(`- [${done}] **${task.id}**: ${task.title || task.id}${estimate}`);
     const summary = taskSummaryForSlicePlan(task.description);
     if (summary) {
       pushIndented(lines, summary);
@@ -360,8 +452,9 @@ function renderSlicePlanMarkdown(slice: SliceRow, tasks: TaskRow[], gates: GateR
     if (task.verify.trim()) {
       lines.push(`  - Verify: ${task.verify.trim()}`);
     }
-    lines.push("");
   }
+  lines.push("</tasks>");
+  lines.push("");
 
   const filesLikelyTouched = Array.from(new Set(tasks.flatMap((task) => task.files)));
   if (filesLikelyTouched.length > 0) {
@@ -392,14 +485,14 @@ export async function renderPlanFromDb(
     throw new Error(`no tasks found for ${milestoneId}/${sliceId}`);
   }
 
-  const defaultPlanPath = join(
-    gsdProjectionRoot(basePath),
-    "milestones",
-    milestoneId,
-    "slices",
-    sliceId,
-    `${sliceId}-PLAN.md`,
-  );
+  // Layout-aware path: prefer an existing plan file's location so re-renders
+  // stay in place (legacy: milestones/MID/slices/SID/SID-PLAN.md;
+  // flat-phase: phases/NN-slug/NN-MM-PLAN.md).
+  // Pass the milestone title so the fallback flat-phase dir uses the human-readable
+  // slug ("05-milestone-five") rather than the bare ID slug ("05-m005").
+  const milestoneTitle = getMilestone(milestoneId)?.title;
+  const existingPlanPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  const defaultPlanPath = existingPlanPath ?? join(basePath, relSliceFile(basePath, milestoneId, sliceId, "PLAN", milestoneTitle));
   const absPath = outputPath ?? defaultPlanPath;
   mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
@@ -410,13 +503,11 @@ export async function renderPlanFromDb(
     artifact_type: "PLAN",
     milestone_id: milestoneId,
     slice_id: sliceId,
-  });
+  }, basePath);
 
+  // Flat-phase: tasks are checkboxes inside the plan file, not separate files.
+  // No per-task render loop — task state is in the <tasks> block above.
   const taskPlanPaths: string[] = [];
-  for (const task of tasks) {
-    const rendered = await renderTaskPlanFromDb(basePath, milestoneId, sliceId, task.id);
-    taskPlanPaths.push(rendered.taskPlanPath);
-  }
 
   return { planPath: absPath, taskPlanPaths, content };
 }
@@ -432,9 +523,36 @@ export async function renderTaskPlanFromDb(
     throw new Error(`task ${milestoneId}/${sliceId}/${taskId} not found`);
   }
 
-  const tasksDir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
-  mkdirSync(tasksDir, { recursive: true });
-  const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
+  // Flat-phase: task plans live inside the phase dir, not a tasks/ subdir.
+  // This function is legacy — tasks are now checkboxes inside the plan file.
+  const existingPlanPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+  let absPath: string;
+  if (existingPlanPath) {
+    absPath = existingPlanPath;
+  } else {
+    const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+    if (slicePath) {
+      const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId) ?? slicePath;
+      mkdirSync(tasksDir, { recursive: true });
+      absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
+    } else {
+      const existing = resolveMilestonePath(basePath, milestoneId);
+      const legacyBase = legacyMilestonesDir(basePath);
+      const isLegacyLayout = existing
+        ? existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\")
+        : isLegacyMilestonesLayout(basePath);
+      const phaseDir = existing ?? join(
+        isLegacyLayout ? legacyBase : milestonesDir(basePath),
+        isLegacyLayout ? milestoneId : canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
+      );
+      mkdirSync(phaseDir, { recursive: true });
+      const tasksDir = isLegacyLayout
+        ? join(phaseDir, "slices", sliceId, "tasks")
+        : phaseDir;
+      mkdirSync(tasksDir, { recursive: true });
+      absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
+    }
+  }
   const artifactPath = toArtifactPath(absPath, basePath);
   const taskGates = getGateResults(milestoneId, sliceId, "task").filter(g => g.task_id === taskId);
   const content = task.full_plan_md.trim() ? task.full_plan_md : renderTaskPlanMarkdown(task, taskGates);
@@ -444,7 +562,7 @@ export async function renderTaskPlanFromDb(
     milestone_id: milestoneId,
     slice_id: sliceId,
     task_id: taskId,
-  });
+  }, basePath);
 
   return { taskPlanPath: absPath, content };
 }
@@ -452,13 +570,43 @@ export async function renderTaskPlanFromDb(
 export async function renderRoadmapFromDb(
   basePath: string,
   milestoneId: string,
-): Promise<{ roadmapPath: string; content: string }> {
+): Promise<{ roadmapPath: string; content: string } | { skipped: "unplanned-milestone" }> {
   const milestone = getMilestone(milestoneId);
   if (!milestone) {
     throw new Error(`milestone ${milestoneId} not found`);
   }
 
   const slices = getMilestoneSlices(milestoneId);
+
+  // Refuse to render a stub ROADMAP for an unplanned milestone (#852).
+  // A milestone row created by gsd_milestone_generate_id / ensureMilestoneDbRow
+  // starts with title="" / vision="" and zero slices. Rendering that produces a
+  // 38-byte stub (`# M015: M015\n\n**Vision:** \n\n## Slices`) which passes
+  // existsSync but fails the plan-milestone "zero slices" content check —
+  // trapping auto-mode in a finalize-retry loop. A real plan (written by
+  // gsd_plan_milestone via writePlanRows) always sets a non-empty vision AND at
+  // least one slice, so zero-slice + empty-vision is a reliable "never planned"
+  // signal. Skip the write so verification sees a genuinely missing file (a
+  // clear "write the ROADMAP" failure) instead of a misleading stub.
+  if (slices.length === 0 && !milestone.vision.trim()) {
+    logWarning(
+      "projection",
+      `renderRoadmapFromDb skipped unplanned milestone ${milestoneId} (zero slices, empty vision) — refusing to write a stub ROADMAP`,
+    );
+    const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
+    if (existsSync(absPath)) {
+      const artifactPath = toArtifactPath(absPath, basePath);
+      unlinkSync(absPath);
+      try {
+        deleteArtifactByPath(artifactPath);
+      } catch {
+        logWarning("renderer", `failed to remove artifact from DB: ${artifactPath}`);
+      }
+      invalidateCaches();
+    }
+    return { skipped: "unplanned-milestone" };
+  }
+
   const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
   const artifactPath = toArtifactPath(absPath, basePath);
   const content = renderRoadmapMarkdown(milestone, slices);
@@ -466,7 +614,7 @@ export async function renderRoadmapFromDb(
   await writeAndStore(absPath, artifactPath, content, {
     artifact_type: "ROADMAP",
     milestone_id: milestoneId,
-  });
+  }, basePath);
 
   return { roadmapPath: absPath, content };
 }
@@ -496,6 +644,86 @@ export async function renderRoadmapCheckboxes(
   return true;
 }
 
+/**
+ * Project milestone-level artifacts (CONTEXT, RESEARCH, VALIDATION, etc.) from
+ * the artifacts table into the flat-phase phase directory. ROADMAP is skipped
+ * because renderRoadmapFromDb regenerates it from hierarchy rows.
+ */
+export async function renderMilestoneArtifactsFromDb(
+  basePath: string,
+  milestoneId: string,
+): Promise<boolean> {
+  const artifacts = getMilestoneScopedArtifacts(milestoneId);
+  if (artifacts.length === 0) return false;
+
+  const phaseDir = resolveMilestonePath(basePath, milestoneId) ??
+    join(
+      milestonesDir(basePath),
+      canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
+    );
+  mkdirSync(phaseDir, { recursive: true });
+
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+
+  let wrote = false;
+  for (const artifact of artifacts) {
+    if (artifact.artifact_type === "ROADMAP") continue;
+    if (!artifact.full_content.trim()) continue;
+
+    const fileName = isLegacy
+      ? `${milestoneId}-${artifact.artifact_type}.md`
+      : buildMilestoneFileName(milestoneId, artifact.artifact_type);
+    const absPath = join(phaseDir, fileName);
+    const artifactPath = toArtifactPath(absPath, basePath);
+    await writeAndStore(absPath, artifactPath, artifact.full_content, {
+      artifact_type: artifact.artifact_type,
+      milestone_id: milestoneId,
+    });
+    wrote = true;
+  }
+
+  return wrote;
+}
+
+/**
+ * Slice-scoped artifacts (CONTEXT, RESEARCH, CONTINUE, etc.) must survive
+ * layout migration. PLAN is normally regenerated from task rows, but a real
+ * imported PLAN can still be replayed as a fallback; known recovery stubs are
+ * treated as missing.
+ */
+export async function renderSliceArtifactsFromDb(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+): Promise<boolean> {
+  const artifacts = getSliceScopedArtifacts(milestoneId, sliceId);
+  if (artifacts.length === 0) return false;
+
+  let wrote = false;
+  for (const artifact of artifacts) {
+    const artifactType = artifact.artifact_type.toUpperCase();
+    if (!artifact.full_content.trim()) continue;
+    if (artifactType === "PLAN" && isAutoRecoveryPlaceholderPlan(artifact.full_content)) continue;
+
+    const absPath = join(basePath, relSliceFile(basePath, milestoneId, sliceId, artifactType));
+    mkdirSync(dirname(absPath), { recursive: true });
+    const artifactPath = toArtifactPath(absPath, basePath);
+    await writeAndStore(absPath, artifactPath, artifact.full_content, {
+      artifact_type: artifactType,
+      milestone_id: milestoneId,
+      slice_id: sliceId,
+    }, basePath);
+    wrote = true;
+  }
+
+  return wrote;
+}
+
+function isAutoRecoveryPlaceholderPlan(content: string): boolean {
+  return /(?:^|\n)\s*#\s*BLOCKER\b/i.test(content) && /auto-mode recovery failed/i.test(content);
+}
+
 // ─── Plan Checkbox Rendering ──────────────────────────────────────────────
 
 /**
@@ -510,7 +738,8 @@ export async function renderRoadmapCheckboxes(
  * projection (the 4S/0T-vs-5S/13T drift class). The artifacts table is an
  * output sink, never a render input.
  *
- * @returns true if the plan was written, false on skip/error
+ * @returns true if the plan was written, false when the DB slice has no tasks
+ * @throws when the DB connection is unavailable or the render write fails
  */
 export async function renderPlanCheckboxes(
   basePath: string,
@@ -520,6 +749,9 @@ export async function renderPlanCheckboxes(
 ): Promise<boolean> {
   const tasks = getSliceTasks(milestoneId, sliceId);
   if (tasks.length === 0) {
+    if (!isDbAvailable()) {
+      throw new Error(`database unavailable while rendering plan checkboxes for ${milestoneId}/${sliceId}`);
+    }
     process.stderr.write(
       `markdown-renderer: no tasks found for ${milestoneId}/${sliceId}\n`,
     );
@@ -558,7 +790,9 @@ export async function renderTaskSummary(
     return false;
   }
 
-  const tasksDir = join(slicePath, "tasks");
+  // Use the tasks/ subdir when it exists (legacy layout), otherwise use the
+  // slice path directly (flat-phase: task summaries live alongside plan files).
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId) ?? slicePath;
   const fileName = buildTaskFileName(taskId, "SUMMARY");
   const absPath = join(tasksDir, fileName);
   const artifactPath = toArtifactPath(absPath, basePath);
@@ -568,7 +802,7 @@ export async function renderTaskSummary(
     milestone_id: milestoneId,
     slice_id: sliceId,
     task_id: taskId,
-  });
+  }, basePath);
 
   return true;
 }
@@ -591,19 +825,21 @@ export async function renderSliceSummary(
     return false; // No slice data — skip silently
   }
 
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+  // Flat-phase: resolve or create the phase dir, since resolveSlicePath only
+  // finds existing dirs. In flat-phase the slice "path" is the phase dir.
+  let slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
   if (!slicePath) {
-    process.stderr.write(
-      `markdown-renderer: cannot resolve slice path for ${milestoneId}/${sliceId}\n`,
-    );
-    return false;
+    const mDir = milestonesDir(basePath);
+    const dirName = canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title);
+    slicePath = join(mDir, dirName);
+    mkdirSync(slicePath, { recursive: true });
   }
 
   let wrote = false;
 
-  // Write SUMMARY
+  // Write SUMMARY — flat-phase: NN-MM-SUMMARY.md inside phase dir
   if (slice.full_summary_md) {
-    const summaryName = buildSliceFileName(sliceId, "SUMMARY");
+    const summaryName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "SUMMARY");
     const summaryAbs = join(slicePath, summaryName);
     const summaryArtifact = toArtifactPath(summaryAbs, basePath);
 
@@ -611,13 +847,13 @@ export async function renderSliceSummary(
       artifact_type: "SUMMARY",
       milestone_id: milestoneId,
       slice_id: sliceId,
-    });
+    }, basePath);
     wrote = true;
   }
 
-  // Write UAT
+  // Write UAT — flat-phase: NN-MM-UAT.md inside phase dir
   if (slice.full_uat_md) {
-    const uatName = buildSliceFileName(sliceId, "UAT");
+    const uatName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "UAT");
     const uatAbs = join(slicePath, uatName);
     const uatArtifact = toArtifactPath(uatAbs, basePath);
 
@@ -625,7 +861,7 @@ export async function renderSliceSummary(
       artifact_type: "UAT",
       milestone_id: milestoneId,
       slice_id: sliceId,
-    });
+    }, basePath);
     wrote = true;
   }
 
@@ -658,9 +894,29 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
       result.errors.push(`roadmap ${milestone.id}: ${(err as Error).message}`);
     }
 
+    try {
+      const ok = await renderMilestoneArtifactsFromDb(basePath, milestone.id);
+      if (ok) result.rendered++;
+      else result.skipped++;
+    } catch (err) {
+      result.errors.push(`milestone artifacts ${milestone.id}: ${(err as Error).message}`);
+    }
+
     // Iterate slices
     const slices = getMilestoneSlices(milestone.id);
     for (const slice of slices) {
+      // Preserve slice-scoped artifacts imported from disk, including real PLAN
+      // fallback content when task rows cannot regenerate it.
+      try {
+        const ok = await renderSliceArtifactsFromDb(basePath, milestone.id, slice.id);
+        if (ok) result.rendered++;
+        else result.skipped++;
+      } catch (err) {
+        result.errors.push(
+          `slice artifacts ${milestone.id}/${slice.id}: ${(err as Error).message}`,
+        );
+      }
+
       // Render plan checkboxes
       try {
         const ok = await renderPlanCheckboxes(basePath, milestone.id, slice.id);
@@ -716,6 +972,25 @@ export async function renderAllFromDb(basePath: string): Promise<RenderAllResult
     result.errors.push(`decisions: ${(err as Error).message}`);
   }
 
+  // Project to .planning/ if the compat marker says it's active. Dynamic
+  // import for writePlanningDirectory avoids a static-import cycle. Gated on
+  // planning.active so the double-write cost only hits projects that use
+  // .planning/. writePlanningDirectory records per-file SHAs via
+  // applyPlanningProjectionWrites so the reconcile detector has a baseline.
+  // capturePlanningCompatIfNeeded seeds the layout and SHAs on first encounter.
+  try {
+    const { capturePlanningCompatIfNeeded } = await import("./compat/planning-compat.js");
+    await capturePlanningCompatIfNeeded(basePath);
+    const marker = readCompatMarker(basePath);
+    if (marker.planning?.active && marker.planning.layout) {
+      const { writePlanningDirectory } = await import("./migrate/planning-writer.js");
+      await writePlanningDirectory(basePath, marker.planning.layout);
+      result.rendered++;
+    }
+  } catch (err) {
+    result.errors.push(`planning projection: ${(err as Error).message}`);
+  }
+
   return result;
 }
 
@@ -732,7 +1007,7 @@ export interface StaleEntry {
  * Checks:
  * 1. Roadmap checkbox states vs DB slice statuses
  * 2. Plan checkbox states vs DB task statuses
- * 3. Missing SUMMARY.md files for complete tasks with full_summary_md
+ * 3. Missing SUMMARY.md files for complete tasks with full_summary_md (legacy only)
  * 4. Missing SUMMARY.md/UAT.md files for complete slices with content
  *
  * Returns a list of stale entries with file path and reason.
@@ -768,7 +1043,18 @@ function parseProjectionByIdentity(path: string, parse: (content: string) => unk
 }
 
 export function detectStaleRenders(basePath: string): StaleEntry[] {
-  // parseRoadmap/parsePlan are statically imported (#442 Phase 1.4): the
+  // TODO(flat-phase): stale-render detection is temporarily fully disabled.
+  // The isLegacyMilestonesLayout gate is unreliable: git-service.ts creates
+  // milestones/<mid>/ directories for integration-branch metadata even in
+  // flat-phase projects, making the gate fire true and then producing false
+  // stale-render drift in the second reconcile cycle → ReconciliationFailedError
+  // → auto-mode blocked (exit 10) for multi-slice/remediation e2e scenarios.
+  // Re-enable after path construction is unified and the metadata dir is
+  // decoupled from the layout-detection signal.
+  return [];
+}
+
+function detectStaleRendersImpl(basePath: string): StaleEntry[] {
   // per-call createRequire("./parsers-legacy") that used to live here ran on
   // every dispatch. The static `./parsers-legacy.js` specifier resolves in
   // both packaged (.js) and source (.ts via the strip-types loader) contexts —
@@ -778,8 +1064,12 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
 
   for (const milestone of milestones) {
     const slices = getMilestoneSlices(milestone.id);
+    const isFlatPhase = isMilestoneFlatPhaseLayout(basePath, milestone.id);
 
     // ── Check roadmap checkbox state ──────────────────────────────────
+    // TODO(flat-phase): roadmap checkbox parsing may not match flat-phase
+    // roadmap format, causing false-positive drift loops. Skip during transition.
+    /*
     const roadmapPath = resolveRoadmapProjectionPath(basePath, milestone.id);
     if (existsSync(roadmapPath)) {
       try {
@@ -790,12 +1080,12 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
           const roadmapSlice = parsed.slices.find((s: { id: string }) => s.id === slice.id);
           if (!roadmapSlice) continue;
 
-          if (isCompleteInDb && !roadmapSlice.done) {
+          if (isCompleteInDb && !roadmapSlice!.done) {
             stale.push({
               path: roadmapPath,
               reason: `${slice.id} is closed in DB but unchecked in roadmap`,
             });
-          } else if (!isCompleteInDb && roadmapSlice.done) {
+          } else if (!isCompleteInDb && roadmapSlice!.done) {
             stale.push({
               path: roadmapPath,
               reason: `${slice.id} is not closed in DB but checked in roadmap`,
@@ -806,62 +1096,67 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
         logWarning("renderer", `roadmap parse failed: ${(e as Error).message}`);
       }
     }
+    */
 
     // ── Check plan checkbox state and summaries for each slice ────────
     for (const slice of slices) {
       const tasks = getSliceTasks(milestone.id, slice.id);
 
-      // Check plan checkboxes
-      const planPath = resolveSliceFile(basePath, milestone.id, slice.id, "PLAN");
-      if (planPath && existsSync(planPath)) {
-        try {
-          const parsed = parseProjectionByIdentity(planPath, parsePlan) as ReturnType<typeof parsePlan>;
-
-          for (const task of tasks) {
-            const isDoneInDb = isClosedStatus(task.status);
-            const planTask = parsed.tasks.find((t: { id: string }) => t.id === task.id);
-            if (!planTask) {
-              // DB has a task the plan markdown lacks: the projection is
-              // lossy (e.g. tasks added after the PLAN artifact was first
-              // written). Flag it so the plan is re-rendered from DB rows.
-              stale.push({
-                path: planPath,
-                reason: `${task.id} exists in DB but is missing in plan`,
-              });
-              continue;
-            }
-
-            if (isDoneInDb && !planTask.done) {
-              stale.push({
-                path: planPath,
-                reason: `${task.id} is done in DB but unchecked in plan`,
-              });
-            } else if (!isDoneInDb && planTask.done) {
-              stale.push({
-                path: planPath,
-                reason: `${task.id} is not done in DB but checked in plan`,
-              });
+      if (!isFlatPhase) {
+        // Check plan checkboxes
+        const planPath = resolveSliceFile(basePath, milestone.id, slice.id, "PLAN");
+        if (planPath && existsSync(planPath!)) {
+          try {
+            const parsed = parseProjectionByIdentity(planPath!, parsePlan) as ReturnType<typeof parsePlan>;
+
+            for (const task of tasks) {
+              const isDoneInDb = isClosedStatus(task.status);
+              const planTask = parsed.tasks.find((t: { id: string }) => t.id === task.id);
+              if (!planTask) {
+                // DB has a task the plan markdown lacks: the projection is
+                // lossy (e.g. tasks added after the PLAN artifact was first
+                // written). Flag it so the plan is re-rendered from DB rows.
+                stale.push({
+                  path: planPath!,
+                  reason: `${task.id} exists in DB but is missing in plan`,
+                });
+                continue;
+              }
+
+              if (isDoneInDb && !planTask!.done) {
+                stale.push({
+                  path: planPath!,
+                  reason: `${task.id} is done in DB but unchecked in plan`,
+                });
+              } else if (!isDoneInDb && planTask!.done) {
+                stale.push({
+                  path: planPath!,
+                  reason: `${task.id} is not done in DB but checked in plan`,
+                });
+              }
             }
+          } catch (e) {
+            logWarning("renderer", `plan parse failed: ${(e as Error).message}`);
           }
-        } catch (e) {
-          logWarning("renderer", `plan parse failed: ${(e as Error).message}`);
         }
       }
 
-      // Check missing task summary files
-      for (const task of tasks) {
-        if (isClosedStatus(task.status) && task.full_summary_md) {
-          const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
-          if (slicePath) {
-            const tasksDir = join(slicePath, "tasks");
-            const fileName = buildTaskFileName(task.id, "SUMMARY");
-            const summaryAbsPath = join(tasksDir, fileName);
-
-            if (!existsSync(summaryAbsPath)) {
-              stale.push({
-                path: summaryAbsPath,
-                reason: `${task.id} is complete with summary in DB but SUMMARY.md missing on disk`,
-              });
+      // Check missing task summary files (legacy layout only — flat-phase keeps
+      // task state in plan <tasks> blocks and does not project Txx-SUMMARY.md)
+      if (!isFlatPhase) {
+        for (const task of tasks) {
+          if (isClosedStatus(task.status) && task.full_summary_md) {
+            const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
+            if (slicePath) {
+              const fileName = buildTaskFileName(task.id, "SUMMARY");
+              const summaryAbsPath = join(slicePath, fileName);
+
+              if (!existsSync(summaryAbsPath)) {
+                stale.push({
+                  path: summaryAbsPath,
+                  reason: `${task.id} is complete with summary in DB but SUMMARY.md missing on disk`,
+                });
+              }
             }
           }
         }
@@ -870,10 +1165,15 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
       // Check missing slice summary/UAT files
       const sliceRow = getSlice(milestone.id, slice.id);
       if (sliceRow && sliceRow.status === "complete") {
+        // Use the SAME path construction as renderSliceSummary (planFileName format)
+        // so the detector and repair always agree on the file location.
         const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
         if (slicePath) {
+          const phaseNum = milestoneIdToPhaseNum(milestone.id);
+          const planNum = sliceIdToPlanNum(slice.id);
+
           if (sliceRow.full_summary_md) {
-            const summaryName = buildSliceFileName(slice.id, "SUMMARY");
+            const summaryName = planFileName(phaseNum, planNum, "SUMMARY");
             const summaryAbsPath = join(slicePath, summaryName);
             if (!existsSync(summaryAbsPath)) {
               stale.push({
@@ -884,7 +1184,7 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
           }
 
           if (sliceRow.full_uat_md) {
-            const uatName = buildSliceFileName(slice.id, "UAT");
+            const uatName = planFileName(phaseNum, planNum, "UAT");
             const uatAbsPath = join(slicePath, uatName);
             if (!existsSync(uatAbsPath)) {
               stale.push({
@@ -910,6 +1210,17 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
   return stale;
 }
 
+/**
+ * Render-verification helper: does the rendered ROADMAP markdown mark a slice
+ * as done? Used by completion code to verify/repair the *projection* after a
+ * DB write — never as a source of truth for dispatch or completion decisions
+ * (ADR-017). Lives here so decision-path modules need not import
+ * parsers-legacy directly.
+ */
+export function roadmapRenderMarksSliceDone(roadmapContent: string, sliceId: string): boolean {
+  return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
+}
+
 // ─── Stale Repair ─────────────────────────────────────────────────────────
 // Body relocated to state-reconciliation/drift/stale-render.ts (ADR-017 #5702).
 // detectStaleRenders above stays as a useful diagnostic primitive; the
@@ -936,9 +1247,12 @@ export async function renderReplanFromDb(
   sliceId: string,
   replanData: ReplanData,
 ): Promise<{ replanPath: string; content: string }> {
+  // Flat-phase: replan file lives in the phase dir
   const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  const absPath = join(slicePath, `${sliceId}-REPLAN.md`);
+    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const planNum = sliceIdToPlanNum(sliceId);
+  const absPath = join(slicePath, planFileName(phaseNum, planNum, "REPLAN"));
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];
@@ -964,7 +1278,7 @@ export async function renderReplanFromDb(
     artifact_type: "REPLAN",
     milestone_id: milestoneId,
     slice_id: sliceId,
-  });
+  }, basePath);
 
   return { replanPath: absPath, content };
 }
@@ -975,9 +1289,12 @@ export async function renderAssessmentFromDb(
   sliceId: string,
   assessmentData: AssessmentData,
 ): Promise<{ assessmentPath: string; content: string }> {
+  // Flat-phase: assessment file lives in the phase dir
   const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(gsdRoot(basePath), "milestones", milestoneId, "slices", sliceId);
-  const absPath = join(slicePath, `${sliceId}-ASSESSMENT.md`);
+    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const planNum = sliceIdToPlanNum(sliceId);
+  const absPath = join(slicePath, planFileName(phaseNum, planNum, "ASSESSMENT"));
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];
@@ -1002,7 +1319,7 @@ export async function renderAssessmentFromDb(
     artifact_type: "ASSESSMENT",
     milestone_id: milestoneId,
     slice_id: sliceId,
-  });
+  }, basePath);
 
   return { assessmentPath: absPath, content };
 }