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

package/src/resources/extensions/gsd/state-reconciliation/drift/external-planning-edit.ts

@@ -0,0 +1,180 @@
+// 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";
+import type { GSDState } from "../../types.js";
+import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
+
+type ExternalPlanningEditDrift = Extract<
+  DriftRecord,
+  { kind: "external-planning-edit" }
+>;
+
+function detectOne(
+  ctx: DriftContext,
+  entries: Record<string, { sha: string; entities: string[] }>,
+  passthrough: boolean,
+): ExternalPlanningEditDrift[] {
+  const records: ExternalPlanningEditDrift[] = [];
+  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: DriftContext,
+  projections: Record<string, { sha: string; entities: string[] }>,
+  passthrough: Record<string, { sha: string; entities: string[] }>,
+): ExternalPlanningEditDrift[] {
+  const planningDir = join(ctx.basePath, ".planning");
+  if (!existsSync(planningDir)) return [];
+
+  const records: ExternalPlanningEditDrift[] = [];
+  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: GSDState,
+  ctx: DriftContext,
+): Promise<ExternalPlanningEditDrift[]> {
+  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 as Error).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: ExternalPlanningEditDrift,
+  ctx: DriftContext,
+): Promise<void> {
+  // 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 as Error).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: DriftHandler<ExternalPlanningEditDrift> = {
+  kind: "external-planning-edit",
+  detect: detectExternalPlanningEdit,
+  repair: repairExternalPlanningEdit,
+};

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -9,7 +9,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";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -46,16 +46,29 @@ export function detectUnregisteredMilestoneDrift(
 
 /**
  * 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: UnregisteredMilestoneDrift,
-  _ctx: DriftContext,
+  ctx: DriftContext,
 ): void {
+  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. ` +
-      "Runtime reconciliation will not import markdown into the authoritative DB; run `/gsd recover --confirm` if this markdown should repopulate the database.",
+    `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.",
   );
 }
 

package/src/resources/extensions/gsd/state-reconciliation/drift/roadmap.ts

@@ -60,6 +60,7 @@ function milestoneHasDivergence(
 
   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;
@@ -69,11 +70,10 @@ function milestoneHasDivergence(
   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) return true;
+    if (dbSliceOrder.get(dbSlice.id) !== i) return true;
     if (!arraysEqual(dbSlice.depends, roadmapSlice.depends)) return true;
     if (isClosedStatus(dbSlice.status) !== roadmapSlice.done) return true;
   }

package/src/resources/extensions/gsd/state-reconciliation/drift/stale-render.ts

@@ -6,9 +6,6 @@
 // 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,
@@ -16,8 +13,8 @@ import {
   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 { resolveSliceFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
 import { logWarning } from "../../workflow-logger.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
@@ -70,11 +67,21 @@ function canonicalizeMilestoneId(dirSegment: string): string {
   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: string): string {
-  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}`,
@@ -82,11 +89,15 @@ function resolveRoadmapMilestoneIdFromPath(normPath: string): string {
   }
 
   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],
+    milestoneMatch[1]!.match(/^(M\d+)/i)?.[1],
   ].filter((candidate): candidate is string => !!candidate);
 
   for (const candidate of candidates) {
@@ -112,17 +123,23 @@ async function repairStaleRenderFromBasePath(
   }
 
   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 milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    const sliceId = pathMatch[2] && pathMatch[3] && /^\d+$/.test(pathMatch[2])
+      ? `S${String(parseInt(pathMatch[3]!, 10)).padStart(2, "0")}`
+      : pathMatch[2]!;
     const wrote = await renderPlanCheckboxes(
       basePath,
       milestoneId,
-      pathMatch[2],
+      sliceId,
       record.renderPath,
     );
     if (!wrote) {
@@ -135,21 +152,44 @@ async function repairStaleRenderFromBasePath(
   }
 
   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]);
+    const milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    // In flat-phase there's no slice segment in the path; find the task's slice from DB.
+    let sliceId: string;
+    if (pathMatch[2]) {
+      sliceId = pathMatch[2];
+    } else {
+      // Flat-phase: scan milestone's slices for the task
+      let foundSliceId: string | undefined;
+      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`,
       );
     }
@@ -157,18 +197,40 @@ async function repairStaleRenderFromBasePath(
   }
 
   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: string;
+    let sliceId: string;
+    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);
@@ -183,16 +245,26 @@ async function repairStaleRenderFromBasePath(
   }
 
   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];
+    const milestoneId = canonicalizeMilestoneId(pathMatch[1]!);
+    let sliceId: string;
+    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(

package/src/resources/extensions/gsd/state-reconciliation/index.ts

@@ -59,19 +59,52 @@ const defaultDeps: ReconciliationDeps = {
  */
 export async function reconcileBeforeDispatch(
   basePath: string,
-  deps: ReconciliationDeps = defaultDeps,
+  partialDeps: Partial<ReconciliationDeps> = {},
 ): Promise<ReconciliationResult> {
+  const deps: ReconciliationDeps = { ...defaultDeps, ...partialDeps };
   const registry = deps.registry ?? DRIFT_REGISTRY;
   const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
   const repaired: DriftRecord[] = [];
 
+  // 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: DriftContext = { basePath, state: stateSnapshot };
+    const ctx: DriftContext = { 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: DriftRecord[] = [];
+      const blockers: string[] = [...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,
@@ -143,7 +176,7 @@ export async function reconcileBeforeDispatch(
   // After MAX_PASSES, one more derive+detect to verify nothing persists.
   deps.invalidateStateCache();
   const finalState = await deps.deriveState(basePath, deps.deriveStateOptions);
-  const finalCtx: DriftContext = { basePath, state: finalState };
+  const finalCtx: DriftContext = { basePath, state: finalState, dryRun: deps.dryRun };
   const finalDetection = await detectAllDrift(finalState, finalCtx, registry);
   const persistent = finalDetection.records;
 

package/src/resources/extensions/gsd/state-reconciliation/registry.ts

@@ -9,6 +9,8 @@ import {
   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";
@@ -22,6 +24,16 @@ import type { DriftHandler } from "./types.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: ReadonlyArray<DriftHandler<any>> = [
+  // ⚠ 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/src/resources/extensions/gsd/state-reconciliation/types.ts

@@ -43,6 +43,21 @@ export type DriftRecord =
       kind: "missing-completion-timestamp";
       entity: "task" | "slice" | "milestone";
       ids: string[];
+    }
+  | {
+      kind: "external-markdown-edit";
+      projectionPath: string;       // relative to basePath, e.g. "m1/plan.md"
+      expectedSha: string;          // sha recorded in .compat.json
+      actualSha: string;            // freshly computed from disk
+      entities: string[];           // DB entity ids to re-import
+    }
+  | {
+      kind: "external-planning-edit";
+      projectionPath: string;       // relative to .planning/, e.g. "phases/01-foo/01-01-PLAN.md"
+      expectedSha: string;
+      actualSha: string;
+      entities: string[];
+      passthrough: boolean;         // true = content-only, no re-import, just refresh sha
     };
 
 /**
@@ -52,6 +67,8 @@ export type DriftRecord =
 export interface DriftContext {
   basePath: string;
   state: GSDState;
+  /** When true, detectors must not persist compat marker changes. */
+  dryRun?: boolean;
 }
 
 /**
@@ -111,4 +128,6 @@ export interface ReconciliationDeps {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   registry?: ReadonlyArray<DriftHandler<any>>;
   deriveStateOptions?: DeriveStateOptions;
+  /** When true, detect drift but do not run repairs (read-only preview). */
+  dryRun?: boolean;
 }