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

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -8,16 +8,63 @@
 //
 // 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, getMilestoneSlices, getSliceTasks, getTask, getSlice, insertArtifact, getGateResults, } from "./gsd-db.js";
-import { resolveDir, resolveFile, resolveSliceFile, resolveSlicePath, gsdProjectionRoot, gsdRoot, buildMilestoneFileName, buildTaskFileName, buildSliceFileName, } from "./paths.js";
+import { getAllMilestones, getMilestone, getMilestoneScopedArtifacts, getSliceScopedArtifacts, getMilestoneSlices, getSliceTasks, getTask, getSlice, insertArtifact, deleteArtifactByPath, getGateResults, isDbAvailable, } from "./gsd-db.js";
+import { resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, gsdProjectionRoot, gsdRoot, buildMilestoneFileName, buildTaskFileName, } from "./paths.js";
 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 { planFileName, milestoneIdToPhaseNum, sliceIdToPlanNum, } 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 = [];
+function recordProjectionWrite(basePath, projectionPath, entities) {
+    _pendingProjectionWrites.push({ basePath, projectionPath, entities });
+}
+function flushProjectionWritesToMarker() {
+    if (_pendingProjectionWrites.length === 0)
+        return;
+    // Group by basePath (defensive — multiple projects are unusual but possible).
+    const byBase = new Map();
+    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.message}`);
+        }
+    }
+}
 // ─── Helpers ──────────────────────────────────────────────────────────────
 /**
  * Convert an absolute file path to a .gsd-relative artifact path.
@@ -37,6 +84,7 @@ function toArtifactPath(absPath, basePath) {
  * Invalidate all caches after a disk write.
  */
 function invalidateCaches() {
+    flushProjectionWritesToMarker();
     invalidateStateCache();
     clearPathCache();
     clearParseCache();
@@ -60,7 +108,9 @@ function taskSummaryForSlicePlan(description) {
     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;
 }
@@ -79,17 +129,29 @@ function sanitizeInlineRoadmapText(value) {
         .trim();
 }
 function resolveRoadmapProjectionPath(basePath, milestoneId) {
-    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, milestoneId) {
+    const existing = resolveMilestonePath(basePath, milestoneId);
+    const legacyBase = legacyMilestonesDir(basePath);
+    return existing
+        ? !(existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\"))
+        : !isLegacyMilestonesLayout(basePath);
 }
 /**
  * Write rendered content to disk and update the artifacts table.
  */
-async function writeAndStore(absPath, artifactPath, content, opts) {
+async function writeAndStore(absPath, artifactPath, content, opts, basePath) {
     await saveFile(absPath, content);
     try {
         insertArtifact({
@@ -105,6 +167,19 @@ async function writeAndStore(absPath, artifactPath, content, opts) {
         // Non-fatal: file is on disk, DB is best-effort
         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 = [];
+        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();
 }
 function renderRoadmapMarkdown(milestone, slices) {
@@ -125,7 +200,8 @@ function renderRoadmapMarkdown(milestone, slices) {
     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
@@ -283,12 +359,14 @@ function renderSlicePlanMarkdown(slice, tasks, gates = []) {
         lines.push("- Run the task and slice verification checks for this slice.");
     }
     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);
@@ -299,8 +377,9 @@ function renderSlicePlanMarkdown(slice, tasks, gates = []) {
         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) {
         lines.push("## Files Likely Touched");
@@ -321,7 +400,14 @@ export async function renderPlanFromDb(basePath, milestoneId, sliceId, outputPat
     if (tasks.length === 0) {
         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);
@@ -331,12 +417,10 @@ export async function renderPlanFromDb(basePath, milestoneId, sliceId, outputPat
         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 = [];
-    for (const task of tasks) {
-        const rendered = await renderTaskPlanFromDb(basePath, milestoneId, sliceId, task.id);
-        taskPlanPaths.push(rendered.taskPlanPath);
-    }
     return { planPath: absPath, taskPlanPaths, content };
 }
 export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskId) {
@@ -344,9 +428,35 @@ export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskI
     if (!task) {
         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;
+    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);
@@ -355,7 +465,7 @@ export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskI
         milestone_id: milestoneId,
         slice_id: sliceId,
         task_id: taskId,
-    });
+    }, basePath);
     return { taskPlanPath: absPath, content };
 }
 export async function renderRoadmapFromDb(basePath, milestoneId) {
@@ -364,13 +474,39 @@ export async function renderRoadmapFromDb(basePath, milestoneId) {
         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);
     await writeAndStore(absPath, artifactPath, content, {
         artifact_type: "ROADMAP",
         milestone_id: milestoneId,
-    });
+    }, basePath);
     return { roadmapPath: absPath, content };
 }
 // ─── Roadmap Checkbox Rendering ───────────────────────────────────────────
@@ -390,6 +526,71 @@ export async function renderRoadmapCheckboxes(basePath, milestoneId) {
     await renderRoadmapFromDb(basePath, milestoneId);
     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, milestoneId) {
+    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, milestoneId, sliceId) {
+    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) {
+    return /(?:^|\n)\s*#\s*BLOCKER\b/i.test(content) && /auto-mode recovery failed/i.test(content);
+}
 // ─── Plan Checkbox Rendering ──────────────────────────────────────────────
 /**
  * Render plan checkbox states from DB.
@@ -403,11 +604,15 @@ export async function renderRoadmapCheckboxes(basePath, milestoneId) {
  * 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, milestoneId, sliceId, outputPath) {
     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`);
         return false;
     }
@@ -432,7 +637,9 @@ export async function renderTaskSummary(basePath, milestoneId, sliceId, taskId)
         process.stderr.write(`markdown-renderer: cannot resolve slice path for ${milestoneId}/${sliceId}\n`);
         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);
@@ -441,7 +648,7 @@ export async function renderTaskSummary(basePath, milestoneId, sliceId, taskId)
         milestone_id: milestoneId,
         slice_id: sliceId,
         task_id: taskId,
-    });
+    }, basePath);
     return true;
 }
 // ─── Slice Summary Rendering ──────────────────────────────────────────────
@@ -456,34 +663,38 @@ export async function renderSliceSummary(basePath, milestoneId, sliceId) {
     if (!slice) {
         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);
         await writeAndStore(summaryAbs, summaryArtifact, slice.full_summary_md, {
             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);
         await writeAndStore(uatAbs, uatArtifact, slice.full_uat_md, {
             artifact_type: "UAT",
             milestone_id: milestoneId,
             slice_id: sliceId,
-        });
+        }, basePath);
         wrote = true;
     }
     return wrote;
@@ -507,9 +718,31 @@ export async function renderAllFromDb(basePath) {
         catch (err) {
             result.errors.push(`roadmap ${milestone.id}: ${err.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.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.message}`);
+            }
             // Render plan checkboxes
             try {
                 const ok = await renderPlanCheckboxes(basePath, milestone.id, slice.id);
@@ -560,6 +793,25 @@ export async function renderAllFromDb(basePath) {
     catch (err) {
         result.errors.push(`decisions: ${err.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.message}`);
+    }
     return result;
 }
 const _projectionParseCache = new Map();
@@ -586,7 +838,17 @@ function parseProjectionByIdentity(path, parse) {
     return parse(readFileSync(path, "utf-8"));
 }
 export function detectStaleRenders(basePath) {
-    // 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) {
     // 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 —
@@ -595,86 +857,94 @@ export function detectStaleRenders(basePath) {
     const milestones = getAllMilestones();
     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 {
-                const parsed = parseProjectionByIdentity(roadmapPath, parseRoadmap);
-                for (const slice of slices) {
-                    const isCompleteInDb = isClosedStatus(slice.status);
-                    const roadmapSlice = parsed.slices.find((s) => s.id === slice.id);
-                    if (!roadmapSlice)
-                        continue;
-                    if (isCompleteInDb && !roadmapSlice.done) {
-                        stale.push({
-                            path: roadmapPath,
-                            reason: `${slice.id} is closed in DB but unchecked in roadmap`,
-                        });
-                    }
-                    else if (!isCompleteInDb && roadmapSlice.done) {
-                        stale.push({
-                            path: roadmapPath,
-                            reason: `${slice.id} is not closed in DB but checked in roadmap`,
-                        });
-                    }
-                }
-            }
-            catch (e) {
-                logWarning("renderer", `roadmap parse failed: ${e.message}`);
+          try {
+            const parsed = parseProjectionByIdentity(roadmapPath, parseRoadmap) as ReturnType<typeof parseRoadmap>;
+    
+            for (const slice of slices) {
+              const isCompleteInDb = isClosedStatus(slice.status);
+              const roadmapSlice = parsed.slices.find((s: { id: string }) => s.id === slice.id);
+              if (!roadmapSlice) continue;
+    
+              if (isCompleteInDb && !roadmapSlice!.done) {
+                stale.push({
+                  path: roadmapPath,
+                  reason: `${slice.id} is closed in DB but unchecked in roadmap`,
+                });
+              } else if (!isCompleteInDb && roadmapSlice!.done) {
+                stale.push({
+                  path: roadmapPath,
+                  reason: `${slice.id} is not closed in DB but checked in roadmap`,
+                });
+              }
             }
+          } catch (e) {
+            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);
-                    for (const task of tasks) {
-                        const isDoneInDb = isClosedStatus(task.status);
-                        const planTask = parsed.tasks.find((t) => 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);
+                        for (const task of tasks) {
+                            const isDoneInDb = isClosedStatus(task.status);
+                            const planTask = parsed.tasks.find((t) => 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.message}`);
+                    catch (e) {
+                        logWarning("renderer", `plan parse failed: ${e.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`,
+                                });
+                            }
                         }
                     }
                 }
@@ -682,10 +952,14 @@ export function detectStaleRenders(basePath) {
             // 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({
@@ -695,7 +969,7 @@ export function detectStaleRenders(basePath) {
                         }
                     }
                     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({
@@ -716,10 +990,23 @@ export function detectStaleRenders(basePath) {
     }
     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, sliceId) {
+    return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
+}
 export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanData) {
+    // 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 = [];
     lines.push(`# ${sliceId} Replan`);
@@ -742,13 +1029,16 @@ export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanD
         artifact_type: "REPLAN",
         milestone_id: milestoneId,
         slice_id: sliceId,
-    });
+    }, basePath);
     return { replanPath: absPath, content };
 }
 export async function renderAssessmentFromDb(basePath, milestoneId, sliceId, assessmentData) {
+    // 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 = [];
     lines.push(`# ${sliceId} Assessment`);
@@ -770,6 +1060,6 @@ export async function renderAssessmentFromDb(basePath, milestoneId, sliceId, ass
         artifact_type: "ASSESSMENT",
         milestone_id: milestoneId,
         slice_id: sliceId,
-    });
+    }, basePath);
     return { assessmentPath: absPath, content };
 }