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

package/dist/resources/extensions/gsd/state-reconciliation/drift/external-markdown-edit.js

@@ -0,0 +1,82 @@
+// Project/App: gsd-pi
+// File Purpose: ADR-017 drift handler for external (gsd-core) markdown edits.
+//
+// gsd-pi's DB is canonical, but .gsd/*.md is the inter-tool contract. When
+// gsd-core edits a projection file, this handler detects the sha drift vs the
+// recorded baseline in .gsd/.compat.json and re-imports the affected entities
+// into the DB. The next renderAllFromDb pass re-projects; the write-time
+// invalidation hook then refreshes the marker entry, closing the loop.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { computeProjectionSha, readCompatMarker, writeCompatMarker, } from "../../compat/compat-marker.js";
+import { logWarning } from "../../workflow-logger.js";
+/**
+ * Detect sha drift between the marker baseline and current file contents.
+ *
+ * - Missing marker → no records (the broader /gsd recover flow handles a
+ *   cold-start; this handler only fires when we have a baseline to compare).
+ * - Missing file on disk → no record (other handlers cover missing artifacts).
+ * - Sha match → no record (gsd-pi's own write or no change).
+ * - Sha mismatch → one record per drifted file, scoped to its recorded entities.
+ */
+function detectExternalMarkdownEdit(_state, ctx) {
+    const marker = readCompatMarker(ctx.basePath);
+    const entries = Object.entries(marker.projections);
+    if (entries.length === 0)
+        return [];
+    const records = [];
+    for (const [projectionPath, entry] of entries) {
+        const abs = join(ctx.basePath, ".gsd", projectionPath);
+        if (!existsSync(abs))
+            continue;
+        const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+        if (actual === entry.sha)
+            continue;
+        records.push({
+            kind: "external-markdown-edit",
+            projectionPath,
+            expectedSha: entry.sha,
+            actualSha: actual,
+            entities: entry.entities,
+        });
+    }
+    return records;
+}
+/**
+ * Idempotent repair: re-import hierarchy for the affected entities from
+ * markdown into the DB, then update the marker entry so the next detect pass
+ * sees the file as expected. migrateHierarchyToDb is itself idempotent
+ * (upsert), so re-running this repair after a successful one is a no-op.
+ */
+async function repairExternalMarkdownEdit(record, ctx) {
+    try {
+        // Dynamic imports break a module-init cycle: this handler ← registry ←
+        // state.ts ← guided-flow.ts ← md-importer.ts ← (this handler's old static
+        // import). Deferring to repair time keeps module load cycle-free.
+        const { migrateHierarchyToDb } = await import("../../md-importer.js");
+        const { invalidateStateCache } = await import("../../state.js");
+        // Scoped re-import. migrateHierarchyToDb walks the whole tree but is a
+        // cheap upsert; per-entity scoping would require decomposing it, which is
+        // out of scope for v1. The cost is bounded by tree size and runs at most
+        // once per reconcile pass (MAX_PASSES=2).
+        migrateHierarchyToDb(ctx.basePath);
+        invalidateStateCache();
+    }
+    catch (err) {
+        logWarning("reconcile", `external-markdown-edit repair failed for ${record.projectionPath}: ${err.message}`);
+        throw err;
+    }
+    // Refresh the marker so a second pass (cap=2 reconcile) doesn't re-fire.
+    const marker = readCompatMarker(ctx.basePath);
+    marker.projections[record.projectionPath] = {
+        sha: record.actualSha,
+        entities: record.entities,
+    };
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(ctx.basePath, marker);
+}
+export const externalMarkdownEditHandler = {
+    kind: "external-markdown-edit",
+    detect: detectExternalMarkdownEdit,
+    repair: repairExternalMarkdownEdit,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/external-planning-edit.js

@@ -0,0 +1,142 @@
+// Project/App: gsd-pi
+// File Purpose: ADR-017 drift handler for external (gsd-core) edits to .planning/.
+// Parallel to external-markdown-edit.ts. Detects sha drift between the compat
+// marker's planning.projections/passthrough and current .planning/ files.
+//
+// Modeled files (projections): re-imported via parsePlanningDirectory → DB.
+// Passthrough files (un-modeled docs): sha refreshed, content untouched.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { computeProjectionSha, readCompatMarker, writeCompatMarker, } from "../../compat/compat-marker.js";
+import { isPlanningPassthroughRelPath, walkPlanningRelPaths, } from "../../compat/planning-compat.js";
+import { logWarning } from "../../workflow-logger.js";
+function detectOne(ctx, entries, passthrough) {
+    const records = [];
+    for (const [projectionPath, entry] of Object.entries(entries)) {
+        const abs = join(ctx.basePath, ".planning", projectionPath);
+        if (!existsSync(abs))
+            continue; // missing-file drift is covered by other handlers
+        const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+        if (actual === entry.sha)
+            continue;
+        records.push({
+            kind: "external-planning-edit",
+            projectionPath,
+            expectedSha: entry.sha,
+            actualSha: actual,
+            entities: entry.entities,
+            passthrough,
+        });
+    }
+    return records;
+}
+function detectUnseededPlanningFiles(ctx, projections, passthrough) {
+    const planningDir = join(ctx.basePath, ".planning");
+    if (!existsSync(planningDir))
+        return [];
+    const records = [];
+    for (const relPath of walkPlanningRelPaths(planningDir)) {
+        const isPassthrough = isPlanningPassthroughRelPath(relPath);
+        const map = isPassthrough ? passthrough : projections;
+        if (map[relPath])
+            continue;
+        const abs = join(planningDir, relPath);
+        const actual = computeProjectionSha(readFileSync(abs, "utf-8"));
+        records.push({
+            kind: "external-planning-edit",
+            projectionPath: relPath,
+            expectedSha: "",
+            actualSha: actual,
+            entities: [],
+            passthrough: isPassthrough,
+        });
+    }
+    return records;
+}
+async function detectExternalPlanningEdit(_state, ctx) {
+    const marker = readCompatMarker(ctx.basePath);
+    if (!marker.planning?.active) {
+        // Not yet activated. Activation (layout parse + DB import) is owned by
+        // capturePlanningCompatIfNeeded, called from reconcileBeforeDispatch when
+        // !dryRun. detect() must never write the marker — it is called in both
+        // dry-run and non-dry-run contexts. In dry-run, preview unseeded files
+        // without persisting activation.
+        if (!ctx.dryRun)
+            return [];
+        const planningDir = join(ctx.basePath, ".planning");
+        if (!existsSync(planningDir))
+            return [];
+        try {
+            const { parsePlanningDirectory } = await import("../../migrate/parser.js");
+            const { detectPlanningLayout } = await import("../../migrate/layout-detect.js");
+            const parsed = await parsePlanningDirectory(planningDir);
+            const layout = detectPlanningLayout(parsed);
+            if (!layout)
+                return [];
+            return detectUnseededPlanningFiles(ctx, {}, {});
+        }
+        catch (e) {
+            logWarning("reconcile", `planning layout auto-detection failed: ${e.message}`);
+        }
+        return [];
+    }
+    const projections = marker.planning.projections;
+    const passthrough = marker.planning.passthrough;
+    const hasBaselines = Object.keys(projections).length > 0 || Object.keys(passthrough).length > 0;
+    return [
+        ...detectOne(ctx, projections, false),
+        ...detectOne(ctx, passthrough, true),
+        // No baseline yet (post-capture, pre-writePlanningDirectory): skip unseeded
+        // detection so every on-disk file is not treated as drift in the same pass.
+        ...(hasBaselines ? detectUnseededPlanningFiles(ctx, projections, passthrough) : []),
+    ];
+}
+async function repairExternalPlanningEdit(record, ctx) {
+    // Passthrough: never re-import (no DB model). Just refresh the sha.
+    if (record.passthrough) {
+        const marker = readCompatMarker(ctx.basePath);
+        marker.planning.passthrough[record.projectionPath] = {
+            sha: record.actualSha,
+            entities: record.entities,
+        };
+        marker.lastProjectedAt = new Date().toISOString();
+        writeCompatMarker(ctx.basePath, marker);
+        return;
+    }
+    // Modeled: re-import via the migrate read path. Dynamic imports break the
+    // module-init cycle (this handler ← registry ← state.ts ← guided-flow.ts
+    // ← md-importer.ts). parsePlanningDirectory reads .planning/; always
+    // transform + writeGSDDirectory so .gsd/ reflects the edited .planning/ file
+    // before migrateHierarchyToDb ingests it. In coexistence, .planning/ is the
+    // gsd-core native format and takes precedence: writing .gsd/ here propagates
+    // the edit that must survive future projections. external-markdown-edit (index
+    // 0) runs before this handler, so .gsd/-only drift is already imported first.
+    try {
+        const { parsePlanningDirectory } = await import("../../migrate/parser.js");
+        const { transformToGSD } = await import("../../migrate/transformer.js");
+        const { writeGSDDirectory } = await import("../../migrate/writer.js");
+        const { migrateHierarchyToDb } = await import("../../md-importer.js");
+        const { invalidateStateCache } = await import("../../state.js");
+        const parsed = await parsePlanningDirectory(join(ctx.basePath, ".planning"));
+        const gsdProject = transformToGSD(parsed);
+        await writeGSDDirectory(gsdProject, ctx.basePath);
+        migrateHierarchyToDb(ctx.basePath);
+        invalidateStateCache();
+    }
+    catch (err) {
+        logWarning("reconcile", `external-planning-edit repair failed for ${record.projectionPath}: ${err.message}`);
+        throw err;
+    }
+    const marker = readCompatMarker(ctx.basePath);
+    marker.planning.projections[record.projectionPath] = {
+        sha: record.actualSha,
+        entities: record.entities,
+    };
+    marker.lastProjectedAt = new Date().toISOString();
+    writeCompatMarker(ctx.basePath, marker);
+}
+export const externalPlanningEditHandler = {
+    kind: "external-planning-edit",
+    detect: detectExternalPlanningEdit,
+    repair: repairExternalPlanningEdit,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/project-md.js

@@ -7,7 +7,7 @@
 import { existsSync } from "node:fs";
 import { getMilestone, isDbAvailable } from "../../gsd-db.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
-import { resolveMilestoneFile } from "../../paths.js";
+import { resolveMilestoneFile, resolveMilestonePath } from "../../paths.js";
 function milestoneHasContent(basePath, milestoneId) {
     const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
     const context = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
@@ -31,12 +31,25 @@ export function detectUnregisteredMilestoneDrift(_state, ctx) {
 }
 /**
  * Repair intentionally fails closed. The project-root DB is authoritative at
- * runtime; markdown-only milestones must be imported through an explicit
- * migration/recovery command so operators opt into changing canonical state.
+ * runtime; markdown-only milestones must be reconciled through an explicit,
+ * operator-controlled action so operators opt into changing canonical state.
+ *
+ * The hint deliberately leads with the *targeted*, non-destructive options. The
+ * common cause of this drift is a directory left under an old ID after a
+ * `unique_milestone_ids` rename, where the right fix is to rename (move) the
+ * directory — not a full DB reimport. `/gsd recover --confirm` is a destructive
+ * clear-and-reimport of the entire DB and is offered only as a last resort, so
+ * users do not reach for it expecting a targeted repair (see issue #826).
  */
-export function repairUnregisteredMilestone(record, _ctx) {
-    throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection. ` +
-        "Runtime reconciliation will not import markdown into the authoritative DB; run `/gsd recover --confirm` if this markdown should repopulate the database.");
+export function repairUnregisteredMilestone(record, ctx) {
+    const dir = resolveMilestonePath(ctx.basePath, record.milestoneId);
+    const dirHint = dir ?? `the .gsd directory for ${record.milestoneId}`;
+    throw new Error(`Milestone ${record.milestoneId} exists only as markdown projection ` +
+        "(on-disk ROADMAP/CONTEXT/SUMMARY with no authoritative DB row). " +
+        "Runtime reconciliation will not import markdown into the DB. Choose one:\n" +
+        `  • Rename: if this directory is the same milestone under an old ID (e.g. a unique_milestone_ids rename), move \`${dirHint}\` to the current ID's directory and re-run.\n` +
+        `  • Discard: if this milestone is no longer relevant, delete \`${dirHint}\` and re-run.\n` +
+        "  • Last resort: `/gsd recover --confirm` performs a destructive full DB clear-and-reimport — it does NOT do a targeted import and can replace or duplicate existing DB milestones.");
 }
 export const unregisteredMilestoneHandler = {
     kind: "unregistered-milestone",

package/dist/resources/extensions/gsd/state-reconciliation/drift/roadmap.js

@@ -40,6 +40,7 @@ function milestoneHasDivergence(basePath, milestoneId) {
     }
     const dbSlices = getMilestoneSlices(milestoneId);
     const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+    const dbSliceOrder = new Map(dbSlices.map((s, index) => [s.id, index]));
     const readySliceIds = getSlicesReadyForDivergenceCheck(milestoneId, dbSlices);
     if (dbSlices.length > 0 && readySliceIds.size === 0) {
         return false;
@@ -48,13 +49,12 @@ function milestoneHasDivergence(basePath, milestoneId) {
     for (let i = 0; i < roadmap.slices.length; i++) {
         const roadmapSlice = roadmap.slices[i];
         roadmapSliceIds.add(roadmapSlice.id);
-        const expectedSequence = i + 1;
         const dbSlice = dbSliceMap.get(roadmapSlice.id);
         if (!dbSlice)
             return true; // Roadmap has a slice the DB doesn't.
         if (!readySliceIds.has(dbSlice.id))
             continue;
-        if (dbSlice.sequence !== expectedSequence)
+        if (dbSliceOrder.get(dbSlice.id) !== i)
             return true;
         if (!arraysEqual(dbSlice.depends, roadmapSlice.depends))
             return true;

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-render.js

@@ -5,12 +5,12 @@
 // the detect+repair composition moves here. The previous repairStaleRenders
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapFromDb, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
-import { getMilestone, getSlice, setSliceSummaryMd } from "../../gsd-db.js";
-import { buildSliceFileName } from "../../paths.js";
+import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd, } from "../../gsd-db.js";
+import { ensureWorkflowDbForBase, } from "../../db-workspace.js";
+import { resolveSliceFile } from "../../paths.js";
 import { logWarning } from "../../workflow-logger.js";
+const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 // ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
 function detectStaleRenderDriftFromBasePath(basePath) {
     const entries = detectStaleRenders(basePath);
@@ -40,6 +40,17 @@ function isRepairableStaleRenderReason(reason) {
         (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
         reason.includes("UAT.md missing"));
 }
+function validationBlocker(state) {
+    if (state.phase !== "blocked")
+        return null;
+    return state.blockers.find((blocker) => VALIDATION_BLOCK_RE.test(blocker)) ?? null;
+}
+function isMilestoneSummaryMissing(record) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    return (record.reason.includes("SUMMARY.md missing") &&
+        (/^M\d+(?:\b|[-_:])/.test(record.reason) ||
+            /(?:^|\/)M\d+(?:-[a-z0-9]+)?-SUMMARY\.md$/i.test(normPath)));
+}
 function canonicalizeMilestoneId(dirSegment) {
     if (getMilestone(dirSegment))
         return dirSegment;
@@ -50,17 +61,31 @@ function canonicalizeMilestoneId(dirSegment) {
     const baseId = dirSegment.match(/^(M\d+)(?:$|-)/i)?.[1];
     if (baseId && getMilestone(baseId))
         return baseId;
+    // Flat-phase: e.g. 01-test → M001
+    const phaseMatch = dirSegment.match(/^(\d+)-/);
+    if (phaseMatch) {
+        const flatId = `M${String(parseInt(phaseMatch[1], 10)).padStart(3, "0")}`;
+        if (getMilestone(flatId))
+            return flatId;
+    }
     return suffixId ?? baseId ?? dirSegment;
 }
 function resolveRoadmapMilestoneIdFromPath(normPath) {
-    const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+    // Flat-phase: phases/NN-slug/NN-ROADMAP.md
+    // Legacy: milestones/MID/MID-ROADMAP.md
+    const milestoneMatch = normPath.match(/phases\/([^/]+)\//)
+        || normPath.match(/milestones\/([^/]+)\//);
     if (!milestoneMatch) {
         throw new Error(`stale-render drift: roadmap path missing milestone segment: ${normPath}`);
     }
     const fileMatch = normPath.match(/(?:^|\/)([^/]+)-ROADMAP\.md$/i);
+    // For flat-phase, derive milestone id from phase number prefix
+    const phaseNumMatch = milestoneMatch[1].match(/^(\d+)-/);
+    const phaseDerivedId = phaseNumMatch ? `M${String(parseInt(phaseNumMatch[1], 10)).padStart(3, "0")}` : null;
     const candidates = [
         fileMatch?.[1],
         milestoneMatch[1],
+        phaseDerivedId,
         fileMatch?.[1]?.match(/^(M\d+)/i)?.[1],
         milestoneMatch[1].match(/^(M\d+)/i)?.[1],
     ].filter((candidate) => !!candidate);
@@ -70,7 +95,16 @@ function resolveRoadmapMilestoneIdFromPath(normPath) {
     }
     return fileMatch?.[1] ?? milestoneMatch[1];
 }
+function ensureDbForStaleRenderRepair(basePath) {
+    return ensureWorkflowDbForBase(basePath);
+}
+function retryDbForStaleRenderRepair(basePath) {
+    return ensureWorkflowDbForBase(basePath, { refresh: true });
+}
 async function repairStaleRenderFromBasePath(record, basePath) {
+    if (!ensureDbForStaleRenderRepair(basePath)) {
+        throw new Error(`stale-render drift: database unavailable for repair (${basePath})`);
+    }
     const normPath = record.renderPath.replace(/\\/g, "/");
     const reason = record.reason;
     if (reason.includes("in roadmap")) {
@@ -78,12 +112,29 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("in plan")) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-PLAN.md
+        // Legacy: milestones/X/slices/Y/PLAN.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-PLAN/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
         }
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const wrote = await renderPlanCheckboxes(basePath, milestoneId, pathMatch[2], record.renderPath);
+        const sliceId = pathMatch[2] && pathMatch[3] && /^\d+$/.test(pathMatch[2])
+            ? `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`
+            : pathMatch[2];
+        let wrote = false;
+        try {
+            wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
+        }
+        catch (err) {
+            if (!retryDbForStaleRenderRepair(basePath))
+                throw err;
+            wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
+        }
+        if (!wrote && retryDbForStaleRenderRepair(basePath)) {
+            wrote = await renderPlanCheckboxes(basePath, milestoneId, sliceId, record.renderPath);
+        }
         if (!wrote) {
             throw new Error(`stale-render drift: plan re-render wrote nothing for ${milestoneId}/${pathMatch[2]} ` +
                 `(${record.renderPath}); slice has no tasks or its path is unresolvable`);
@@ -91,31 +142,77 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
+        // Flat-phase: phases/NN-slug/ (no tasks/ subdir, task summaries in phase dir)
+        // Legacy: milestones/X/slices/Y/tasks/
+        const pathMatch = normPath.match(/phases\/([^/]+)\//)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
         const taskMatch = reason.match(/^(T\d+)/);
         if (!pathMatch || !taskMatch) {
             throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
         }
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const wrote = await renderTaskSummary(basePath, milestoneId, pathMatch[2], taskMatch[1]);
+        // In flat-phase there's no slice segment in the path; find the task's slice from DB.
+        let sliceId;
+        if (pathMatch[2]) {
+            sliceId = pathMatch[2];
+        }
+        else {
+            // Flat-phase: scan milestone's slices for the task
+            let foundSliceId;
+            for (const s of getMilestoneSlices(milestoneId)) {
+                if (getSliceTasks(milestoneId, s.id).some(t => t.id === taskMatch[1])) {
+                    foundSliceId = s.id;
+                    break;
+                }
+            }
+            if (!foundSliceId) {
+                throw new Error(`stale-render drift: task ${taskMatch[1]} not found in any slice of ${milestoneId} (${record.renderPath})`);
+            }
+            sliceId = foundSliceId;
+        }
+        const wrote = await renderTaskSummary(basePath, milestoneId, sliceId, taskMatch[1]);
         if (!wrote) {
             throw new Error(`stale-render drift: task summary re-render wrote nothing for ` +
-                `${milestoneId}/${pathMatch[2]}/${taskMatch[1]} (${record.renderPath}); ` +
+                `${milestoneId}/${sliceId}/${taskMatch[1]} (${record.renderPath}); ` +
                 `task has no summary in DB or its slice path is unresolvable`);
         }
         return;
     }
     if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-SUMMARY.md or phases/NN-slug/NN-SUMMARY.md
+        // Legacy: milestones/X/slices/Y/SUMMARY.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-SUMMARY/)
+            || normPath.match(/phases\/([^/]+)\/(\d+)-SUMMARY/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
         }
-        const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const sliceId = pathMatch[2];
+        // Flat-phase: groups are (phaseDir, phaseNum, planNum) for NN-MM-SUMMARY,
+        // or (phaseDir, phaseNum) for NN-SUMMARY (phase-level). In the latter case,
+        // derive slice from the reason text which starts with S\d+.
+        // Legacy: groups are (milestoneDir, sliceDir).
+        let milestoneId;
+        let sliceId;
+        milestoneId = canonicalizeMilestoneId(pathMatch[1]);
+        if (pathMatch[3] && /^\d+$/.test(pathMatch[2])) {
+            // NN-MM-SUMMARY: pathMatch[3] is the plan number
+            sliceId = `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`;
+        }
+        else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+            // Legacy: pathMatch[2] is the slice dir name
+            sliceId = pathMatch[2];
+        }
+        else {
+            // NN-SUMMARY (phase-level): derive slice from reason
+            const reasonSlice = reason.match(/^(S\d+)/);
+            sliceId = reasonSlice ? reasonSlice[1] : "S01";
+        }
         const slice = getSlice(milestoneId, sliceId);
-        const uatPath = join(dirname(record.renderPath), buildSliceFileName(sliceId, "UAT"));
+        // Use resolveSliceFile so the UAT existence check matches the NN-MM-UAT.md
+        // name that renderSliceSummary actually writes (buildSliceFileName only yields MM-UAT.md).
+        const uatPath = resolveSliceFile(basePath, milestoneId, sliceId, "UAT");
         // renderSliceSummary writes both artifacts, so clear deleted UAT first.
-        if (slice?.full_uat_md && !existsSync(uatPath)) {
+        if (slice?.full_uat_md && !uatPath) {
             setSliceSummaryMd(milestoneId, sliceId, slice.full_summary_md ?? "", "");
         }
         const wrote = await renderSliceSummary(basePath, milestoneId, sliceId);
@@ -127,14 +224,26 @@ async function repairStaleRenderFromBasePath(record, basePath) {
         return;
     }
     if (reason.includes("UAT.md missing")) {
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        // Flat-phase: phases/NN-slug/NN-MM-UAT.md or phases/NN-slug/NN-UAT.md
+        // Legacy: milestones/X/slices/Y/UAT.md
+        const pathMatch = normPath.match(/phases\/([^/]+)\/(\d+)-(\d+)-UAT/)
+            || normPath.match(/phases\/([^/]+)\/(\d+)-UAT/)
+            || normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
         if (!pathMatch) {
             throw new Error(`stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`);
         }
-        // When UAT.md is removed from disk, mirror that intent by clearing stale
-        // persisted UAT content instead of rehydrating it back onto disk.
         const milestoneId = canonicalizeMilestoneId(pathMatch[1]);
-        const sliceId = pathMatch[2];
+        let sliceId;
+        if (pathMatch[3] && /^\d+$/.test(pathMatch[2])) {
+            sliceId = `S${String(parseInt(pathMatch[3], 10)).padStart(2, "0")}`;
+        }
+        else if (pathMatch[2] && /^S\d+/.test(pathMatch[2])) {
+            sliceId = pathMatch[2];
+        }
+        else {
+            const reasonSlice = reason.match(/(S\d+)/);
+            sliceId = reasonSlice ? reasonSlice[1] : "S01";
+        }
         const slice = getSlice(milestoneId, sliceId);
         if (!slice) {
             throw new Error(`stale-render drift: missing slice for UAT clear ${milestoneId}/${sliceId}`);
@@ -151,9 +260,19 @@ export function detectStaleRenderDrift(_state, ctx) {
 export async function repairStaleRender(record, ctx) {
     await repairStaleRenderFromBasePath(record, ctx.basePath);
 }
+export function staleRenderBlocker(record, ctx) {
+    const blocker = validationBlocker(ctx.state);
+    if (!blocker || !isMilestoneSummaryMissing(record))
+        return null;
+    return [
+        `Stale milestone summary render at ${record.renderPath} is blocked by milestone validation.`,
+        blocker,
+    ].join("\n");
+}
 export const staleRenderHandler = {
     kind: "stale-render",
     detect: detectStaleRenderDrift,
+    blocker: staleRenderBlocker,
     repair: repairStaleRender,
 };
 // ─── Legacy entry point ──────────────────────────────────────────────────────