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

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

@@ -6,6 +6,8 @@
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
 
+import { join } from "node:path";
+
 import {
   detectStaleRenders,
   renderPlanCheckboxes,
@@ -13,7 +15,16 @@ import {
   renderSliceSummary,
   renderTaskSummary,
 } from "../../markdown-renderer.js";
-import { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd } from "../../gsd-db.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";
@@ -21,6 +32,9 @@ 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[] {
@@ -58,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];
@@ -107,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;
 
@@ -136,12 +178,31 @@ async function repairStaleRenderFromBasePath(
     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,
-      sliceId,
-      record.renderPath,
-    );
+    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]} ` +
@@ -296,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;
 
@@ -63,6 +63,7 @@ export async function reconcileBeforeDispatch(
 ): 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[] = [];
 
@@ -122,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 });
+        }
       }
     }
 
@@ -216,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 {
@@ -18,30 +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>> = [
-  // ⚠ 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,
-  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),
+  );
+}