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

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

@@ -6,10 +6,11 @@
 // 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 { 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, isDbAvailable, setSliceSummaryMd, } from "../../gsd-db.js";
+import { getWorkflowDatabasePath, openWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk, } from "../../db-workspace.js";
+import { gsdRoot, resolveSliceFile } from "../../paths.js";
 import { logWarning } from "../../workflow-logger.js";
 // ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
 function detectStaleRenderDriftFromBasePath(basePath) {
@@ -50,17 +51,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 +85,42 @@ function resolveRoadmapMilestoneIdFromPath(normPath) {
     }
     return fileMatch?.[1] ?? milestoneMatch[1];
 }
+function expectedDbPathForStaleRenderRepair(basePath) {
+    return join(gsdRoot(basePath), "gsd.db");
+}
+function ensureDbForStaleRenderRepair(basePath) {
+    const dbPath = expectedDbPathForStaleRenderRepair(basePath);
+    if (isDbAvailable() && getWorkflowDatabasePath() === dbPath)
+        return true;
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `stale-render repair could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
+function retryDbForStaleRenderRepair(basePath) {
+    const dbPath = expectedDbPathForStaleRenderRepair(basePath);
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        if (isDbAvailable() && getWorkflowDatabasePath() === dbPath && refreshWorkflowDatabaseFromDisk()) {
+            return true;
+        }
+        return openWorkflowDatabasePath(dbPath);
+    }
+    catch (err) {
+        logWarning("reconcile", `stale-render repair could not reopen DB: ${err.message}`);
+        return false;
+    }
+}
 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 +128,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 +158,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 +240,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}`);

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -29,16 +29,49 @@ const defaultDeps = {
  *   - any repair function throws within a pass, or
  *   - drift persists after the cap.
  */
-export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
+export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
+    const deps = { ...defaultDeps, ...partialDeps };
     const registry = deps.registry ?? DRIFT_REGISTRY;
     const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
     const repaired = [];
+    // Capture-on-first-read: infer .planning/ layout, import content into DB, and
+    // activate the compat marker. Skipped in dry-run mode to keep the reconcile
+    // pass fully read-only — no marker writes.
+    if (!deps.dryRun) {
+        const { capturePlanningCompatIfNeeded } = await import("../compat/planning-compat.js");
+        await capturePlanningCompatIfNeeded(basePath);
+    }
     for (let pass = 0; pass < MAX_PASSES; pass++) {
         deps.invalidateStateCache();
         const stateSnapshot = await deps.deriveState(basePath, deps.deriveStateOptions);
-        const ctx = { basePath, state: stateSnapshot };
+        const ctx = { basePath, state: stateSnapshot, dryRun: deps.dryRun };
         const detection = await detectAllDrift(stateSnapshot, ctx, registry);
         const drift = detection.records;
+        if (deps.dryRun && drift.length > 0) {
+            const wouldRepair = [];
+            const blockers = [...detection.detectBlockers];
+            for (const record of drift) {
+                const handler = registry.find((h) => h.kind === record.kind);
+                const blocker = handler?.blocker ? await handler.blocker(record, ctx) : null;
+                if (blocker) {
+                    blockers.push(blocker);
+                }
+                else {
+                    wouldRepair.push(record);
+                }
+            }
+            return {
+                ok: true,
+                stateSnapshot,
+                repaired: wouldRepair,
+                blockers: [
+                    ...new Set([
+                        ...(stateSnapshot.blockers ?? []),
+                        ...blockers,
+                    ]),
+                ],
+            };
+        }
         if (drift.length === 0) {
             return {
                 ok: true,
@@ -106,7 +139,7 @@ export async function reconcileBeforeDispatch(basePath, deps = defaultDeps) {
     // After MAX_PASSES, one more derive+detect to verify nothing persists.
     deps.invalidateStateCache();
     const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
-    const finalCtx = { basePath, state: finalState };
+    const finalCtx = { basePath, state: finalState, dryRun: deps.dryRun };
     const finalDetection = await detectAllDrift(finalState, finalCtx, registry);
     const persistent = finalDetection.records;
     if (persistent.length > 0) {

package/dist/resources/extensions/gsd/state-reconciliation/registry.js

@@ -4,6 +4,8 @@
 import { completionTimestampHandler } from "./drift/completion.js";
 import { artifactDbStatusDivergenceHandler, completedMilestoneReopenedHandler, diskSliceIdDivergenceHandler, } from "./drift/artifact-db.js";
 import { mergeStateHandler } from "./drift/merge-state.js";
+import { externalMarkdownEditHandler } from "./drift/external-markdown-edit.js";
+import { externalPlanningEditHandler } from "./drift/external-planning-edit.js";
 import { unregisteredMilestoneHandler } from "./drift/project-md.js";
 import { roadmapDivergenceHandler } from "./drift/roadmap.js";
 import { sketchFlagHandler } from "./drift/sketch-flag.js";
@@ -15,6 +17,16 @@ import { staleWorkerHandler } from "./drift/stale-worker.js";
 // by kind before invoking repair, so this is sound at runtime.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const DRIFT_REGISTRY = [
+    // ⚠ ORDER IS SIGNIFICANT for repairs within a single pass.
+    // external-markdown-edit MUST run before any handler that re-projects
+    // markdown from DB (stale-render, roadmap-divergence). If a DB-projection
+    // handler runs first it overwrites the gsd-core file and the subsequent
+    // external-markdown-edit repair imports the already-overwritten content —
+    // silently discarding the cross-tool edit. With external-markdown-edit first
+    // the DB is updated to reflect the gsd-core edit before stale-render
+    // re-renders, so the canonical re-projection preserves the edit's intent.
+    externalMarkdownEditHandler,
+    externalPlanningEditHandler,
     sketchFlagHandler,
     mergeStateHandler,
     staleRenderHandler,

package/dist/resources/extensions/gsd/state-transition-matrix.js

@@ -99,6 +99,44 @@ export const STATE_TRANSITION_MATRIX = [
 export function findTransition(from, event) {
     return STATE_TRANSITION_MATRIX.find((entry) => (entry.from === from || entry.from === "*") && entry.event === event);
 }
+/**
+ * Edge-keyed legality check for the Phase Transition Invariant (ADR-030).
+ * `advance()` derives the next Phase and asserts the (from → to) edge here.
+ *
+ * The matrix is an assertion, not a decision-maker — `deriveState` already
+ * chose the Phase. A self-edge is trivially legal (no transition to assert). An
+ * edge is legal when some matrix entry permits it, honoring the `*` wildcard
+ * rows (e.g. any → blocked via manual-block, any → executing via
+ * retryable-failure).
+ *
+ * Note: the matrix is currently a sparse hardening spec, not a complete
+ * legal-edge graph, so `advance()` consumes this in advisory mode (telemetry
+ * only). It must be expanded to cover every edge `deriveState` emits before
+ * enforcement flips on.
+ */
+export function isLegalEdge(from, to) {
+    if (from === to)
+        return true;
+    return STATE_TRANSITION_MATRIX.some((entry) => (entry.from === from || entry.from === "*") && entry.to === to);
+}
+/**
+ * Thrown when an illegal derived Phase edge survives reconciliation. Carries
+ * both endpoints so Recovery Classification can report them. Recognized by
+ * class in `classifyFailure` and mapped to the `illegal-transition` kind.
+ */
+export class IllegalPhaseTransitionError extends Error {
+    // Explicit fields, not constructor parameter properties — strip-types
+    // consumers (workspace-index subprocess, integration tests) reject the
+    // parameter-property syntax with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+    from;
+    to;
+    constructor(from, to) {
+        super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+        this.name = "IllegalPhaseTransitionError";
+        this.from = from;
+        this.to = to;
+    }
+}
 export function validateTransitionMatrix(requiredEvents) {
     const seen = new Set();
     const duplicateKeys = [];