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

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

@@ -5,13 +5,12 @@
 // the detect+repair composition moves here. The previous repairStaleRenders
 // had zero callers in production code — wiring it through
 // reconcileBeforeDispatch closes that gap.
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapFromDb, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.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 { getMilestone, getMilestoneSlices, getSlice, getSliceTasks, setSliceSummaryMd, } from "../../gsd-db.js";
+import { ensureWorkflowDbForBase, } from "../../db-workspace.js";
+import { resolveSliceFile } from "../../paths.js";
 import { logWarning } from "../../workflow-logger.js";
+const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 // ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
 function detectStaleRenderDriftFromBasePath(basePath) {
     const entries = detectStaleRenders(basePath);
@@ -41,6 +40,17 @@ function isRepairableStaleRenderReason(reason) {
         (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
         reason.includes("UAT.md missing"));
 }
+function validationBlocker(state) {
+    if (state.phase !== "blocked")
+        return null;
+    return state.blockers.find((blocker) => VALIDATION_BLOCK_RE.test(blocker)) ?? null;
+}
+function isMilestoneSummaryMissing(record) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    return (record.reason.includes("SUMMARY.md missing") &&
+        (/^M\d+(?:\b|[-_:])/.test(record.reason) ||
+            /(?:^|\/)M\d+(?:-[a-z0-9]+)?-SUMMARY\.md$/i.test(normPath)));
+}
 function canonicalizeMilestoneId(dirSegment) {
     if (getMilestone(dirSegment))
         return dirSegment;
@@ -85,37 +95,11 @@ 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;
-    }
+    return ensureWorkflowDbForBase(basePath);
 }
 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;
-    }
+    return ensureWorkflowDbForBase(basePath, { refresh: true });
 }
 async function repairStaleRenderFromBasePath(record, basePath) {
     if (!ensureDbForStaleRenderRepair(basePath)) {
@@ -276,9 +260,19 @@ export function detectStaleRenderDrift(_state, ctx) {
 export async function repairStaleRender(record, ctx) {
     await repairStaleRenderFromBasePath(record, ctx.basePath);
 }
+export function staleRenderBlocker(record, ctx) {
+    const blocker = validationBlocker(ctx.state);
+    if (!blocker || !isMilestoneSummaryMissing(record))
+        return null;
+    return [
+        `Stale milestone summary render at ${record.renderPath} is blocked by milestone validation.`,
+        blocker,
+    ].join("\n");
+}
 export const staleRenderHandler = {
     kind: "stale-render",
     detect: detectStaleRenderDrift,
+    blocker: staleRenderBlocker,
     repair: repairStaleRender,
 };
 // ─── Legacy entry point ──────────────────────────────────────────────────────

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

@@ -6,9 +6,9 @@ import { clearParseCache as defaultClearParseCache } from "../files.js";
 import { clearPathCache } from "../paths.js";
 import { logWarning } from "../workflow-logger.js";
 import { ReconciliationFailedError, } from "./errors.js";
-import { DRIFT_REGISTRY } from "./registry.js";
+import { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES } from "./registry.js";
 export { ReconciliationFailedError } from "./errors.js";
-export { DRIFT_REGISTRY } from "./registry.js";
+export { DRIFT_REGISTRY, RECONCILIATION_REPAIR_PHASES, handlerPhaseIndex } from "./registry.js";
 const MAX_PASSES = 2;
 const defaultDeps = {
     invalidateStateCache: defaultInvalidate,
@@ -32,6 +32,7 @@ const defaultDeps = {
 export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
     const deps = { ...defaultDeps, ...partialDeps };
     const registry = deps.registry ?? DRIFT_REGISTRY;
+    const repairPhases = getRepairPhases(registry);
     const clearParseCache = deps.clearParseCache ?? defaultClearParseCache;
     const repaired = [];
     // Capture-on-first-read: infer .planning/ layout, import content into DB, and
@@ -88,27 +89,29 @@ export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
         const failures = [];
         const blockers = [...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();
+        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 });
+                }
             }
         }
         if (repairedThisPass) {
@@ -177,6 +180,28 @@ export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
         ],
     };
 }
+function getRepairPhases(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+registry) {
+    const assigned = new Set();
+    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,
+        },
+    ];
+}
 /**
  * Run every detector. A single detector throwing (e.g. a transient file read
  * error) must NOT abort the whole cycle and hide every later handler's drift —

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

@@ -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 { artifactDbStatusDivergenceHandler, completedMilestoneReopenedHandler, diskSliceIdDivergenceHandler, } from "./drift/artifact-db.js";
 import { mergeStateHandler } from "./drift/merge-state.js";
@@ -11,30 +10,35 @@ import { roadmapDivergenceHandler } from "./drift/roadmap.js";
 import { sketchFlagHandler } from "./drift/sketch-flag.js";
 import { staleRenderHandler } from "./drift/stale-render.js";
 import { staleWorkerHandler } from "./drift/stale-worker.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 = [
-    // ⚠ 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,
+/**
+ * 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 = [
+    {
+        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 = RECONCILIATION_REPAIR_PHASES.flatMap((phase) => phase.handlers);
+export function handlerPhaseIndex(kind) {
+    return RECONCILIATION_REPAIR_PHASES.findIndex((phase) => phase.handlers.some((handler) => handler.kind === kind));
+}