@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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

@@ -6,8 +6,7 @@
 // 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,
@@ -16,14 +15,26 @@ 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 {
+  ensureWorkflowDbForBase,
+} from "../../db-workspace.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";
 
 type StaleRenderDrift = Extract<DriftRecord, { kind: "stale-render" }>;
 
+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: string): StaleRenderDrift[] {
@@ -61,6 +72,22 @@ function isRepairableStaleRenderReason(reason: string): boolean {
   );
 }
 
+function validationBlocker(state: GSDState): string | null {
+  if (state.phase !== "blocked") return null;
+  return state.blockers.find((blocker) => VALIDATION_BLOCK_RE.test(blocker)) ?? null;
+}
+
+function isMilestoneSummaryMissing(record: StaleRenderDrift): boolean {
+  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: string): string {
   if (getMilestone(dirSegment)) return dirSegment;
   const suffixId = dirSegment.match(/^(M\d+-[a-z0-9]{6})(?:$|-)/)?.[1];
@@ -70,11 +97,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 +119,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) {
@@ -96,10 +137,22 @@ function resolveRoadmapMilestoneIdFromPath(normPath: string): string {
   return fileMatch?.[1] ?? milestoneMatch[1];
 }
 
+function ensureDbForStaleRenderRepair(basePath: string): boolean {
+  return ensureWorkflowDbForBase(basePath);
+}
+
+function retryDbForStaleRenderRepair(basePath: string): boolean {
+  return ensureWorkflowDbForBase(basePath, { refresh: true });
+}
+
 async function repairStaleRenderFromBasePath(
   record: StaleRenderDrift,
   basePath: string,
 ): Promise<void> {
+  if (!ensureDbForStaleRenderRepair(basePath)) {
+    throw new Error(`stale-render drift: database unavailable for repair (${basePath})`);
+  }
+
   const normPath = record.renderPath.replace(/\\/g, "/");
   const reason = record.reason;
 
@@ -112,19 +165,44 @@ 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 wrote = await renderPlanCheckboxes(
-      basePath,
-      milestoneId,
-      pathMatch[2],
-      record.renderPath,
-    );
+    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]!;
+    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]} ` +
@@ -135,21 +213,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 +258,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 +306,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(
@@ -224,9 +357,22 @@ export async function repairStaleRender(
   await repairStaleRenderFromBasePath(record, ctx.basePath);
 }
 
+export function staleRenderBlocker(
+  record: StaleRenderDrift,
+  ctx: DriftContext,
+): string | null {
+  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: DriftHandler<StaleRenderDrift> = {
   kind: "stale-render",
   detect: detectStaleRenderDrift,
+  blocker: staleRenderBlocker,
   repair: repairStaleRender,
 };
 

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

@@ -15,7 +15,7 @@ import {
   ReconciliationFailedError,
   type ReconciliationFailureDetail,
 } from "./errors.js";
-import { DRIFT_REGISTRY } from "./registry.js";
+import { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES, type ReconciliationRepairPhase } from "./registry.js";
 import type {
   DriftContext,
   DriftHandler,
@@ -33,7 +33,7 @@ export type {
 } from "./types.js";
 export { ReconciliationFailedError } from "./errors.js";
 export type { ReconciliationFailureDetail } from "./errors.js";
-export { DRIFT_REGISTRY } from "./registry.js";
+export { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES, handlerPhaseIndex } from "./registry.js";
 
 const MAX_PASSES = 2;
 
@@ -59,19 +59,53 @@ 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 repairPhases = getRepairPhases(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,
@@ -89,28 +123,29 @@ export async function reconcileBeforeDispatch(
     const failures: ReconciliationFailureDetail[] = [];
     const blockers: string[] = [...detection.detectBlockers];
     let repairedThisPass = false;
-    for (const record of drift) {
-      const handler = registry.find((h) => h.kind === record.kind);
-      if (!handler) {
-        failures.push({
-          drift: record,
-          cause: new Error(
-            `No drift handler registered for kind "${record.kind}"`,
-          ),
-        });
-        continue;
-      }
-      const blocker = handler.blocker ? await handler.blocker(record, ctx) : null;
-      if (blocker) {
-        blockers.push(blocker);
-        continue;
-      }
-      try {
-        await handler.repair(record, ctx);
-        repaired.push(record);
-        repairedThisPass = true;
-      } catch (cause) {
-        failures.push({ drift: record, cause });
+    const repairedKindsThisPass = new Set<string>();
+
+    for (const phase of repairPhases) {
+      for (const record of drift) {
+        const recordKey = `${record.kind}:${JSON.stringify(record)}`;
+        if (repairedKindsThisPass.has(recordKey)) continue;
+
+        const handler = phase.handlers.find((h) => h.kind === record.kind);
+        if (!handler) continue;
+
+        const blocker = handler.blocker ? await handler.blocker(record, ctx) : null;
+        if (blocker) {
+          blockers.push(blocker);
+          continue;
+        }
+        try {
+          await handler.repair(record, ctx);
+          repaired.push(record);
+          repairedKindsThisPass.add(recordKey);
+          repairedThisPass = true;
+        } catch (cause) {
+          failures.push({ drift: record, cause });
+        }
       }
     }
 
@@ -143,7 +178,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;
 
@@ -183,6 +218,30 @@ export async function reconcileBeforeDispatch(
   };
 }
 
+function getRepairPhases(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registry: ReadonlyArray<DriftHandler<any>>,
+): ReadonlyArray<ReconciliationRepairPhase> {
+  const assigned = new Set<DriftHandler>();
+  const phases = RECONCILIATION_REPAIR_PHASES.map((phase) => {
+    const phaseKinds = new Set(phase.handlers.map((handler) => handler.kind));
+    const handlers = registry.filter((handler) => phaseKinds.has(handler.kind));
+    for (const handler of handlers) assigned.add(handler);
+    return { name: phase.name, handlers };
+  }).filter((phase) => phase.handlers.length > 0);
+
+  const unphasedHandlers = registry.filter((handler) => !assigned.has(handler));
+  if (unphasedHandlers.length === 0) return phases;
+
+  return [
+    ...phases,
+    {
+      name: "custom",
+      handlers: unphasedHandlers,
+    },
+  ];
+}
+
 interface DetectionOutcome {
   records: DriftRecord[];
   /** One blocker string per handler whose detect() threw. */

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

@@ -1,6 +1,5 @@
 // Project/App: gsd-pi
-// File Purpose: ADR-017 drift handler registry. Single source of truth for
-// the catalog. Tests can override per-call via ReconciliationDeps.registry.
+// File Purpose: ADR-017 drift handler registry and explicit repair phases.
 
 import { completionTimestampHandler } from "./drift/completion.js";
 import {
@@ -9,6 +8,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";
@@ -16,20 +17,46 @@ import { staleRenderHandler } from "./drift/stale-render.js";
 import { staleWorkerHandler } from "./drift/stale-worker.js";
 import type { DriftHandler } from "./types.js";
 
-// Each handler is parameterized over its specific DriftRecord variant for
-// internal type safety. The registry stores them under DriftHandler<any> so
-// handlers with disjoint repair parameter types coexist; the lifecycle matches
-// 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>> = [
-  sketchFlagHandler,
-  mergeStateHandler,
-  staleRenderHandler,
-  staleWorkerHandler,
-  unregisteredMilestoneHandler,
-  diskSliceIdDivergenceHandler,
-  roadmapDivergenceHandler,
-  completedMilestoneReopenedHandler,
-  artifactDbStatusDivergenceHandler,
-  completionTimestampHandler,
+export interface ReconciliationRepairPhase {
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  handlers: ReadonlyArray<DriftHandler<any>>;
+}
+
+/**
+ * Repairs run phase-by-phase; detection uses the flattened registry (all handlers).
+ * external-markdown-edit MUST complete before re-project handlers (stale-render,
+ * roadmap-divergence) so cross-tool edits are imported before DB re-projection.
+ */
+export const RECONCILIATION_REPAIR_PHASES: ReadonlyArray<ReconciliationRepairPhase> = [
+  {
+    name: "import-external-edits",
+    handlers: [externalMarkdownEditHandler, externalPlanningEditHandler],
+  },
+  {
+    name: "normalize-db",
+    handlers: [
+      sketchFlagHandler,
+      mergeStateHandler,
+      staleWorkerHandler,
+      unregisteredMilestoneHandler,
+      diskSliceIdDivergenceHandler,
+      completedMilestoneReopenedHandler,
+      artifactDbStatusDivergenceHandler,
+    ],
+  },
+  {
+    name: "re-project",
+    handlers: [staleRenderHandler, roadmapDivergenceHandler, completionTimestampHandler],
+  },
 ];
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const DRIFT_REGISTRY: ReadonlyArray<DriftHandler<any>> =
+  RECONCILIATION_REPAIR_PHASES.flatMap((phase) => phase.handlers);
+
+export function handlerPhaseIndex(kind: string): number {
+  return RECONCILIATION_REPAIR_PHASES.findIndex((phase) =>
+    phase.handlers.some((handler) => handler.kind === kind),
+  );
+}

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;
 }

package/src/resources/extensions/gsd/state-transition-matrix.ts

@@ -131,6 +131,48 @@ export function findTransition(
   );
 }
 
+/**
+ * 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: Phase, to: Phase): boolean {
+  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.
+  readonly from: Phase;
+  readonly to: Phase;
+
+  constructor(from: Phase, to: Phase) {
+    super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+    this.name = "IllegalPhaseTransitionError";
+    this.from = from;
+    this.to = to;
+  }
+}
+
 export function validateTransitionMatrix(requiredEvents: readonly string[]): MatrixValidationResult {
   const seen = new Set<string>();
   const duplicateKeys: string[] = [];